配置

OpenClaw 会从 ~/.openclaw/openclaw.json 读取可选的 JSON5 (JSON5 supports comments and trailing commas) 配置。

如果该文件缺失，OpenClaw 会使用安全的默认值。添加配置的常见原因包括：

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

所有可用字段请参阅完整参考。

刚接触配置？ 从 openclaw onboard 开始进行交互式设置，或者查看 Configuration Examples 指南，获取完整的可复制粘贴配置。

最小配置

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

编辑配置

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

严格校验

OpenClaw 只接受完全符合 schema 的配置。未知键、类型格式错误或无效值都会导致 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 },
  },
}

哪些可以热应用，哪些需要重启

大多数字段都可以无停机热应用。在 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.*`（port、bind、auth、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-..." },
  },
}

有关完整优先级和来源，请参阅 Environment。

完整参考

有关逐字段的完整参考，请参阅 Configuration Reference。

相关内容：Configuration Examples · Configuration Reference · Doctor

配置

On this page