配置

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

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

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

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

最小配置

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

编辑配置

bash openclaw onboard # full onboarding flow openclaw configure # config wizard

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

直接编辑 ~/.openclaw/openclaw.json。Gateway(网关) 会监视该文件并自动应用更改（请参阅热重载）。

严格验证

验证失败时：

Gateway(网关) 无法启动
只有诊断命令有效 (openclaw doctor, openclaw logs, openclaw health, openclaw status)
运行 openclaw doctor 以查看确切的问题
运行 openclaw doctor --fix（或 --yes）以应用修复

常见任务

Set up a 渠道 (WhatsApp, Telegram, Discord, etc.)

每个渠道在 `channels.

` 下都有自己的配置部分。请参阅相应的渠道页面以获取设置步骤：

- [WhatsApp](/en/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/en/channels/telegram) — `channels.telegram`
- [Discord](/en/channels/discord) — `channels.discord`
- [Slack](/en/channels/slack) — `channels.slack`
- [Signal](/en/channels/signal) — `channels.signal`
- [iMessage](/en/channels/imessage) — `channels.imessage`
- [Google Chat](/en/channels/googlechat) — `channels.googlechat`
- [Mattermost](/en/channels/mattermost) — `channels.mattermost`
- [Microsoft Teams](/en/channels/msteams) — `channels.msteams`

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

```json5
{
  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"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

agents.defaults.models 定义模型目录并充当 /model 的允许列表。
模型引用使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
agents.defaults.imageMaxDimensionPx 控制转录/工具图像的缩小比例（默认为 1200）；较低的值通常在包含大量屏幕截图的运行中减少视觉令牌的使用。
请参阅模型 CLI 以在聊天中切换模型，并参阅模型故障转移以了解身份轮换和备用行为。
对于自定义/自托管提供商，请参阅参考文档中的自定义提供商。

控制谁可以向机器人发送消息

私信访问是通过 dmPolicy 按渠道控制的：

"pairing"（默认）：未知发送者将获得一次性配对代码以进行批准
"allowlist"：仅 allowFrom 中的发送者（或配对的允许存储）
"open"：允许所有入站私信（需要 allowFrom: ["*"]）
"disabled"：忽略所有私信

对于群组，请使用 groupPolicy + groupAllowFrom 或特定于渠道的允许列表。

请参阅完整参考文档了解每个渠道的详细信息。

设置群组聊天提及控制

群组消息默认为 需要提及。按代理配置模式：

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

元数据提及：原生 @-提及（WhatsApp 点击提及，Telegram @bot 等）
文本模式：mentionPatterns 中的安全正则模式
请参阅完整参考文档了解渠道特定覆盖和自聊模式。

调整网关渠道健康监控

控制网关重启看起来陈旧的渠道的积极程度：

{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}

设置 gateway.channelHealthCheckMinutes: 0 以全局禁用健康监控重启。
channelStaleEventThresholdMinutes 应大于或等于检查间隔。
使用 `channels.

.healthMonitor.enabled或channels.

.accounts.

.healthMonitor.enabled` 为单个渠道或账户禁用自动重启，而不禁用全局监控器。 - 参见 Health Checks 了解操作调试，以及 full reference 了解所有字段。

配置会话和重置

会话控制对话连续性和隔离：

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

dmScope： main (共享) | per-peer | per-channel-peer | per-account-channel-peer
threadBindings：线程绑定会话路由的全局默认值（Discord 支持 /focus、/unfocus、/agents、/session idle 和 /session max-age）。
参见 Session Management 了解范围、身份链接和发送策略。
参见 full reference 了解所有字段。

启用沙箱隔离

在隔离的 Docker 容器中运行代理会话：

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

首先构建镜像： scripts/sandbox-setup.sh

参见沙箱隔离了解完整指南，以及 full reference 了解所有选项。

为官方 iOS 版本启用基于中继的推送

基于中继的推送在 openclaw.json 中配置。

在网关配置中进行设置：

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

CLI 等效项：

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

此项配置的作用：

允许网关通过外部中继发送 push.test、唤醒轻推和重连唤醒。
使用配对的 iOS 应用转发的注册范围发送授权。网关不需要部署范围的中继令牌。
将每个基于中继的注册绑定到该 iOS 应用所配对的网关身份，因此其他网关无法重复使用已存储的注册。
将本地/手动 iOS 版本保留在直接 APNs 上。基于中继的发送仅适用于通过中继注册的官方分发版本。
必须与官方/TestFlight iOS 版本中内置的中继基础 URL 匹配，以便注册和发送流量到达同一中继部署。

端到端流程：

安装使用相同中继基础 URL 编译的官方/TestFlight iOS 版本。
在网关上配置 gateway.push.apns.relay.baseUrl。
将 iOS 应用与网关配对，并允许节点和操作员会话连接。
iOS 应用获取网关身份，使用 App Attest 和应用收据向中继注册，然后将基于中继的 push.apns.register 负载发布到配对的网关。
网关存储中继句柄和发送授权，然后将它们用于 push.test、唤醒轻推和重连唤醒。

操作说明：

如果您将 iOS 应用切换到不同的网关，请重新连接应用，以便其发布绑定到该网关的新中继注册。
如果您发布指向不同中继部署的新 iOS 版本，应用将刷新其缓存的中继注册，而不是重复使用旧的中继源。

兼容性说明：

OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可用作临时环境变量覆盖。
OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍然是仅限环回开发的应急方案；请勿在配置中持久化 HTTP 中继 URL。

请参阅 iOS 应用了解端到端流程，并参阅身份验证和信任流程了解中继安全模型。

设置心跳（定期检查）

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

every: 持续时间字符串 (30m, 2h)。设置为 0m 以禁用。
target: last | none | `

