Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 会从 ~/.openclaw/openclaw.json 读取一个可选的 配置。 活动配置路径必须是普通文件。符号链接的 openclaw.json 布局不支持 OpenClaw 所有的写入操作；原子写入可能会替换该路径， 而不是保留符号链接。如果你将配置保存在默认状态目录之外， 请直接将 OPENCLAW_CONFIG_PATH 指向真实文件。 如果文件缺失，OpenClaw 将使用安全默认值。添加配置的常见原因包括：
  • 连接通道并控制谁可以给机器人发消息
  • 设置模型、工具、沙箱或自动化（cron、hooks）
  • 调整会话、媒体、网络或 UI
请参阅完整参考以查看所有可用字段。 代理和自动化应在编辑配置前使用 config.schema.lookup 获取精确的字段级文档。 本页用于任务导向的指导，配置参考用于更广泛的字段映射和默认值。
刚接触配置？ 可以先运行 openclaw onboard 进行交互式设置，或者查看 配置示例 指南，获取可直接复制粘贴的完整配置。

​
最小配置

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

​
编辑配置

openclaw onboard       # 完整的入门流程
openclaw configure     # 配置向导

​
严格校验

OpenClaw 只接受完全符合架构的配置。未知键、格式错误的类型或无效值都会导致 Gateway 拒绝启动。根级唯一例外是 $schema（字符串），这样编辑器就可以附加 JSON Schema 元数据。
openclaw config schema 会打印 Control UI 和校验所使用的规范 JSON Schema。 config.schema.lookup 会为下钻工具获取单个路径作用域节点以及子项摘要。 字段 title/description 文档元数据会贯穿嵌套对象、通配符（*）、数组项（[]）以及 anyOf/ oneOf/allOf 分支。运行时插件和通道架构会在清单注册表加载后合并进来。 当校验失败时：
  • Gateway 不会启动
  • 只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
  • 运行 openclaw doctor 查看确切问题
  • 运行 openclaw doctor --fix（或 --yes）应用修复
The Gateway keeps a trusted last-known-good copy after each successful startup, but startup and hot reload do not restore it automatically. If openclaw.json fails validation (including plugin-local validation), Gateway startup fails or the reload is skipped and the current runtime keeps the last accepted config. Run openclaw doctor --fix (or --yes) to repair prefixed/clobbered config or restore the last-known-good copy. Promotion to last-known-good is skipped when a candidate contains redacted secret placeholders such as ***.

​
常见任务

每个通道在 channels.<provider> 下都有自己的配置部分。请参阅对应的通道页面了解设置步骤：所有通道共享相同的 DM 策略模式：
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 仅适用于 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 的允许列表。
  • 使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 可在不移除现有模型的情况下添加允许列表条目。会移除条目的普通替换会被拒绝，除非你传入 --replace。
  • 模型引用使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
  • agents.defaults.imageMaxDimensionPx 控制转录/工具图像的缩放（默认 1200）；较低的值通常会在大量截图的运行中减少视觉 token 用量。
  • 有关在聊天中切换模型，请参阅 模型 CLI；有关身份验证轮换和回退行为，请参阅 模型故障转移。
  • 关于自定义/自托管提供商，请参阅参考中的 自定义提供商。
DM 访问通过 dmPolicy 按通道控制：
  • "pairing"（默认）：未知发送者会收到一次性的配对码以进行批准
  • "allowlist"：仅限 allowFrom 中的发送者（或已配对允许存储）
  • "open"：允许所有传入 DM（需要 allowFrom: ["*"]）
  • "disabled"：忽略所有 DM
对于群组，请使用 groupPolicy + groupAllowFrom 或通道特定允许列表。查看完整参考以了解各通道细节。
群消息默认需要提及。为每个代理配置触发模式，并保持可见房间回复走默认的 message-tool 路径，除非你明确想要旧式自动最终回复：
{
  messages: {
    visibleReplies: "automatic", // 设为 "message_tool" 可在全局要求 message-tool 发送
    groupChat: {
      visibleReplies: "message_tool", // 默认值；如需旧式房间回复可用 "automatic"
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • 元数据提及：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
  • 文本模式：mentionPatterns 中的安全正则模式
  • 可见回复：messages.visibleReplies 可在全局要求 message-tool 发送；messages.groupChat.visibleReplies 可为群组/通道覆盖该设置。
  • 有关可见回复模式、按通道覆盖以及自聊模式，请参阅完整参考。
使用 agents.defaults.skills 作为共享基础，然后用 agents.list[].skills 覆盖特定代理：
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // 继承 github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换默认值
      { id: "locked-down", skills: [] }, // 无技能
    ],
  },
}
  • 若默认情况下不想限制技能，请省略 agents.defaults.skills。
  • 省略 agents.list[].skills 以继承默认值。
  • 将 agents.list[].skills 设为 [] 表示没有技能。
  • 参阅 Skills、Skills 配置 以及 配置参考。
