openclaw.json 配置架构完整参考手册
配置文件路径：
~/.openclaw/openclaw.json官方文档：docs.openclaw.ai/gateway/configuration-reference
格式说明
配置文件使用 JSON5 格式——支持注释和末尾逗号，普通 JSON 同样有效。所有字段均为可选，未填写时 OpenClaw 使用安全默认值。
查看当前配置的 JSON Schema：
openclaw config schema
验证配置合法性：
openclaw config validate
一、顶层结构总览
{
// 身份信息
identity: { ... },
// 环境变量
env: { ... },
// 鉴权配置（profile 元数据，密钥在 auth-profiles.json）
auth: { ... },
// Gateway 运行参数
gateway: { ... },
// 日志
logging: { ... },
// 消息格式和行为
messages: { ... },
// 路由和队列
routing: { ... },
// 会话生命周期
session: { ... },
// Agent 默认配置和多 Agent 列表
agents: { ... },
// 多 Agent 路由
multiAgent: { ... },
// 频道配置（WhatsApp / Telegram / Discord / Slack / ...）
channels: { ... },
// 工具策略和自定义提供商
tools: { ... },
// MCP 服务器
mcp: { ... },
// 模型目录行为
models: { ... },
// 技能配置
skills: { ... },
// 插件配置
plugins: { ... },
// Talk 模式（语音）
talk: { ... },
// Web/WebSocket 接入层（WhatsApp Baileys）
web: { ... },
}
二、identity — 身份信息
{
identity: {
name: "Clawd", // Agent 显示名称
theme: "helpful assistant", // 角色主题（注入 system prompt）
emoji: "🦞", // 头像 emoji
},
}
三、env — 环境变量
{
env: {
// 直接写在顶层的键值对会注入为环境变量
OPENROUTER_API_KEY: "sk-or-...",
// 也可以写在 vars 子块
vars: {
GROQ_API_KEY: "gsk-...",
GEMINI_API_KEY: "...",
},
// 从宿主机 Shell 环境继承变量
shellEnv: {
enabled: true,
timeoutMs: 15000, // Shell 环境读取超时
},
},
}
四、auth — 鉴权配置
密钥实际存储在 auth-profiles.json，这里只存 profile 元数据和优先顺序。
{
auth: {
profiles: {
"anthropic:default": { provider: "anthropic", mode: "api_key" },
"anthropic:work": { provider: "anthropic", mode: "api_key" },
"openai:default": { provider: "openai", mode: "api_key" },
"openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
},
// 每个提供商的 profile 使用顺序（优先级从前到后）
order: {
anthropic: ["anthropic:default", "anthropic:work"],
openai: ["openai:default"],
"openai-codex": ["openai-codex:personal"],
},
},
}
五、gateway — Gateway 运行参数
{
gateway: {
mode: "local", // 必填，必须为 "local"，否则 Gateway 拒绝启动
port: 18789, // WebSocket 监听端口
bind: "loopback", // 绑定模式：loopback | lan | tailnet | auto | custom
auth: "token", // 鉴权方式：token | password
// 频道健康监控
channelHealthCheckMinutes: 5,
channelStaleEventThresholdMinutes: 30,
channelMaxRestartsPerHour: 10,
// 节点配对
nodes: {
pairing: {
// 可信 CIDR 自动批准（谨慎使用）
autoApproveCidrs: ["192.168.1.0/24"],
},
},
},
}
六、logging — 日志配置
{
logging: {
level: "info", // 文件日志级别：silent|fatal|error|warn|info|debug|trace
file: "/tmp/openclaw/openclaw.log",
consoleLevel: "info", // 控制台日志级别
consoleStyle: "pretty", // pretty | json
redactSensitive: "tools", // 敏感信息脱敏范围
},
}
七、messages — 消息格式
{
messages: {
messagePrefix: "[openclaw]", // 发送消息前缀
responsePrefix: ">", // 回复前缀
ackReaction: "👀", // 收到消息时的 emoji 回应
ackReactionScope: "group-mentions", // off | all | group-mentions
// TTS 配置（见 talk 章节）
tts: { ... },
},
}
八、routing — 路由与队列
{
routing: {
// 群聊 @ 触发规则
groupChat: {
mentionPatterns: ["@openclaw", "openclaw"],
historyLimit: 50,
},
// 消息队列策略
queue: {
mode: "collect", // off | collect | debounce
debounceMs: 1000, // 去抖延迟（ms）
cap: 20, // 队列最大深度
drop: "summarize", // 超限处理：summarize | drop | error
// 按频道覆盖队列模式
byChannel: {
whatsapp: "collect",
telegram: "collect",
discord: "collect",
slack: "collect",
},
},
},
}
九、session — 会话生命周期
{
session: {
scope: "per-sender", // 会话 key 策略
dmScope: "per-channel-peer", // 多用户收件箱推荐使用此项
// 自动重置规则
reset: {
mode: "daily", // off | daily | idle | manual
atHour: 4, // daily 模式下每天几点重置
idleMinutes: 60, // idle 模式下闲置多久重置
},
// 按频道覆盖重置策略
resetByChannel: {
discord: { mode: "idle", idleMinutes: 10080 }, // 7 天
},
resetTriggers: ["/new", "/reset"],
// 会话存储路径
store: "~/.openclaw/agents/default/sessions/sessions.json",
// 会话存储维护策略
maintenance: {
mode: "warn", // off | warn | prune
pruneAfter: "30d",
maxEntries: 500,
rotateBytes: "10mb",
resetArchiveRetention: "30d",
maxDiskBytes: "500mb",
highWaterBytes: "400mb", // 触发清理的高水位（默认 maxDiskBytes 的 80%）
},
typingIntervalSeconds: 5,
// 消息发送策略
sendPolicy: {
default: "allow",
rules: [
{ action: "deny", match: { channel: "discord", chatType: "group" } },
],
},
// Discord 线程绑定
threadBindings: {
enabled: true,
},
// 上下文压缩策略（compaction）
compaction: {
mode: "auto", // auto | manual | off
targetTokens: 40000,
},
},
}
十、agents — Agent 配置
10.1 agents.defaults — 全局默认值
{
agents: {
defaults: {
// 工作区路径
workspace: "~/.openclaw/workspace",
repoRoot: "~/Projects/openclaw", // 可选，system prompt 中显示的仓库根目录
// 模型配置
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"],
},
// 视觉模型（image 工具路径）
imageModel: {
primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
},
// 图片生成模型
imageGenerationModel: {
primary: "openai/gpt-image-2",
},
// 视频生成模型
videoGenerationModel: {
primary: "qwen/wan2.6-t2v",
},
// PDF 处理模型
pdfModel: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
// 模型别名（支持 /model 命令使用别名切换）
models: {
"anthropic/claude-opus-4-6": { alias: "opus" },
"anthropic/claude-sonnet-4-6": { alias: "sonnet" },
"openai/gpt-5.4": { alias: "gpt" },
},
// 模型全局参数
params: {
cacheRetention: "long", // 提示词缓存保留策略
},
// 模型行为默认值
thinkingDefault: "low", // off | minimal | low | medium | high | xhigh
verboseDefault: "off", // off | on | full
reasoningDefault: "off", // off | on | stream
elevatedDefault: "on", // off | on | ask | full
toolProgressDetail: "explain",
// 超时与限制
timeoutSeconds: 600,
mediaMaxMb: 5,
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
contextTokens: 200000,
maxConcurrent: 3, // 最大并发 agent 运行数
// 图片质量
imageMaxDimensionPx: 1200, // 最长边像素上限
imageQuality: "auto", // auto | efficient | balanced | high
// 时区和时间格式
userTimezone: "America/Shanghai",
timeFormat: "auto", // auto | 12 | 24
// 技能白名单（默认，可被 agents.list[].skills 覆盖）
skills: ["github", "weather"],
// 工作区 bootstrap 文件控制
skipBootstrap: false,
skipOptionalBootstrapFiles: ["SOUL.md"], // 跳过特定可选文件
contextInjection: "continuation-skip", // always | continuation-skip | never
bootstrapMaxChars: 20000,
bootstrapTotalMaxChars: 60000,
bootstrapPromptTruncationWarning: "always", // off | once | always
// 启动时上下文（/new /reset 后的首次注入）
startupContext: {
enabled: true,
applyOn: ["new", "reset"],
dailyMemoryDays: 2,
maxFileBytes: 16384,
maxFileChars: 1200,
maxTotalChars: 2800,
},
// 上下文大小限制
contextLimits: {
memoryGetMaxChars: 12000,
memoryGetDefaultLines: 120,
postCompactionMaxChars: 1800,
// toolResultMaxChars: 32000, // 高级工具结果上限，通常不需要手动设置
},
// 流式输出控制
blockStreamingDefault: "off", // off | on
blockStreamingBreak: "text_end",
blockStreamingChunk: {
minChars: 800,
maxChars: 1200,
breakPreference: "paragraph",
},
blockStreamingCoalesce: {
idleMs: 1000,
},
// 打字延迟模拟（仿人类节奏）
humanDelay: {
mode: "natural", // off | natural
},
typingIntervalSeconds: 5,
// 心跳任务
heartbeat: {
every: "30m",
model: "anthropic/claude-sonnet-4-6",
target: "last", // 发送到最近活跃会话
directPolicy: "allow", // allow | block
to: "+15555550123",
prompt: "HEARTBEAT",
ackMaxChars: 300,
},
// 记忆搜索（向量嵌入）
memorySearch: {
provider: "gemini",
model: "gemini-embedding-001",
remote: {
apiKey: "${GEMINI_API_KEY}",
},
extraPaths: ["../team-docs", "/srv/shared-notes"],
},
// CLI 后端（文本回退，无工具调用）
cliBackends: {
"claude-cli": {
command: "/opt/homebrew/bin/claude",
},
},
// 沙箱隔离
sandbox: {
mode: "non-main", // off | non-main | all
scope: "session", // session | run
workspaceRoot: "~/.openclaw/sandboxes",
docker: {
image: "openclaw-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
user: "1000:1000",
},
browser: {
enabled: false,
},
},
},
// 多 Agent 列表
list: [
{
id: "main",
default: true,
// 各字段不填则继承 agents.defaults
thinkingDefault: "high",
skills: ["github", "weather", "search"], // 覆盖 defaults.skills
},
{
id: "coder",
workspace: "~/.openclaw/workspace-coder",
model: { primary: "anthropic/claude-opus-4-6" },
skills: ["github"], // 只用 github skill，不继承 defaults
},
{
id: "locked-down",
skills: [], // 不使用任何 skill
},
],
},
}
10.2 multiAgent — 多 Agent 路由
{
multiAgent: {
// 路由绑定（通常由 openclaw agents bind 管理，不推荐手动编辑）
bindings: [
{
agentId: "coder",
channel: "telegram",
accountId: "ops",
},
],
},
}
十一、channels — 频道配置
11.0 通用说明
每个频道的配置块存在时自动启动（除非 enabled: false）。
DM 策略（dmPolicy）：
| 值 | 行为 |
|---|---|
pairing（默认） | 未知发送者收到一次性配对码，Owner 审批后方可通信 |
allowlist | 仅 allowFrom 列表内的发送者 |
open | 允许所有人（需设 allowFrom: ["*"]） |
disabled | 忽略所有入站 DM |
群组策略（groupPolicy）：
| 值 | 行为 |
|---|---|
allowlist（默认） | 仅白名单群组 |
open | 跳过群组白名单检查（@ 触发规则仍生效） |
disabled | 屏蔽所有群组消息 |
11.1 channels.defaults — 全局频道默认值
11.2 Feishu（飞书）
{
channels: {
lark: {
enabled: true,
appId: "cli_XXXXXXXXXX",
appSecret: "YOUR_APP_SECRET",
verificationToken: "YOUR_VERIFICATION_TOKEN",
encryptKey: "YOUR_ENCRYPT_KEY",
dmPolicy: "allowlist",
allowFrom: ["ou_xxxxxxxx"],
groups: {
"*": { requireMention: true },
},
},
},
}
十二、tools — 工具策略
12.1 工具 profile
{
tools: {
profile: "coding", // minimal | coding | messaging | full
},
}
| Profile | 包含工具 |
|---|---|
minimal | 仅 session_status |
coding | group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image 等 |
messaging | group:messaging, sessions_list, sessions_history, sessions_send, session_status |
full | 无限制（同不设置） |
12.2 工具组
| 组名 | 包含工具 |
|---|---|
group:runtime | exec, process, code_execution |
group:fs | read, write, edit, apply_patch |
group:sessions | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
group:memory | memory_search, memory_get |
group:web | web_search, x_search, web_fetch |
group:ui | browser, canvas |
group:automation | heartbeat_respond, cron, gateway |
group:messaging | message |
group:media | image, image_generate, music_generate, video_generate, tts |
group:plugins | 所有已加载插件（含 MCP）的工具 |
12.3 工具白名单/黑名单与 Elevated 权限
{
tools: {
profile: "coding",
allow: ["web_search", "group:fs"],
deny: ["exec"],
// Elevated 模式白名单（/elevated on 和沙箱需要）
elevated: {
allowFrom: {
"*": ["user1"],
telegram: ["tg:123456789"],
},
},
// 媒体工具配置
media: {
audio: {
enabled: true,
maxBytes: 20971520, // 20 MB
models: [
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
],
timeoutSeconds: 120,
},
video: {
enabled: true,
maxBytes: 52428800, // 50 MB
models: [
{ provider: "google", model: "gemini-3-flash-preview" },
],
},
},
// 沙箱工具策略
sandbox: {
tools: [
"group:fs",
"group:runtime",
"bundle-mcp", // 允许沙箱访问 MCP 工具
],
},
},
}
12.4 自定义提供商和 base URL
{
models: {
providers: {
// SiliconFlow（硅基流动）
"siliconflow": {
type: "openai-compatible",
baseUrl: "https://api.siliconflow.cn/v1",
apiKey: "${SILICONFLOW_API_KEY}",
models: [
{ id: "Qwen/Qwen3-8B", alias: "qwen3" },
{ id: "deepseek-ai/DeepSeek-R1" },
],
},
// Alibaba DashScope（阿里云百炼）
"dashscope": {
type: "openai-compatible",
baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
apiKey: "${DASHSCOPE_API_KEY}",
models: [
{ id: "qwen-max", alias: "qwen" },
{ id: "qwen-plus" },
{ id: "qwen-turbo" },
],
},
// 本地 Ollama
"ollama": {
type: "openai-compatible",
baseUrl: "http://localhost:11434/v1",
apiKey: "ollama",
models: [
{ id: "qwen2.5:7b", alias: "qwen-local" },
{ id: "deepseek-r1:7b" },
],
// 按需启动本地模型服务
localService: {
command: "ollama",
args: ["serve"],
healthUrl: "http://localhost:11434",
readyPattern: "Listening on",
},
},
},
// 定价 bootstrap（关闭可加快 Gateway 启动）
pricing: {
enabled: false,
},
},
}
十三、mcp — MCP 服务器配置
{
mcp: {
sessionIdleTtlMs: 600000, // 空闲 TTL（10 分钟），设 0 禁用空闲驱逐
servers: {
// stdio 类型（本地命令）
"context7": {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-fetch"],
enabled: true,
// 工具过滤
toolFilter: {
include: ["search_*"],
exclude: ["admin_*"],
},
},
// 远程 HTTP 类型
"remote-docs": {
url: "https://example.com/mcp",
transport: "streamable-http", // streamable-http | sse
timeout: 20, // 请求超时（秒）
connectTimeout: 5, // 连接超时（秒）
supportsParallelToolCalls: true,
headers: {
Authorization: "Bearer ${MCP_TOKEN}",
},
// OAuth 鉴权（运行 openclaw mcp login <name> 存储 token）
auth: "oauth",
oauth: {
scope: "docs.read",
},
// 双向 TLS
sslVerify: true,
clientCert: "/path/to/client.crt",
clientKey: "/path/to/client.key",
},
// 仅对特定 agent 暴露的 MCP（Codex 投影控制）
"outlook": {
command: "node",
args: ["./outlook-mcp.js"],
codex: {
agents: ["main"],
defaultToolsApprovalMode: "approve", // auto | prompt | approve
},
},
},
},
}
十四、skills — 技能配置
{
skills: {
// 捆绑技能的白名单（不在列表中的捆绑技能不加载）
allowBundled: ["gemini", "peekaboo"],
// 加载路径
load: {
extraDirs: ["~/Projects/agent-scripts/skills"],
allowSymlinkTargets: ["~/Projects/manager/skills"],
},
// 安装偏好
install: {
preferBrew: true,
nodeManager: "npm", // npm | pnpm | yarn | bun
allowUploadedArchives: false,
},
// 全局技能大小限制
limits: {
maxSkillsPromptChars: 18000,
},
// 单个技能配置
entries: {
"image-lab": {
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
},
"peekaboo": { enabled: true },
"sag": { enabled: false },
},
},
}
十五、plugins — 插件配置
{
plugins: {
enabled: true,
allow: ["voice-call", "open-prose"], // 白名单（仅加载列表内插件）
deny: [], // 黑名单（deny 优先于 allow）
// 额外加载路径
load: {
paths: ["~/Projects/oss/voice-call-plugin"],
},
// 单个插件配置
entries: {
"voice-call": {
enabled: true,
hooks: {
allowPromptInjection: false,
},
config: { provider: "twilio" },
},
"memory-core": {
config: {
dreaming: {
enabled: true,
mode: "rem",
},
},
},
},
},
}
注意：插件配置变更需要重启 Gateway 才能生效。
十六、talk — 语音 / Talk 模式
{
talk: {
consultThinkingLevel: "low", // Talk 语音实时咨询时的思考级别
consultFastMode: false, // 是否对 Talk 咨询启用快速模式
speechLocale: "zh-CN", // BCP 47 语音识别语言（iOS/macOS）
silenceTimeoutMs: 700, // 停顿超时（macOS/Android 默认 700ms，iOS 900ms）
realtime: {
consultRouting: "gateway", // 实时 Talk 转录的路由回退策略
},
},
}
十七、完整最小化配置示例
// ~/.openclaw/openclaw.json
{
identity: {
name: "OpenClaw",
emoji: "🦞",
},
gateway: {
mode: "local",
},
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-sonnet-4-6",
},
},
},
channels: {
telegram: {
enabled: true,
botToken: "YOUR_BOT_TOKEN",
allowFrom: ["tg:YOUR_USER_ID"],
},
},
}
十八、完整生产配置示例（国内部署）
{
identity: {
name: "我的助手",
theme: "helpful assistant",
emoji: "🤖",
},
gateway: {
mode: "local",
port: 18789,
bind: "loopback",
},
env: {
DASHSCOPE_API_KEY: "sk-...",
SILICONFLOW_API_KEY: "sk-...",
},
logging: {
level: "info",
consoleLevel: "warn",
consoleStyle: "pretty",
},
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
userTimezone: "Asia/Shanghai",
timeFormat: "24",
model: {
primary: "dashscope/qwen-max",
fallbacks: ["siliconflow/deepseek-ai/DeepSeek-R1"],
},
models: {
"dashscope/qwen-max": { alias: "qwen" },
"dashscope/qwen-plus": { alias: "plus" },
},
thinkingDefault: "low",
timeoutSeconds: 300,
skills: ["search"],
},
list: [
{
id: "main",
default: true,
},
],
},
models: {
providers: {
"dashscope": {
type: "openai-compatible",
baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
apiKey: "${DASHSCOPE_API_KEY}",
models: [
{ id: "qwen-max", alias: "qwen" },
{ id: "qwen-plus", alias: "plus" },
{ id: "qwen-turbo", alias: "turbo" },
],
},
"siliconflow": {
type: "openai-compatible",
baseUrl: "https://api.siliconflow.cn/v1",
apiKey: "${SILICONFLOW_API_KEY}",
models: [
{ id: "deepseek-ai/DeepSeek-R1", alias: "r1" },
{ id: "Qwen/Qwen3-8B", alias: "qwen3" },
],
},
},
pricing: { enabled: false },
},
channels: {
telegram: {
enabled: true,
botToken: "YOUR_BOT_TOKEN",
dmPolicy: "allowlist",
allowFrom: ["tg:YOUR_USER_ID"],
groups: {
"*": { requireMention: true },
},
network: {
autoSelectFamily: true,
dnsResultOrder: "ipv4first",
},
},
lark: {
enabled: true,
appId: "cli_XXXXXXXXXX",
appSecret: "YOUR_APP_SECRET",
dmPolicy: "allowlist",
allowFrom: ["ou_xxxxxxxx"],
},
},
tools: {
profile: "coding",
},
session: {
dmScope: "per-channel-peer",
reset: {
mode: "daily",
atHour: 5,
},
},
}
附录：配置分块索引
| 配置块 | 主要用途 | 详细文档 |
|---|---|---|
identity | Agent 名称、emoji、主题 | — |
env | 环境变量注入 | — |
auth | 鉴权 profile 元数据和顺序 | Authentication |
gateway | 端口、绑定、健康监控 | Configuration reference |
logging | 日志级别和输出格式 | Logging |
messages | 消息前缀、ACK 表情 | Config — agents |
routing | 群聊触发、消息队列 | Config — agents |
session | 会话 key、重置策略、存储维护 | Config — agents |
agents | 模型、技能、沙箱、多 Agent | Config — agents |
channels | 各平台接入配置 | Config — channels |
tools | 工具 profile、白名单、媒体 | Config — tools |
models | 自定义提供商、定价 | Config — tools |
mcp | MCP 服务器定义 | MCP |
skills | 技能加载、安装、限制 | Skills |
plugins | 插件加载、白/黑名单 | Plugins |
talk | 语音咨询参数 | Talk mode |
整理自 OpenClaw 官方文档，版本：2026.6.1