OpenClaw Gateway 配置完全指南-05r

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置文件。如果文件不存在，OpenClaw 会使用安全的默认配置。

为什么需要配置？

连接渠道并控制谁可以发送消息
设置模型、工具、Sandbox 或自动化（Cron、Hooks）
调整会话、媒体、网络或 UI 设置

Gateway 配置

最小配置示例

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

编辑配置的方式

1. 交互式向导

openclaw onboard       # 完整引导流程
openclaw configure    # 配置向导

2. CLI 命令

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

3. Control UI

打开 http://127.0.0.1:18789，使用 Config 标签页。Control UI 会从配置模式渲染表单，也提供原始 JSON 编辑器。

4. 直接编辑

直接编辑 ~/.openclaw/openclaw.json。Gateway 会监视文件并自动应用更改（热重载）。

严格验证

警告： OpenClaw 只接受完全匹配模式的配置。未知的键、格式错误的类型或无效的值会导致 Gateway 拒绝启动。

验证失败时：

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

常见任务

设置渠道

每个渠道都有自己的配置部分 channels.<provider>：

WhatsApp — channels.whatsapp
Telegram — channels.telegram
Discord — channels.discord
Slack — channels.slack
iMessage — channels.imessage

所有渠道共享相同的 DM 策略模式：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}

选择和配置模型

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.2"],
      },
    },
  },
}