理解配置结构

OpenClaw 的主配置文件是 ~/.openclaw/openclaw.json。它不是“所有字段都填满才专业”的大表，而是 Gateway、Agent、Channel、tools、models、sandbox、automation 的运行契约。

1. 先把配置理解成运行契约

openclaw.json 管的不是一个功能，而是多组边界：

• Agent：workspace、skills、模型、bootstrap、sandbox。
• Channel：WhatsApp、Telegram、Discord、Slack 等入口。
• Session：不同人、不同群、不同账号的上下文隔离。
• Tools 和 plugins：Agent 能调用哪些能力。
• Gateway：端口、认证、Control UI、日志、热加载。
• Automation：heartbeat、cron、hooks。

如果文件不存在，OpenClaw 会使用 safe defaults（安全默认值）。真正需要配置，通常是因为你要接渠道、控访问、设模型、开 sandbox、调 session 或加自动化。

flowchart TD
    Config["openclaw.json"]
    Gateway["Gateway 基础设施"]
    Agent["Agent 工作单元"]
    Channel["Channel 消息入口"]
    Tools["Tools / Plugins"]
    Automation["Automation"]
    Security["访问与密钥边界"]

    Config --> Gateway
    Config --> Agent
    Config --> Channel
    Config --> Tools
    Config --> Automation
    Config --> Security

    style Config fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Security fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Agent fill:#dcfce7,stroke:#22c55e,stroke-width:2px

2. openclaw.json 必须是真实文件

官方最新配置文档特别强调：active config path 必须是 regular file（普通文件）。把 ~/.openclaw/openclaw.json 做成 symlink（符号链接）不适合 OpenClaw 自己写配置，因为 atomic write（原子写入）可能替换路径，而不是保留 symlink。

如果你把配置放在默认状态目录之外，应该用：

OPENCLAW_CONFIG_PATH=/path/to/real/openclaw.json

3. 新手怎么改配置

官方提供几种入口：openclaw onboard、openclaw configure、openclaw config get/set/unset、Control UI，以及直接编辑文件。

推荐顺序：

1. 第一次用 onboarding。
2. 小改动用 openclaw config set。
3. 想看结构用 Control UI。
4. 需要查字段约束时用 openclaw config schema 或 config.schema.lookup。
5. 已经理解 schema 时再直接编辑 JSON5。

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

Control UI 会从 live config schema 渲染表单，还能显示字段 title / description 等 docs metadata。对 Agent 或自动化工具来说，config.schema.lookup 是写配置前的第一站。

4. strict schema 不是限制，是保护

OpenClaw 只接受完全匹配 schema 的配置。未知字段、类型错误、非法值都会让 Gateway 拒绝启动；根级例外只有 $schema 字符串，方便编辑器挂 JSON Schema metadata。

这听起来严格，但对一个能调用工具、接消息、处理密钥的系统来说，这是保护。

配置校验失败时，优先跑：

openclaw doctor
openclaw config validate
openclaw doctor --fix

5. 最小配置只表达最小意图

官方最小例子通常表达两个核心意图：给 Agent 一个 workspace，给某个 channel 一个受控入口。

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
    },
  },
}

这不是“推荐照抄上线”的完整配置。真实使用时，你还要根据平台文档配置 token、allowlist、DM policy、群组策略、session、tools 和模型。

新手每次改配置前先问：

• 我接的是哪个渠道。
• 谁可以发消息给它。
• 群组是否必须 mention。
• Agent 在哪个 workspace 工作。
• 这个入口能用哪些 tools 和 skills。
• 这次改动能不能单独验证。

6. 热加载和重启怎么理解

Gateway 会监听 openclaw.json，很多配置可以自动应用。默认 reload mode 是 hybrid：安全改动热应用，关键基础设施改动自动重启。

常见 reload mode：

新手只要记住：保存文件不等于已经生效。要看 logs、health、doctor 和 Gateway 状态。

7. 密钥不要写进公开配置

OpenClaw 会读取父进程环境变量，也会读取当前工作目录 .env 和 ~/.openclaw/.env。这些文件不会覆盖已经存在的环境变量。

配置字符串里可以引用环境变量：

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

但环境变量引用不是加密。涉及 token、API key、Gateway auth、模型 key、OAuth 时，不要把明文写进教程仓、公开 workspace 或截图里。

8. 配置坏了先做什么

配置坏了不要先删文件重来。官方诊断入口包括 doctor、logs、health、status、config validate。

推荐排障顺序：

1. 看 Gateway 是否还能启动诊断命令。
2. 运行 openclaw config validate。
3. 运行 openclaw doctor。
4. 看日志里具体 schema path。
5. 需要自动修复时再跑 openclaw doctor --fix。
6. 回滚最近一次配置改动。
7. 只修一个字段，再验证。

如果你一次改了十个字段，就很难判断真正坏在哪里。

flowchart TD
    Broken["配置出错"]
    Validate["openclaw config validate"]
    Doctor["openclaw doctor"]
    Logs["openclaw logs"]
    Fix["openclaw doctor --fix"]
    Small["只修一个字段"]
    Status["openclaw gateway status"]

    Broken --> Validate
    Validate --> Doctor
    Doctor --> Logs
    Logs --> Fix
    Fix --> Small
    Small --> Status

    style Broken fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Small fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Status fill:#dcfce7,stroke:#22c55e,stroke-width:2px

9. 新手常见坑

• 直接复制完整配置，里面的字段自己并不理解。
• 把配置文件做成 symlink，又让 OpenClaw 自己写配置。
• 把明文密钥放进 openclaw.json。
• 以为 workspace 是安全沙箱。
• 配置 open 入口后没有 session 和 tools 限制。
• 保存文件后不看 reload 日志。
• 一次改十几个字段，导致诊断没有锚点。

10. 怎么判断配置健康

健康标准：

• openclaw doctor 没有关键配置错误。
• openclaw health 能反映 Gateway 当前状态。
• 每个 channel 都有明确访问控制。
• 每个 Agent 都有明确 workspace。
• 密钥来自环境变量或安全凭据，不在公开文件里。
• 改动范围小，能通过日志解释为什么生效。

配置的目标是让 OpenClaw 可运行、可审计、可恢复，而不是把所有字段填满。

11. 本章自检

1. 为什么不建议把 openclaw.json 做成 symlink？
2. strict schema 校验失败时，Gateway 会怎么处理？
3. 哪些配置通常热加载，哪些通常需要重启？

12. 接下来去哪

13. 官方资料

• Configuration
• Configuration reference
• Configuration examples
• Secrets management
• Environment variables