先关注后阅读，娇姐怕失去上进的你

文末娇姐整理openclaw所有文章链接

想了解娇姐点击文末链接

本文基于官方文档、官方字段参考、仓库实现、社区导出 schema 和生态案例交叉比对。遇到差异时采用三层原则：官方文档 > 本机导出 schema > 社区示例。

• docs.openclaw.ai/gateway/configuration（官方任务导向）
• docs.openclaw.ai/gateway/configuration-reference（官方字段级参考）
• github.com/openclaw/openclaw（实现细节与 issue）
• 社区 config.schema.json（枚举参考，版本会漂移）
• 生态示例（OpenRouter、Docker CN IM 等，仅对照）

1. 配置文件基础机制（必须先懂）

1.1 文件路径与格式

默认路径是 ~/.openclaw/openclaw.json。文件采用 JSON5，支持注释和尾逗号；也可通过 OPENCLAW_CONFIG_PATH 覆盖路径。

1.2 严格 Schema 校验

未知字段、类型不匹配、无效枚举值都可能导致 Gateway 拒绝启动。根级通常唯一例外是 $schema（用于 IDE 联想）。

openclaw doctoropenclaw doctor --fixopenclaw doctor --deep --yes

1.3 四种编辑入口

1.4 热加载机制

默认 gateway.reload.mode: "hybrid"。能热更新的就立即生效，必须重启的会自动重启。

2. 顶层配置结构：每个 key 是什么作用

下面是你给出的顶层块全量说明，按“业务价值最高”排序。所有字段都可选，省略即走默认值。

3. agents：核心中的核心

3.1 defaults.workspace

工作目录，承载 AGENTS.md、USER.md、SOUL.md、memory、工具产物等。你可以理解成 Agent 的“家目录”。

3.2 defaults.model / models / imageModel

3.3 defaults.heartbeat

定时心跳任务，适合日报、巡检提醒。字段包含 every、model、prompt、target、directPolicy。

3.4 defaults.compaction

上下文过长时自动压缩，避免 Token 爆掉。资料中共同确认的关键字段是 softThresholdTokens 和 model。

3.5 defaults.sandbox

沙箱隔离高风险工具调用。常见 mode：off、non-main、all；scope：session、agent、shared。

3.6 defaults 其他常用字段

• thinkingDefault: off/low/high
• elevatedDefault: off/full
• timeoutSeconds: 默认 600
• maxConcurrent: 默认 3
• userTimezone: 如 Asia/Shanghai
• subagents.maxConcurrent: 子 Agent 并发上限
• skills: 共享技能白名单，[] 表示禁用
• skipBootstrap: 是否跳过 Bootstrap prompt

3.7 agents.list 与 3.8 bindings

当你要把“家用”和“工作”隔离，或把不同账号路由给不同 Agent，就用 agents.list + bindings。匹配优先级通常是 peer > guildId/teamId > accountId > channel > 默认。

4. channels：消息渠道全量说明

4.1 通用策略

4.2 WhatsApp

重点字段：allowFrom（E.164 号码）、textChunkLimit、chunkMode、mediaMaxMb、sendReadReceipts、groups、accounts、defaultAccount。多账号最容易配置漏的是 defaultAccount。

4.3 Telegram

重点字段：botToken 或 tokenFile、streaming、replyToMode、webhookUrl、proxy、retry、configWrites。streaming=partial 会增加编辑请求次数，需关注限流。

4.4 Discord

重点字段：token、allowBots、historyLimit、textChunkLimit、threadBindings、actions、guilds。审核功能 moderation 常默认关闭，别误判权限。

4.5 Slack

重点字段：botToken（xoxb）、appToken（xapp）、signingSecret、nativeStreaming、typingReaction、thread.historyScope。Socket Mode 和 HTTP Mode 不能混配。

4.6 中国 IM（飞书/钉钉/企微/QQ）

这些通常依赖社区插件，字段以插件版本为准。常见核心字段分别是 appId/appSecret、clientId/clientSecret、robotCode、botId/secret。

5. gateway：网关配置项逐条解释

警告：Docker 中如果 bind 还是 loopback，做了 -p 映射也可能外部无法访问。容器场景通常要配 bind: "lan" 或 host 网络。

6. session：会话隔离与寿命管理

重点：多用户多渠道部署建议直接用 per-channel-peer，最稳，不会串会话。

7. models：自定义提供商与本地模型

典型用途：接 OpenAI 兼容网关、Ollama、LM Studio、自建代理。关键是 mode、providers.<id>.baseUrl、api 适配器。

8. tools：最关键安全边界

