Gateway 配置概览

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置文件（支持注释和尾随逗号）。文件缺失时使用安全默认值。

配置路径必须是普通文件，不支持符号链接布局。如需将配置放在默认状态目录之外，通过 OPENCLAW_CONFIG_PATH 直接指向真实文件。

最小配置

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

编辑配置的方式

方式	命令/操作
交互向导	`openclaw onboard` / `openclaw configure`
CLI 单行	`openclaw config get/set/unset <path>`
Control UI	访问 `http://127.0.0.1:18789`，使用 Config 标签页
直接编辑	编辑 `~/.openclaw/openclaw.json`，Gateway 自动热重载

严格校验

OpenClaw 只接受完全符合 schema 的配置。未知字段、类型错误或无效值会导致 Gateway 拒绝启动。唯一的根级例外是 $schema 字段。

校验失败时：

Gateway 不启动
只有诊断命令可用：openclaw doctor、openclaw logs、openclaw health
运行 openclaw doctor --fix 自动修复

热重载模式

模式	行为
`hybrid`（默认）	安全变更立即热应用，关键变更自动重启
`hot`	仅热应用安全变更，需要重启时只记录警告
`restart`	任何配置变更都重启 Gateway
`off`	禁用文件监听，变更需手动重启生效

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

哪些变更需要重启

类别	字段	需要重启
Channels	`channels.*`	否
Agent & 模型	`agents`, `models`	否
自动化	`hooks`, `cron`	否
Session & 消息	`session`, `messages`	否
Gateway 服务器	`gateway.*`（端口、绑定、认证）	是
基础设施	`discovery`, `plugins`	是

常用任务速查

设置 DM 访问策略

{
  channels: {
    telegram: {
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],
    },
  },
}

pairing（默认）：未知发送者获得一次性配对码
allowlist：仅允许 allowFrom 中的发送者
open：允许所有入站 DM（需 allowFrom: ["*"]）
disabled：忽略所有 DM

配置模型

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

配置 Session

{
  session: {
    dmScope: "per-channel-peer",  // 多用户推荐
    reset: { mode: "daily", atHour: 4 },
  },
}

启用沙箱

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

拆分配置文件（$include）

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
}

单文件：替换包含对象
文件数组：按顺序深度合并（后者优先）
嵌套 include：最多支持 10 层
路径必须在 openclaw.json 所在目录内

环境变量

OpenClaw 从父进程、CWD .env 和 ~/.openclaw/.env 读取环境变量（均不覆盖已有变量）。

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
  },
}

在配置值中引用环境变量：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
}

规则：只匹配大写名称 [A-Z_][A-Z0-9_]*，缺失变量在加载时报错，用 $${VAR} 转义。

Config RPC（程序化更新）

openclaw gateway call config.get --params '{}'  # 获取当前配置和 hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { ... } } }",
  "baseHash": "<hash>"
}'

config.schema.lookup：查看单个路径的 schema 节点
config.get：获取当前快照和 hash
config.patch：部分更新（JSON merge patch）
config.apply：替换整个配置

控制面写操作限速：每 deviceId+clientIp 每 60 秒 3 次请求。

Wiki AI

目录