理解配置结构

OpenClaw 的主配置文件是 ~/.openclaw/openclaw.json。官方文档说明：如果文件不存在，OpenClaw 会使用安全默认值；真正需要配置时，通常是为了接渠道、控权限、设模型、开 sandbox、管理 session 或调整 Gateway。

新手不要从完整配置文件开始。先用 onboarding 跑通，再理解每一类配置为什么存在。

先理解配置管什么

openclaw.json 主要管这些事情：

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

这不是一个“越全越好”的文件。每多一类配置，就多一个排错和安全边界。

新手怎么改配置

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

推荐顺序：

1. 第一次用 onboarding。
2. 小改动用 openclaw config set。
3. 想看结构用 Control UI。
4. 已经理解 schema 时再直接编辑 JSON5。

不要把网上的一整份配置复制进来。OpenClaw 是严格 schema 校验，未知字段、类型错误和非法值都会让 Gateway 拒绝启动或拒绝 reload。

最小配置应该只表达最小意图

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

但最小配置不是“推荐直接照抄上线”。真实使用时，你还要根据平台文档配置 token、allowlist、DM policy、群组策略和 session。

新手要先问自己：

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

---

热加载和重启怎么理解

Gateway 会监听 openclaw.json，很多业务配置可以热加载，例如 channels、agents、models、hooks、cron、heartbeat、session、tools、browser、skills、MCP、UI 和 logging。

但 Gateway 自身基础设施类配置通常需要重启，例如端口、绑定地址、认证、TLS、HTTP 入口、discovery、canvasHost、plugins。

新手只要记住：保存配置后不等于一定生效。要看日志、health 和 doctor 输出。

密钥不要写进公开配置

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

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

缺失或空值导致加载失败，通常是好事。密钥没准备好时，不要让 Gateway 半启动。

配置坏了先做什么

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

推荐排障顺序：

1. 看 Gateway 是否还能启动诊断命令。
2. 运行 doctor。
3. 看日志里具体 schema path。
4. 回滚最近一次配置改动。
5. 只修一个字段，再验证。

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

新手常见坑

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

---

怎么判断配置健康

健康标准：

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

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

官方来源

• OpenClaw Configuration
• OpenClaw Configuration Reference
• OpenClaw Configuration examples
• OpenClaw Secrets management

最近更新：2026年5月4日