配置与运维

配置

网关（Gateway）会从 ~/.openclaw/openclaw.json 读取一个可选的 JSON5 配置文件。如果没有这个文件，也没关系——OpenClaw 会使用安全的默认值运行。

你通常会因为以下原因需要添加或修改配置：

  • 连接各种频道，控制谁能给机器人发消息
  • 设置模型、工具、沙箱或自动化功能（定时任务、钩子（hooks））
  • 调整会话、媒体、网络或界面相关的参数

完整的字段说明请查阅配置参考文档。

💡 第一次接触配置？ 建议先运行 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 },
  },
}

哪些能热应用，哪些需要重启

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

类别字段需要重启？
频道channels.*、web（WhatsApp）—— 所有内置和扩展频道否
智能体与模型agent、agents、models、routing否
自动化hooks、cron、agent.heartbeat否
会话与消息session、messages否
工具与媒体tools、browser、skills、audio、talk否
界面与杂项ui、logging、identity、bindings否
网关服务器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 诊断工具

网关运行手册配置参考文档