> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 配置 OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。如果文件缺失，OpenClaw 会使用安全默认值。 活动配置路径必须是常规文件。OpenClaw 所拥有的写入会以原子方式替换它（重命名到该路径），因此符号链接的 `openclaw.json` 会被替换其目标文件，而不是透过链接写入 - 请避免符号链接配置布局。如果你将配置保存在默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 添加配置的常见原因： * 连接渠道并控制谁可以给机器人发消息 * 设置模型、工具、沙箱隔离或自动化（cron、hooks） * 调整会话、媒体、网络或 UI 查看[完整参考](/zh-CN/gateway/configuration-reference)了解每个可用字段。 智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确到字段级别的文档。使用本页获取面向任务的指导，并使用[配置参考](/zh-CN/gateway/configuration-reference)查看更完整的字段地图和默认值。 **刚开始配置？** 使用 `openclaw onboard` 启动交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南获取可完整复制粘贴的配置。 ## 最小配置 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} // ~/.openclaw/openclaw.json { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } ``` ## 编辑配置 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard # full onboarding flow openclaw configure # config wizard ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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](http://127.0.0.1:18789)，并使用**配置**标签页。 Control UI 会根据实时配置 schema 渲染表单，包括字段 `title` / `description` 文档元数据，以及可用时的插件和渠道 schema，并提供 **Raw JSON** 编辑器作为备用入口。对于下钻 UI 和其他工具，Gateway 网关还会暴露 `config.schema.lookup`，用于获取一个路径范围内的 schema 节点及其直接子项摘要。 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 ## 严格验证 OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。 `openclaw config schema` 会打印 Control UI 和验证使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围内的节点，以及用于下钻工具的子项摘要。字段 `title`/`description` 文档元数据会贯穿嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/`oneOf`/`allOf` 分支。运行时插件和渠道 schema 会在清单注册表加载后合并进来。 验证失败时： * Gateway 网关不会启动 * 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） * 运行 `openclaw doctor` 查看精确问题 * 运行 `openclaw doctor --fix`（`--repair` 是同一个标志；`--yes` 会跳过提示）应用修复 Gateway 网关会在每次成功启动后保留一份受信任的最后已知良好副本，但启动和热重载不会自动恢复它 - 只有 `openclaw doctor --fix` 会这样做。如果 `openclaw.json` 验证失败（包括插件本地验证），Gateway 网关启动会失败，或重载会被跳过，并且当前运行时会保留最后接受的配置。被拒绝的写入也会保存为 `.rejected.` 以供检查。Gateway 网关会阻止看起来像意外覆盖的写入 - 删除 `gateway.mode`、丢失 `meta` 块，或文件缩小超过一半 - 除非写入明确允许破坏性更改。当候选配置包含已遮盖的密钥占位符（例如 `***` 或 `[redacted]`）时，会跳过提升为最后已知良好配置。 ## 常见任务 每个渠道在 `channels.` 下都有自己的配置区段。请查看专用渠道页面了解设置步骤： * [Discord](/zh-CN/channels/discord) - `channels.discord` * [Feishu](/zh-CN/channels/feishu) - `channels.feishu` * [Google Chat](/zh-CN/channels/googlechat) - `channels.googlechat` * [iMessage](/zh-CN/channels/imessage) - `channels.imessage` * [Mattermost](/zh-CN/channels/mattermost) - `channels.mattermost` * [Microsoft Teams](/zh-CN/channels/msteams) - `channels.msteams` * [Signal](/zh-CN/channels/signal) - `channels.signal` * [Slack](/zh-CN/channels/slack) - `channels.slack` * [Telegram](/zh-CN/channels/telegram) - `channels.telegram` * [WhatsApp](/zh-CN/channels/whatsapp) - `channels.whatsapp` 所有渠道共享相同的私信策略模式： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["tg:123"], // only for allowlist/open }, }, } ``` 设置主模型和可选回退： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`）；较低的值通常会减少截图密集运行中的视觉 token 使用量。 * 查看[模型 CLI](/zh-CN/concepts/models)了解在聊天中切换模型，并查看[模型故障转移](/zh-CN/concepts/model-failover)了解凭证轮换和回退行为。 * 对于自定义/自托管提供商，请参见参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 私信访问通过每个渠道的 `dmPolicy` 控制（默认 `"pairing"`）： * `"pairing"`：未知发送者会收到一次性配对码以便批准 * `"allowlist"`：只允许 `allowFrom`（或已配对允许存储）中的发送者 * `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`） * `"disabled"`：忽略所有私信 对于群组，使用 `groupPolicy`（`"allowlist" | "open" | "disabled"`）以及 `groupAllowFrom` 或特定渠道的允许列表。 查看[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)了解每个渠道的详细信息。 群组消息默认**需要提及**。按智能体配置触发模式。普通群组/渠道回复会自动发布；对于智能体应自行决定何时发言的共享房间，可选择启用消息工具路径： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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` 会覆盖群组/渠道中的该设置。 * 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)了解可见回复模式、按渠道覆盖以及自聊模式。 使用 `agents.defaults.skills` 设置共享基线，然后用 `agents.list[].skills` 覆盖特定智能体： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。 控制 Gateway 网关重启看起来停滞的渠道的激进程度： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`，可在不禁用全局监控的情况下，为某个渠道或账号禁用自动重启。 * 查看[健康检查](/zh-CN/gateway/health)了解运维调试，并查看[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 在负载较高或低功耗主机上，给本地客户端更多时间完成认证前 WebSocket 握手： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { handshakeTimeoutMs: 30000, }, } ``` * 默认值为 `15000` 毫秒。 * `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 对一次性服务或 shell 覆盖仍然具有优先级。 * 请优先修复启动/事件循环停顿；这个旋钮适用于健康但预热期间较慢的主机。 会话控制对话连续性和隔离： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`：线程绑定会话路由的全局默认值。`/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age` 会按会话绑定、解绑、列出并调节此设置（Discord 绑定线程，Telegram 绑定话题/对话）。 * 请参阅[会话管理](/zh-CN/concepts/session)，了解作用域、身份链接和发送策略。 * 请参阅[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。 在隔离的沙箱运行时中运行智能体会话： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, } ``` 先构建镜像 - 如果使用源码检出，请运行 `scripts/sandbox-setup.sh`；如果通过 npm 安装，请参阅[沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)中的内联 `docker build` 命令。 请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。 面向公开 App Store 构建的基于中继的推送使用托管的 OpenClaw 中继：`https://ios-push-relay.openclaw.ai`。 自定义中继部署需要有意独立的 iOS 构建/部署路径，其中继 URL 必须与 Gateway 网关中继 URL 匹配。如果你正在使用自定义中继构建，请在 Gateway 网关配置中设置： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { push: { apns: { relay: { baseUrl: "https://relay.example.com", // Optional. Default: 10000 timeoutMs: 10000, }, }, }, }, } ``` 等效 CLI： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` 此设置的作用： * 允许 Gateway 网关通过外部中继发送 `push.test`、唤醒提示和重连唤醒。 * 使用由已配对 iOS 应用转发的注册作用域发送授权。Gateway 网关不需要部署范围的中继令牌。 * 将每个基于中继的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关不能复用已存储的注册。 * 让本地/手动 iOS 构建继续使用直接 APNs。基于中继的发送仅适用于通过中继注册的官方分发构建。 * 必须与嵌入 iOS 构建的中继基准 URL 匹配，以便注册和发送流量到达同一个中继部署。 端到端流程： 1. 安装官方 iOS 应用。 2. 可选：仅在使用有意独立的自定义中继构建时，在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。 3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都连接。 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` 仍可作为临时环境变量覆盖使用。 * 自定义 Gateway 网关中继 URL 必须与嵌入 iOS 构建的中继基准 URL 匹配；公开 App Store 发布通道会拒绝自定义 iOS 中继 URL 覆盖。 * `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然是仅限 loopback 的开发逃生口；不要在配置中持久保存 HTTP 中继 URL。 请参阅 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds) 了解端到端流程，并参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { heartbeat: { every: "30m", target: "last", }, }, }, } ``` * `every`：持续时间字符串（`30m`、`2h`）。设置为 `0m` 可禁用。默认值：`30m`。 * `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） * `directPolicy`：面向私信风格 Heartbeat 目标的 `allow`（默认）或 `block` * 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) 获取完整指南。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { cron: { enabled: true, maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000, }, }, } ``` * `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。 * `runLog`：按作业清理保留的 Cron 运行历史行。历史存储在 SQLite 中；`maxBytes`（默认 `2_000_000`）为兼容旧版文件后端运行日志而保留，`keepLines` 默认为 `2000`。 * 请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)，了解功能概览和 CLI 示例。 在 Gateway 网关上启用 HTTP webhook 端点： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 网关身份验证密钥（`gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`）。 * Hook 身份验证仅通过标头传递（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。 * `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径上，例如 `/hooks`。 * 除非进行严格限定范围的调试，否则保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。 * 如果启用 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes`，以限定调用方选择的会话键。 * 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格工具策略（例如仅消息传递，并尽可能启用沙箱隔离）。 请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)，了解所有映射选项和 Gmail 集成。 使用独立工作区和会话运行多个隔离的智能体： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和按智能体访问配置文件。 使用 `$include` 组织大型配置： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} // ~/.openclaw/openclaw.json { gateway: { port: 18789 }, agents: { $include: "./agents.json5" }, broadcast: { $include: ["./clients/a.json5", "./clients/b.json5"], }, } ``` * **单个文件**：替换包含它的对象 * **文件数组**：按顺序深度合并（后者优先），最多支持 10 层嵌套 * **同级键**：在 include 之后合并（覆盖已包含的值） * **相对路径**：相对于执行 include 的文件解析 * **路径格式**：include 路径不得包含空字节，并且在解析前后都必须严格短于 4096 个字符 * **OpenClaw 所有的写入**：当一次写入只更改一个由单文件 include 支撑的顶级区段时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被包含的文件，并保持 `openclaw.json` 不变 * **不支持的直通写入**：对于 OpenClaw 所有的写入，根 include、include 数组以及带有同级覆盖的 include 会失败关闭，而不是扁平化配置 * **限制范围**：`$include` 路径必须解析到保存 `openclaw.json` 的目录下。若要在多台机器或多个用户之间共享一棵目录树，请将 `OPENCLAW_INCLUDE_ROOTS` 设置为路径列表（POSIX 上为 `:`，Windows 上为 `;`），列出 include 可以引用的其他目录。符号链接会被解析并重新检查，因此即使某个路径在词法上位于配置目录中，只要其真实目标逃逸出所有允许的根，仍会被拒绝。 * **错误处理**：针对缺失文件、解析错误、循环 include、无效路径格式和长度过长提供清晰错误 ## 配置热重载 Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改 - 大多数设置无需手动重启。 直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并在不重写 `openclaw.json` 的情况下拒绝无效的外部编辑。OpenClaw 所有的配置写入在写入前使用相同的 schema 门禁（请参阅[严格验证](#strict-validation)，了解适用于每次写入的覆盖/回滚规则）。 如果看到 `config reload skipped (invalid config)`，或启动时报出 `Invalid config`，请检查配置，运行 `openclaw config validate`，然后运行 `openclaw doctor --fix` 修复。请参阅 [Gateway 网关故障排查](/zh-CN/gateway/troubleshooting#gateway-rejected-invalid-config)获取检查清单。 ### 重载模式 | 模式 | 行为 | | ---------------- | ----------------------------- | | **`hybrid`**（默认） | 立即热应用安全更改。对关键更改自动重启。 | | **`hot`** | 仅热应用安全更改。需要重启时记录警告 - 由你处理。 | | **`restart`** | 在任何配置更改时重启 Gateway 网关，无论是否安全。 | | **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 | ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { reload: { mode: "hybrid", debounceMs: 300 }, }, } ``` ### 哪些可以热应用，哪些需要重启 大多数字段都可以无停机热应用；某些热应用的部分只会重启对应的 子系统（渠道、cron、Heartbeat、健康监控），而不是整个 Gateway 网关。在 `hybrid` 模式下，需要重启 Gateway 网关的变更会自动处理。 | 类别 | 字段 | 是否需要重启 Gateway 网关？ | | ------------- | -------------------------------------------------------------------- | ------------------ | | 渠道 | `channels.*`、`web` (WhatsApp) - 所有内置渠道和插件渠道 | 否（重启该渠道） | | 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 | | 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否（重启该子系统） | | 会话和消息 | `session`、`messages` | 否 | | 工具和媒体 | `tools`、`skills`、`mcp`、`audio`、`talk` | 否 | | 插件配置 | `plugins.entries.*`、`plugins.allow`、`plugins.deny`、`plugins.enabled` | 否（重新加载插件运行时） | | UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 | | Gateway 网关服务器 | `gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP、push） | **是** | | 基础设施 | `discovery`、`browser`、`plugins.load`、`plugins.installs` | **是** | `gateway.reload` 和 `gateway.remote` 是 `gateway.*` 下的例外 - 更改它们**不会**触发重启。各个插件也可以覆盖此表：已加载的插件可以声明自己的触发重启配置前缀（例如内置 Canvas 插件会针对 `plugins.enabled`、`plugins.allow` 和 `plugins.deny` 重启 Gateway 网关，而不仅仅是它自己的 `plugins.entries.canvas`），所以实际行为取决于哪些插件处于活动状态。 ### 重新加载规划 当你编辑通过 `$include` 引用的源文件时，OpenClaw 会基于源文件编写时的布局来规划 重新加载，而不是基于扁平化后的内存视图。 这会让热重载决策（热应用还是重启）保持可预测，即使单个 顶级部分位于自己的包含文件中，例如 `plugins: { $include: "./plugins.json5" }`。如果源布局存在歧义，重新加载规划会失败并关闭。 ## 配置 RPC（程序化更新） 对于通过 Gateway 网关 API 写入配置的工具，优先使用此流程： * `config.schema.lookup` 用于检查一个子树（浅层 schema 节点 + 子项 摘要） * `config.get` 用于获取当前快照和 `hash` * `config.patch` 用于局部更新（JSON 合并补丁：对象合并，`null` 删除；数组会在明确用 `replacePaths` 确认后替换，如果 条目会被移除） * `config.apply` 仅在你打算替换整个配置时使用 * `update.run` 用于显式自更新并重启；如果重启后的会话应运行一个后续轮次，请包含 `continuationMessage` * `update.status` 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本 智能体应将 `config.schema.lookup` 作为精确 字段级文档和约束的第一入口。当它们需要更广泛的配置地图、默认值，或专用 子系统参考链接时，请使用 [配置参考](/zh-CN/gateway/configuration-reference)。 控制平面写入（`config.apply`、`config.patch`、`update.run`）会按 每个 `deviceId+clientIp` 每 60 秒 3 次请求进行速率限制。重启 请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。 `update.status` 是只读的，但属于管理员范围，因为重启哨兵可能 包含更新步骤摘要和命令输出尾部。 局部补丁示例： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway call config.get --params '{}' # capture payload.hash openclaw gateway call config.patch --params '{ "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }", "baseHash": "" }' ``` `config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、 `note` 和 `restartDelayMs`。一旦配置文件已经存在，这两个方法都需要 `baseHash`（没有现有配置的首次写入会跳过该检查）。 `config.patch` 还接受 `replacePaths`，这是一个配置路径数组，用来表明这些路径的数组 替换是有意的。如果补丁会用更少条目的数组替换或删除现有数组， Gateway 网关会拒绝该写入，除非该精确路径出现在 `replacePaths` 中；数组条目下的嵌套数组使用 `[]`，例如 `agents.list[].skills`。这可以防止截断的 `config.get` 快照 静默覆盖路由或 allowlist 数组。当你打算替换完整配置时，请使用 `config.apply`。 ## 环境变量 OpenClaw 会从父进程读取环境变量，另外还会读取： * 当前工作目录中的 `.env`（如果存在） * `~/.openclaw/.env`（全局回退） 这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-..." }, }, } ``` 如果启用且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { env: { shellEnv: { enabled: true, timeoutMs: 15000 }, }, } ``` 等效环境变量：`OPENCLAW_LOAD_SHELL_ENV=1`。默认 `timeoutMs`：`15000`。 在任何配置字符串值中使用 `${VAR_NAME}` 引用环境变量： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 对象的字段，你可以使用： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/zh-CN/gateway/secrets)。 支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。 有关完整优先级和来源，请参阅 [Environment](/zh-CN/help/environment)。 ## 完整参考 完整的逐字段参考见 **[配置参考](/zh-CN/gateway/configuration-reference)**。 *** *相关：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)* ## 相关 * [配置参考](/zh-CN/gateway/configuration-reference) * [配置示例](/zh-CN/gateway/configuration-examples) * [Gateway runbook](/zh-CN/gateway)