配置

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置。活动的配置路径必须是常规文件。OpenClaw 不支持符号链接 openclaw.jsonOpenClaw 布局的写入；原子写入可能会替换路径而不是保留符号链接。如果您将配置保留在默认状态目录之外，请将 OPENCLAW_CONFIG_PATH 直接指向实际文件。

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

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

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

代理和自动化应在编辑配置之前使用 config.schema.lookup 查看精确的字段级文档。请使用本页面获取面向任务的指导，并使用配置参考查看更广泛的字段映射和默认值。

最小配置

{
  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

打开 http://127.0.0.1:18789 并使用 Config 选项卡。控制 UI 根据实时配置架构渲染表单，包括字段 title / description 文档元数据，以及在可用时的插件和渠道架构，并提供 Raw JSON 编辑器作为应急手段。对于向下钻取 UI 和其他工具，网关还公开 config.schema.lookup 以获取单个路径范围的架构节点以及直接子级摘要。

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

严格验证

openclaw config schema 打印由控制 UI 和验证使用的规范 JSON 架构。 config.schema.lookup 获取单个路径范围的节点以及用于下钻工具的子摘要。字段 title/description 文档元数据通过嵌套对象、通配符 (*)、数组项 ([]) 和 anyOf/ oneOf/allOf 分支传递。当加载清单注册表时，运行时插件和渠道架构会合并进来。

验证失败时：

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

Gateway(网关) 在每次成功启动后会保留一个可信的“最后已知良好”副本，但启动和热重载不会自动恢复它。如果 Gateway(网关)openclaw.jsonGateway(网关) 验证失败（包括插件本地验证），Gateway(网关) 启动失败或重载被跳过，并且当前运行时保留最后接受的配置。运行 openclaw doctor --fix (或 --yes) 以修复前缀/覆盖的配置或恢复最后已知的良好副本。当候选配置包含已编辑的秘密占位符（例如 ***）时，将跳过提升为最后已知良好的操作。

常见任务

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

每个渠道在 `channels.

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

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

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

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

agents.defaults.models 定义了模型目录，并充当 /model 的允许列表；provider/* 条目将 /model、/models 和模型选择器过滤为选定的提供商，同时仍使用动态模型发现。
使用 `openclaw config set agents.defaults.models ’

’ —strict-json —merge添加允许列表条目而不删除现有模型。除非您传递—replace，否则将删除条目的普通替换将被拒绝。 - 模型引用使用 provider/model格式（例如anthropic/claude-opus-4-6）。 - agents.defaults.imageMaxDimensionPx控制转录/工具图像的下采样（默认1200`CLI）；较低的值通常会在大量截图的运行中减少视觉 token 的使用。 - 请参阅 Models CLI 以在聊天中切换模型，并参阅 Model Failover 以了解身份验证轮换和回退行为。 - 对于自定义/自托管提供商，请参阅参考文档中的 Custom providers。

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

私信访问权限通过 dmPolicy 按渠道控制：

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

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

有关每个渠道的详细信息，请参阅完整参考。

Set up group chat mention gating

群组消息默认为 需要提及。为每个代理配置触发模式。普通的群组/渠道回复会自动发布；对于代理应该决定何时发言的共享房间，选择加入消息工具路径：

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)
      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

元数据提及：原生的 @-提及（WhatsApp 点击提及，Telegram @bot 等）
文本模式：mentionPatterns 中的安全正则模式
可见回复：messages.visibleReplies 可以全局要求消息工具发送；messages.groupChat.visibleReplies 会为群组/渠道覆盖该设置。
关于可见回复模式、按渠道覆盖和自聊模式，请参阅完整参考。

按代理限制 Skills

使用 agents.defaults.skills 作为共享基线，然后使用 agents.list[].skills 覆盖特定代理：

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

省略 agents.defaults.skills 以默认允许无限制的 Skills。
省略 agents.list[].skills 以继承默认值。
设置 agents.list[].skills: [] 以禁用所有 Skills。
请参阅 Skills、Skills 配置以及配置参考。

调整网关渠道健康监控

控制网关重启看起来已停滞的渠道的积极程度：

{
  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` 来禁用单个渠道或账户的自动重启，而无需禁用全局监控器。 - 有关操作调试，请参阅健康检查；有关所有字段，请参阅完整参考。

调整网关 WebSocket 握手超时

为负载较高或性能较低的主机上的本地客户端预留更多时间来完成认证前的 WebSocket 握手：

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

默认值为 15000 毫秒。
针对一次性服务或 shell 覆盖，OPENCLAW_HANDSHAKE_TIMEOUT_MS 仍然优先。
优先解决启动/事件循环阻塞问题；此选项适用于健康但在预热期间速度较慢的主机。

配置会话和重置

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

{
  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）。
请参阅会话管理了解作用域、身份链接和发送策略。
请参阅完整参考了解所有字段。

启用沙箱隔离

在隔离的沙箱运行时中运行代理会话：

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

首先构建镜像 - 从源码检出运行 scripts/sandbox-setup.sh，或者从 npm 安装请参阅沙箱隔离 § 镜像和设置中的内联 docker build 命令。

请参阅沙箱隔离获取完整指南，以及完整参考获取所有选项。

iOS为官方 iOS 构建启用基于中继的推送

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

在网关配置中进行设置：

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

CLI 等效命令：

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

此功能的作用：

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

端到端流程：

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

操作说明：

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

兼容性说明：

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

请参阅 iOS App 了解端到端流程，并参阅 Authentication and trust flow 了解中继安全模型。

设置心跳（定期检查）

{
  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, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

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

.jsonl`。 - 有关功能概述和 CLI 示例，请参阅 Cron jobs。

Set up 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.token；不要重用共享的 Gateway(网关) 令牌。
Hook 认证仅限标头（Authorization: Bearer ... 或 x-openclaw-token）；查询字符串令牌将被拒绝。
hooks.path 不能被 /；将 webhook 入口保留在专用子路径上，例如 /hooks。
除非进行范围严格的调试，否则请保持不安全内容绕过标志处于禁用状态（hooks.gmail.allowUnsafeExternalContent，hooks.mappings[].allowUnsafeExternalContent）。
如果启用 hooks.allowRequestSessionKey，还请设置 hooks.allowedSessionKeyPrefixes 以限制调用方选择的会话密钥。
对于由 hook 驱动的代理，首选强大的现代模型层级和严格的策略（例如，仅限消息传递并在可能的情况下进行沙箱隔离）。

参阅完整参考了解所有映射选项和 Gmail 集成。

Configure multi-agent routing

运行多个具有独立工作区和会话的隔离代理：

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

- **单个文件**：替换包含对象
- **文件数组**：按顺序深度合并（后者胜出）
- **同级键**：在 include 之后合并（覆盖被包含的值）
- **嵌套 include**：支持最多 10 层深度
- **相对路径**：相对于包含的文件解析
- **OpenClaw 拥有的写入**：当写入操作仅更改由单个文件 include 支持的一个顶级部分时（例如 `plugins: { $include: "./plugins.json5" }`OpenClaw），OpenClaw 会更新该被包含的文件，并保持 `openclaw.json`OpenClaw 不变
- **不支持的透传写入**：根 include、include 数组以及具有同级覆盖的 include，对于 OpenClaw 拥有的写入操作将“安全失败”（fail closed），而不是扁平化配置
- **限制**：`$include` 路径必须在持有 `openclaw.json` 的目录下解析。若要在机器或用户之间共享目录树，请将 `OPENCLAW_INCLUDE_ROOTS` 设置为 include 可以引用的其他目录的路径列表（POSIX 上为 `:`，Windows 上为 `;`Windows）。符号链接会被解析并重新检查，因此如果一个路径在词法上位于配置目录中，但其实际目标逃逸了每个允许的根目录，则仍会被拒绝。
- **错误处理**：针对缺失文件、解析错误和循环 include 提供明确的错误信息

配置热重载

Gateway(网关) 会监视 Gateway(网关)~/.openclaw/openclaw.json 并自动应用更改 - 对于大多数设置，无需手动重启。

直接文件编辑在通过验证之前被视为不可信。监视器会等待编辑器的临时写入/重命名平息，读取最终文件，并在不重写 openclaw.jsonOpenClaw 的情况下拒绝无效的外部编辑。OpenClaw 自有的配置写入在写入前使用相同的模式门控；诸如删除 gateway.mode 或将文件缩小一半以上的破坏性覆盖将被拒绝，并保存为 .rejected.* 以供检查。

如果您看到 config reload skipped (invalid config) 或启动报告 Invalid config, inspect the config, run openclaw config validate, then run Gateway(网关)openclaw doctor --fix 进行修复。请参阅 Gateway 故障排除查看检查清单。

重载模式

模式	行为
`hybrid` (默认)	即时热应用安全更改。对于关键更改自动重启。
`hot`	仅热应用安全更改。当需要重启时记录警告 - 由您处理。
`restart`	在任何配置更改（无论是否安全）时重启 Gateway(网关)。
`off`	禁用文件监视。更改在下次手动重启时生效。

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

热应用内容与需要重启的内容对比

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

类别	字段	需要重启？
通道	`channels.*`, `web`WhatsApp (WhatsApp) - 所有内置和插件通道	否
Agent 与模型	`agent`, `agents`, `models`, `routing`	否
自动化	`hooks`, `cron`, `agent.heartbeat`	否
会话与消息	`session`, `messages`	否
工具与媒体	`tools`, `browser`, `skills`, `mcp`, `audio`, `talk`	否
UI 与杂项	`ui`, `logging`, `identity`, `bindings`	否
Gateway(网关) 服务器	`gateway.*` (端口, 绑定, 认证, tailscale, TLS, HTTP)	是
基础设施	`discovery`, `plugins`	是

重新加载计划

当您编辑通过 $includeOpenClaw 引用的源文件时，OpenClaw 会根据源原始布局规划重新加载，而不是扁平化的内存视图。这使得热重新加载决策（热应用还是重启）即使当单个顶级部分位于其自己的包含文件中（例如 plugins: { $include: "./plugins.json5" }）时也是可预测的。如果源布局不明确，重新加载规划将失败关闭。

配置 RPC（程序化更新）

对于通过网关 API 写入配置的工具，请首选此流程：

config.schema.lookup 以检查一个子树（浅层模式节点 + 子摘要）
config.get 以获取当前快照以及 hash
config.patch 用于部分更新（JSON 合并补丁：对象合并，null 删除，数组替换）
仅当您打算替换整个配置时才使用 config.apply
update.run 用于显式自我更新并重启；如果重启后的会话应运行一次后续轮次，则包含 continuationMessage
update.status 以检查最新的更新重启标记并在重启后验证运行版本

代理应将 config.schema.lookup 视为精确字段级文档和约束的首选。当它们需要更广泛的配置映射、默认值或指向专用子系统参考的链接时，请使用 Configuration reference。

部分补丁示例：

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

config.apply 和 config.patch 都接受 raw、baseHash、sessionKey、note 和 restartDelayMs。当配置已存在时，这两种方法都需要 baseHash。

环境变量

OpenClaw 从父进程以及以下位置读取环境变量：

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

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

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

<Accordion title=“Shell 环境导入（可选）“OpenClaw> 如果启用且未设置预期键名，OpenClaw 将运行您的登录 shell 并仅导入缺失的键名：

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

等效环境变量：OPENCLAW_LOAD_SHELL_ENV=1

配置值中的环境变量替换

可以使用 ${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 引用（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 的详细信息（包括用于 env/file/exec 的 secrets.providers）请参见 Secrets Management。支持的凭证路径列于 SecretRef Credential Surface。

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

完整参考

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

相关：配置示例 · 配置参考 · 诊断工具