配置

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置文件。

如果文件不存在，OpenClaw 会使用安全的默认值。添加配置的常见原因：

连接频道并控制谁可以向机器人发送消息
设置模型、工具、沙箱或自动化（cron、hooks）
调整会话、媒体、网络或 UI

查看完整参考了解所有可用字段。

初次接触配置？ 从 openclaw onboard 开始进行交互式设置，或查看配置示例指南获取完整的可复制配置。

最小配置

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

编辑配置

openclaw onboard       # 完整设置向导
openclaw configure     # 配置向导

严格验证

OpenClaw 只接受完全符合模式的配置。未知键、格式错误的类型或无效值会导致 Gateway 拒绝启动。唯一的根级别例外是 $schema（字符串），因此编辑器可以附加 JSON Schema 元数据。

当验证失败时：

Gateway 不会启动
只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
运行 openclaw doctor 查看具体问题
运行 openclaw doctor --fix（或 --yes）应用修复

常见任务

配置热重载

Gateway 监视 ~/.openclaw/openclaw.json 并自动应用更改 — 大多数设置无需手动重启。

重载模式

模式	行为
`hybrid`（默认）	立即热应用安全更改。自动重启处理关键更改。
`hot`	仅热应用安全更改。当需要重启时记录警告 — 由您处理。
`restart`	任何配置更改时重启 Gateway，无论是否安全。
`off`	禁用文件监视。更改在下次手动重启时生效。

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

什么热应用 vs 什么需要重启

大多数字段可以热应用而无需停机。在 hybrid 模式下，需要重启的更改会自动处理。

类别	字段	需要重启？
频道	`channels.*`、`web`（WhatsApp）— 所有内置和扩展频道	否
代理和模型	`agent`、`agents`、`models`、`routing`	否
自动化	`hooks`、`cron`、`agent.heartbeat`	否
会话和消息	`session`、`messages`	否
工具和媒体	`tools`、`browser`、`skills`、`audio`、`talk`	否
UI 和杂项	`ui`、`logging`、`identity`、`bindings`	否
Gateway 服务器	`gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP）	是
基础设施	`discovery`、`canvasHost`、`plugins`	是

gateway.reload 和 gateway.remote 是例外 — 更改它们不会触发重启。

配置 RPC（编程更新）

控制平面写入 RPC（config.apply、config.patch、update.run）的速率限制为每个 deviceId+clientIp 每 60 秒 3 个请求。受限时候，RPC 返回 UNAVAILABLE 并附带 retryAfterMs。

环境变量

OpenClaw 从父进程读取环境变量，以及：

当前工作目录中的 .env（如果存在）
~/.openclaw/.env（全局后备）

两个文件都不会覆盖现有的环境变量。您也可以在配置中设置内联环境变量：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

查看环境了解完整的优先级和来源。

完整参考

有关完整的逐字段参考，请查看 配置参考。

相关：配置示例 · 配置参考 · Doctor