控制 gateway 对看起来陈旧的通道重启有多激进：
{
  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 可仅为某个通道或账户禁用自动重启，而不关闭全局监控。
  • 有关运行时调试，请参阅 Health Checks；有关所有字段，请参阅完整参考。
为本地客户端在负载较高或低性能主机上完成预认证 WebSocket 握手争取更多时间：
{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}
  • 默认值为 15000 毫秒。
  • OPENCLAW_HANDSHAKE_TIMEOUT_MS 仍然会优先用于一次性的服务或 shell 覆盖。
  • 优先先修复启动/事件循环卡顿；这个开关适用于健康但在预热期间较慢的主机。
会话控制对话连续性和隔离：
{
  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）。
  • 有关作用域、身份链接和发送策略，请参阅 会话管理。
  • 有关所有字段，请参阅完整参考。
在隔离的沙箱运行时中运行代理会话：
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
先构建镜像——从源码检出运行 scripts/sandbox-setup.sh，或者在 npm 安装后查看 Sandboxing § Images and setup 中的内联 docker build 命令。有关完整指南，请参阅 沙箱；有关所有选项，请参阅完整参考。
中继支持的推送在 openclaw.json 中配置。在 gateway 配置中设置：
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // 可选。默认值：10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
对应的 CLI 命令：
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
这会做什么：
  • 让 gateway 可以通过外部中继发送 push.test、唤醒提示以及重连唤醒。
  • 使用由配对的 iOS 应用转发的注册范围发送授权。Gateway 不需要部署范围的中继令牌。
  • 将每个中继支持的注册绑定到 iOS 应用所配对的 gateway 身份，因此其他 gateway 不能复用已存储的注册。
  • 让本地/手动 iOS 构建继续直接使用 APNs。中继支持的发送仅适用于通过中继注册的官方分发构建。
  • 必须与官方/TestFlight iOS 构建中内置的中继基础 URL 匹配，因此注册和发送流量会到达同一个中继部署。
端到端流程：
  1. 安装一个使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。
  2. 在 gateway 上配置 gateway.push.apns.relay.baseUrl。
  3. 将 iOS 应用配对到 gateway，并让 node 和 operator 会话都连接起来。
  4. iOS 应用获取 gateway 身份，使用 App Attest 加应用收据向中继注册，然后将中继支持的 push.apns.register 载荷发布到已配对的 gateway。
  5. Gateway 存储中继句柄和发送授权，然后将它们用于 push.test、唤醒提示和重连唤醒。
运维说明：
  • 如果你将 iOS 应用切换到不同的 gateway，请重新连接应用，以便它可以发布绑定到该 gateway 的新中继注册。
  • 如果你发布了指向不同中继部署的新 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 | <channel-id>（例如 discord、matrix、telegram 或 whatsapp）
  • directPolicy：用于 DM 风格心跳目标的 allow（默认）或 block
  • 有关完整指南，请参阅 Heartbeat。
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron 分发 + 隔离的 cron 代理轮执行
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention：从 sessions.json 中清理已完成的隔离运行会话（默认 24h；设为 false 可禁用）。
  • runLog：按大小和保留行数清理 cron/runs/<jobId>.jsonl。
  • 有关功能概览和 CLI 示例，请参阅 Cron 作业。
在 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 集成，请参阅完整参考。
运行多个相互隔离的代理，使用不同的工作区和会话：
{
  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" } },
  ],
}
有关绑定规则和每个代理的访问配置文件，请参阅 多代理 和完整参考。
使用 $include 来组织大型配置：
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • Single file: replaces the containing object
  • Array of files: deep-merged in order (later wins)
  • Sibling keys: merged after includes (override included values)
  • Nested includes: supported up to 10 levels deep
  • Relative paths: resolved relative to the including file
  • OpenClaw-owned writes: when a write changes only one top-level section backed by a single-file include such as plugins: { $include: "./plugins.json5" }, OpenClaw updates that included file and leaves openclaw.json intact
  • Unsupported write-through: root includes, include arrays, and includes with sibling overrides fail closed for OpenClaw-owned writes instead of flattening the config
  • Confinement: $include paths must resolve under the directory holding openclaw.json. To share a tree across machines or users, set OPENCLAW_INCLUDE_ROOTS to a path-list (: on POSIX, ; on Windows) of additional directories that includes may reference. Symlinks are resolved and re-checked, so a path that lexically lives in a config dir but whose real target escapes every allowed root is still rejected.
  • Error handling: clear errors for missing files, parse errors, and circular includes

​
配置热重载

Gateway 会监视 ~/.openclaw/openclaw.json 并自动应用更改——大多数设置无需手动重启。 Direct file edits are treated as untrusted until they validate. The watcher waits for editor temp-write/rename churn to settle, reads the final file, and rejects invalid external edits without rewriting openclaw.json. OpenClaw-owned config writes use the same schema gate before writing; destructive clobbers such as dropping gateway.mode or shrinking the file by more than half are rejected and saved as .rejected.* for inspection. If you see config reload skipped (invalid config) or startup reports Invalid config, inspect the config, run openclaw config validate, then run openclaw doctor --fix for repair. See Gateway troubleshooting for the checklist.

​
重载模式

模式行为
hybrid（默认）立即热应用安全更改。对关键更改自动重启。
hot仅热应用安全更改。当需要重启时记录警告——由你来处理。
restart任意配置更改都会重启 Gateway，无论安全与否。
off禁用文件监视。更改会在下一次手动重启后生效。
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
哪些可热应用，哪些需要重启

大多数字段都可在不停机的情况下热应用。在 hybrid 模式下，需要重启的更改会自动处理。 | 类别 | 字段 | 需要重启？ | | ----------------------------------------------------------------- | --------------- | | 通道 | channels.*、web（WhatsApp）——所有内置和插件通道 | 否 | | 代理与模型 | agent、agents、models、routing | 否 | | 自动化 | hooks、cron、agent.heartbeat | 否 | | 会话与消息 | session、messages | 否 | | 工具与媒体 | tools、browser、skills、mcp、audio、talk | 否 | | UI 与杂项 | ui、logging、identity、bindings | 否 | | Gateway 服务器 | gateway.*（端口、bind、auth、tailscale、TLS、HTTP） | 是 | | 基础设施 | discovery、canvasHost、plugins | 是 |
gateway.reload 和 gateway.remote 是例外——更改它们不会触发重启。

​
重载规划

当你编辑一个通过 $include 引用的源文件时，OpenClaw 会根据源作者布局来规划重载， 而不是按内存中的扁平化视图来规划。这样即使某个顶层部分位于自己独立的包含文件中， 例如 plugins: { $include: "./plugins.json5" }，热重载决策（热应用还是重启）也会保持可预测。 如果源布局存在歧义，重载规划会失败关闭。

​
配置 RPC（程序化更新）

对于通过 gateway API 写入配置的工具，建议使用以下流程：
  • config.schema.lookup 用于检查一个子树（浅层 schema 节点 + 子节点 摘要）
  • config.get 用于获取当前快照以及 hash
  • config.patch 用于部分更新（JSON merge patch：对象合并，null 删除，数组替换）
  • config.apply 仅在你打算替换整个配置时使用
  • update.run 用于显式自更新并重启；当重启后的会话应运行一次后续回合时，请包含 continuationMessage
  • update.status 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本
Agents 应将 config.schema.lookup 视为获取精确 字段级文档和约束的第一站。在需要更广泛的配置映射、默认值或指向专用 子系统参考的链接时，请使用 Configuration reference。
控制平面写入（config.apply、config.patch、update.run）在每个 deviceId+clientIp 上每 60 秒限制 3 次请求。重启 请求会合并，然后在每个重启周期之间强制执行 30 秒冷却时间。 update.status 是只读的，但需要 admin 作用域，因为重启哨兵可能 包含更新步骤摘要和命令输出尾部。
部分补丁示例： 
openclaw gateway call config.get --params '{}'  # 捕获 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-..." },
  },
}
如果启用且预期的键未设置，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"
对于支持 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。
相关：Configuration Examples · Configuration Reference · Doctor

​
相关内容