推荐最小权限思路：先 profile 选低，后续按需放开；deny 永远比 allow 优先；workspaceOnly 建议开启。

tools: {  profile: "coding",  deny: ["canvas", "browser"],  fs: { workspaceOnly: true },  exec: { timeoutSec: 60, backgroundMs: 10000 },  loopDetection: { enabled: true, maxSameToolCalls: 5 }}

9. env / secrets / auth：凭证体系全量说明

9.1 env.vars 与 shellEnv

env.vars 只在进程环境未定义时补齐，适合非敏感默认值；shellEnv 用于从登录 shell 继承环境变量。

9.2 ${ENV_VAR} 替换

配置内任意字符串可引用环境变量。变量缺失会报错，这能尽早暴露安全配置问题。

9.3 API key 优先级

9.4 SecretRef 来源

• source: env（环境变量）
• source: file（文件）
• source: exec（外部命令，如 Vault CLI）

10. cron / hooks：自动化与事件入口

10.1 cron

cron 块控制“运行器”，任务条目建议放到 agents.list[].crons[]。关键字段：enabled、maxConcurrentRuns、sessionRetention、runLog、retry、failureAlert。

10.2 hooks

关键字段：enabled、token、path、defaultSessionKey、allowRequestSessionKey、mappings。payload 来自外部，必须视为不可信输入。

警告：hooks.token 必须配置；allowUnsafeExternalContent 保持关闭；外部请求体不要直接喂高权限工具。

11. 其他常用模块（经常被忽略）

12. 生产参考配置（可直接改造）

{  identity: { name: "Clawd", theme: "helpful AI assistant" },  agents: {    defaults: {      workspace: "~/.openclaw/workspace",      userTimezone: "Asia/Shanghai",      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-4.1"]      },      heartbeat: { every: "2h", model: "openai/gpt-4.1-mini" },      compaction: { softThresholdTokens: 40000, model: "openai/gpt-4.1-mini" },      timeoutSeconds: 600,      maxConcurrent: 3    }  },  models: {    providers: {      anthropic: { apiKey: "${ANTHROPIC_API_KEY}" },      openai: { apiKey: "${OPENAI_API_KEY}" }    }  },  channels: {    defaults: { groupPolicy: "allowlist" },    whatsapp: {      dmPolicy: "allowlist",      allowFrom: ["+8613800138000"],      groups: { "*": { requireMention: true } }    },    telegram: {      enabled: true,      botToken: "${TELEGRAM_BOT_TOKEN}",      dmPolicy: "pairing",      streaming: "partial",      historyLimit: 50    }  },  gateway: {    bind: "loopback",    auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" },    reload: { mode: "hybrid", debounceMs: 300 }  },  session: {    dmScope: "per-channel-peer",    reset: { mode: "daily", atHour: 4, idleMinutes: 120 },    maintenance: { mode: "prune", pruneAfter: "30d", maxEntries: 500 }  },  tools: {    profile: "coding",    fs: { workspaceOnly: true },    exec: { timeoutSec: 60 },    loopDetection: { enabled: true, maxSameToolCalls: 5 }  },  cron: {    enabled: true,    maxConcurrentRuns: 2,    sessionRetention: "24h"  },  env: {    vars: { TZ: "Asia/Shanghai" },    shellEnv: { enabled: true }  },  logging: {    level: "info",    redactSensitive: true  }}

13. 安全最佳实践（生产必做）

14. CLI 配置命令速查（收藏即用）

# 查看配置openclaw config getopenclaw config get agents.defaults.workspaceopenclaw config get --json# 修改配置openclaw config set agents.defaults.heartbeat.every "2h"openclaw config set session.dmScope "per-channel-peer"# 删除配置项（回默认）openclaw config unset plugins.entries.brave.config.webSearch.apiKey# 导出 Schemaopenclaw config schema > config.schema.json# 诊断与修复openclaw doctoropenclaw doctor --fixopenclaw doctor --deep --yes# 安全审计openclaw security audit --deepgrep -r "sk-" ~/.openclaw/# 运行状态openclaw status --allopenclaw health --json --verboseopenclaw logs --follow --level warnopenclaw logs --json# Gateway 控制openclaw gateway startopenclaw gateway stopopenclaw gateway restart

重点：对小白最有价值的落地顺序是：先 schema，再 6 大核心块（agents/channels/gateway/session/models/tools），然后 doctor + health + status 三连验证。

一句话结论：openclaw.json 是 OpenClaw 的运行总开关。把配置当工程来维护，你的稳定性、安全性、成本都能显著提升。

关于openclaw资料包和系列文章