配置（Configuration）

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5（支持注释和尾逗号）配置。

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

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

所有可用字段的完整参考见完整参考文档。

提示： 刚开始配置？ 从 openclaw onboard 开始交互式设置，或查看配置示例获取完整的复制粘贴配置。

最简配置

json5

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

编辑配置

交互式向导

bash

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

CLI（单行命令）

bash

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

控制 UI

打开 http://127.0.0.1:18789 并使用 Config 标签。控制 UI 从配置 schema 渲染表单，提供 Raw JSON 编辑器作为备用。

直接编辑

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

严格验证

警告： OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 拒绝启动。唯一的根级例外是 $schema（字符串），供编辑器附加 JSON Schema 元数据。

验证失败时：

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

常见任务

设置渠道（WhatsApp、Telegram、Discord 等）

每个渠道在 channels.<provider> 下有自己的配置部分。查看专属渠道页面获取设置步骤：

WhatsApp — channels.whatsapp
Telegram — channels.telegram
Discord — channels.discord
Slack — channels.slack
Signal — channels.signal
iMessage — channels.imessage
Google Chat — channels.googlechat
Mattermost — channels.mattermost
Microsoft Teams — channels.msteams

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

json5

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

选择和配置模型

设置主模型和可选的降级模型：

json5

{
  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 命令的 allowlist。
模型引用使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
agents.defaults.imageMaxDimensionPx 控制转录/工具图片的最大像素缩放（默认 1200）；截图密集的运行适当降低通常能减少视觉 token 用量。
在聊天中切换模型见模型 CLI，auth 轮换和降级行为见模型降级。
自定义/自托管提供商，见参考文档中的自定义提供商。

控制谁可以向 bot 发消息

每个渠道通过 dmPolicy 控制 DM 访问：

"pairing"（默认）：未知发送者收到一次性配对码，需要审批
"allowlist"：只允许 allowFrom 中的发送者（或已配对的 allow store）
"open"：允许所有入站 DM（需要 allowFrom: ["*"]）
"disabled"：忽略所有 DM

群组消息使用 groupPolicy + groupAllowFrom 或渠道特定的 allowlist。

每渠道详情见完整参考。

设置群聊 @提及门控

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

json5

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

元数据提及：原生 @-提及（WhatsApp 点击提及、Telegram @bot 等）
文本模式：mentionPatterns 中的安全正则模式
见完整参考中的每渠道覆盖和自聊模式。

调整 Gateway 渠道健康监控

控制 Gateway 重启看起来停滞的渠道的激进程度：

json5

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

设置 gateway.channelHealthCheckMinutes: 0 全局禁用健康监控重启。
channelStaleEventThresholdMinutes 应大于或等于检查间隔。
使用 channels.<provider>.healthMonitor.enabled 或 channels.<provider>.accounts.<id>.healthMonitor.enabled 为单个渠道或账户禁用自动重启，而不禁用全局监控。
运维调试见健康检查，所有字段见完整参考。

配置会话和重置

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

json5

{
  session: {
    dmScope: "per-channel-peer",  // 多用户时推荐
    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）。
会话范围、身份链接和发送策略见会话管理。
所有字段见完整参考。

启用沙盒

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

json5

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

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

完整指南见沙盒，所有选项见完整参考。

为官方 iOS 构建启用 relay 推送

Relay 推送在 openclaw.json 中配置。

在 gateway 配置中设置：

json5

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // 可选，默认：10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

CLI 等效命令：

bash

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

此功能的作用：

让 Gateway 通过外部 relay 发送 push.test、唤醒 nudge 和重连唤醒。
使用由已配对 iOS 应用转发的注册范围内的发送授权。Gateway 不需要全局 relay token。
将每个 relay 支持的注册绑定到 iOS 应用配对的 Gateway 身份，防止其他 Gateway 复用存储的注册。
本地/手动 iOS 构建保持直接 APNs。Relay 支持的发送仅适用于通过 relay 注册的官方分发版本。
必须与官方/TestFlight iOS 构建中内置的 relay URL 匹配。

端到端流程：

安装使用相同 relay URL 编译的官方/TestFlight iOS 构建。
在 Gateway 上配置 gateway.push.apns.relay.baseUrl。
将 iOS 应用与 Gateway 配对，让 node 和 operator 会话都连接。
iOS 应用获取 Gateway 身份，使用 App Attest 和应用收据向 relay 注册，然后将 relay 支持的 push.apns.register payload 发布到已配对的 Gateway。
Gateway 存储 relay handle 和发送授权，用于 push.test、唤醒 nudge 和重连唤醒。

运维注意：

如果将 iOS 应用切换到不同 Gateway，重新连接应用使其发布绑定到该 Gateway 的新 relay 注册。
如果发布新的 iOS 构建指向不同 relay，应用会刷新缓存的 relay 注册而不是复用旧 relay 来源。

兼容性说明：

OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍作为临时 env 覆盖有效。
OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍是仅限回环的开发逃生舱；不要在配置中持久化 HTTP relay URL。

端到端流程见 iOS App，relay 安全模型见认证和信任流程。

设置心跳（周期性检入）

json5

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

every：持续时间字符串（30m、2h）。设置 0m 禁用。
target：last | whatsapp | telegram | discord | none
directPolicy：DM 类型心跳目标的 allow（默认）或 block
完整指南见心跳。

配置 cron 任务

json5

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

sessionRetention：从 sessions.json 清理已完成的独立运行会话（默认 24h；设置 false 禁用）。
runLog：按大小和保留行数清理 cron/runs/<jobId>.jsonl。
功能概览和 CLI 示例见 Cron 任务。

设置 Webhook（hooks）

在 Gateway 上启用 HTTP webhook 端点：

json5

{
  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 payload 内容视为不可信输入。
保持不安全内容绕过标志禁用（hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent），除非在严格范围内调试。
对于 hook 驱动的 agent，优先使用强大的现代模型层级和严格的工具策略（例如仅消息加上可行时的沙盒）。

所有映射选项和 Gmail 集成见完整参考。

配置多 Agent 路由

运行多个具有独立工作空间和会话的隔离 agent：

json5

{
  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" } },
  ],
}

绑定规则和每 agent 访问 profile 见多 Agent 和完整参考。

将配置拆分为多个文件（$include）

使用 $include 组织大型配置：

json5

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

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

配置热重载

Gateway 监视 ~/.openclaw/openclaw.json 并自动应用变更——大多数设置无需手动重启。

重载模式

模式	行为
`hybrid`（默认）	立即热应用安全更改。自动重启关键更改。
`hot`	仅热应用安全更改。需要重启时记录警告——你来处理。
`restart`	任何配置更改都重启 Gateway，无论是否安全。
`off`	禁用文件监视。更改在下次手动重启时生效。

json5

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

哪些字段热应用，哪些需要重启

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

类别	字段	需要重启？
渠道	`channels.*`、`web`（WhatsApp）— 所有内置和扩展渠道	否
Agent 和模型	`agent`、`agents`、`models`、`routing`	否
自动化	`hooks`、`cron`、`agent.heartbeat`	否
会话和消息	`session`、`messages`	否
工具和媒体	`tools`、`browser`、`skills`、`audio`、`talk`	否
UI 和其他	`ui`、`logging`、`identity`、`bindings`	否
Gateway 服务器	`gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP）	是
基础设施	`discovery`、`canvasHost`、`plugins`	是

注意： gateway.reload 和 gateway.remote 是例外——更改它们不会触发重启。

Config RPC（程序化更新）

注意： 控制平面写入 RPC（config.apply、config.patch、update.run）每 deviceId+clientIp 每 60 秒限制 3 次请求。触发限制时，RPC 返回 UNAVAILABLE 并附带 retryAfterMs。

config.apply（完整替换）

一步验证 + 写入完整配置并重启 Gateway。

警告： config.apply 替换整个配置。使用 config.patch 进行部分更新，或使用 openclaw config set 更新单个键。

参数：

raw（字符串）— 整个配置的 JSON5 payload
baseHash（可选）— 来自 config.get 的配置哈希（配置存在时必填）
sessionKey（可选）— 重启后唤醒 ping 的会话键
note（可选）— 重启标记的备注
restartDelayMs（可选）— 重启前的延迟（默认 2000）

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

bash

openclaw gateway call config.get --params '{}'  # 获取 payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'

config.patch（部分更新）

将部分更新合并到现有配置（JSON merge patch 语义）：

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

参数：

raw（字符串）— 只包含要更改的键的 JSON5
baseHash（必填）— 来自 config.get 的配置哈希
sessionKey、note、restartDelayMs — 与 config.apply 相同

重启行为与 config.apply 相同：合并的挂起重启加上 30 秒冷却时间。

bash

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

环境变量

OpenClaw 从父进程读取 env var，以及：

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

两个文件都不覆盖现有 env var。你也可以在配置中设置内联 env var：

json5

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

Shell env 导入（可选）

如果启用且预期的键未设置，OpenClaw 会运行你的 login shell 并仅导入缺失的键：

json5

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

环境变量等效：OPENCLAW_LOAD_SHELL_ENV=1

配置值中的 env var 替换

在任意配置字符串值中用 ${VAR_NAME} 引用 env var：

json5

{
  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 对象的字段，可以使用：

json5

{
  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 管理。支持的凭证路径见 SecretRef 凭证面。

完整优先级和来源见环境变量。

完整参考

字段级别的完整参考，见 配置参考。

相关：配置示例 · 配置参考 · Doctor

配置（Configuration） ​

最简配置 ​

编辑配置 ​

严格验证 ​

常见任务 ​

配置热重载 ​

重载模式 ​

哪些字段热应用，哪些需要重启 ​

Config RPC（程序化更新） ​

环境变量 ​

完整参考 ​

配置（Configuration）

最简配置

编辑配置

严格验证

常见任务

配置热重载

重载模式

哪些字段热应用，哪些需要重启

Config RPC（程序化更新）

环境变量

完整参考