(例如discord, matrix, telegram, 或 whatsapp) - directPolicy: allow(默认) 或block` 用于私聊风格的心跳目标 - 查看 Heartbeat 了解完整指南。

配置定时任务

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

sessionRetention: 从 sessions.json 中清理已完成的独立运行会话 (默认 24h；设置为 false 以禁用)。
runLog: 根据大小和保留行数清理 `cron/runs/

.jsonl`。 - 查看 Cron jobs 了解功能概述和 CLI 示例。

设置 Webhooks (hooks)

在 Gateway(网关) 上启用 HTTP webhook 端点：

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

安全说明：

将所有 hook/webhook 负载内容视为不受信任的输入。
保持不安全内容绕过标志为禁用状态 (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent)，除非在进行严格限制范围的调试。
对于由 hook 驱动的代理，建议使用强大的现代模型层级和严格的工具策略 (例如，在可能的情况下仅使用消息传递加上沙箱隔离)。

查看 full reference 了解所有映射选项和 Gmail 集成。

配置多代理路由

使用独立的工作空间和会话运行多个隔离的代理：

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

有关绑定规则和每个代理的访问配置文件，请参阅 Multi-Agent 和完整参考。

将配置拆分为多个文件 ($include)

使用 $include 来组织大型配置：

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

单个文件：替换包含的对象
文件数组：按顺序深度合并（后者优先）
同级键：在包含之后合并（覆盖包含的值）
嵌套包含：最多支持 10 层深度
相对路径：相对于包含文件解析
错误处理：针对丢失的文件、解析错误和循环包含提供清晰的错误信息

配置热重载

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`、 `logging`、 `identity`、 `bindings`	否
Gateway(网关) 服务器	`gateway.*` (端口、绑定、认证、Tailscale、TLS、HTTP)	是
基础设施	`discovery`、`canvasHost`、`plugins`	是

配置 RPC (程序化更新)

config.apply (full replace)

验证 + 写入完整配置并在一步内重启 Gateway(网关)。

参数:

raw (string) — 整个配置的 JSON5 载荷
baseHash (可选) — 来自 config.get 的配置哈希（配置存在时必需）
sessionKey (可选) — 重启后唤醒 ping 的会话密钥
note (可选) — 重启哨兵的备注
restartDelayMs (可选) — 重启前的延迟（默认 2000）

当一个重启请求已经挂起/进行中时，后续请求会被合并，并且在重启周期之间应用 30 秒的冷却时间。

openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "

”, “sessionKey”: “agent:main:whatsapp:direct:+15555550123” }’ ```

config.patch (partial update)

将部分更新合并到现有配置中（JSON 合并补丁语义）：

对象递归合并
null 删除一个键
数组替换

参数：

raw (string) — 仅包含要更改的键的 JSON5
baseHash (required) — 来自 config.get 的配置哈希
sessionKey, note, restartDelayMs — 同 config.apply

重启行为与 config.apply 一致：合并挂起的重启，且重启周期之间有 30 秒的冷却时间。

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "

” }’ ```

环境变量

OpenClaw 从父进程读取环境变量，外加：

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

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

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

Shell env import (optional)

如果启用且预期键名未设置，OpenClaw 将运行您的登录 shell 并仅导入缺失的键：

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

等效环境变量： OPENCLAW_LOAD_SHELL_ENV=1

Env var substitution in config values

在任何配置字符串值中使用 ${VAR_NAME} 引用环境变量：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

规则：

仅匹配大写名称： [A-Z_][A-Z0-9_]*
缺失/空的变量在加载时报错
使用 $${VAR} 进行转义以输出字面量
在 $include 文件中有效
内联替换： "${BASE}/v1" → "https://api.example.com/v1"

Secret refs (env, file, exec)

对于支持 SecretRef 对象的字段，您可以使用：

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRef 的详细信息（包括 secrets.providers 用于 env/file/exec）请参阅 Secrets Management。支持的凭证路径列于 SecretRef Credential Surface。

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

完整参考

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