openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-28 23:01:02 +00:00
parent 011c883114
commit 760cc257f2
3 changed files with 583 additions and 608 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

639
docs/zh-CN/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

290
docs/zh-CN/gateway/configuration.md
View File

@ -3,36 +3,38 @@ read_when:
- 首次设置 OpenClaw
- 正在查找常见配置模式
- 导航到特定配置部分
summary: 配置概览：常见任务、快速设置，以及完整参考链接
summary: 配置概览：常见任务、快速设置，以及完整参考的链接
title: 配置
x-i18n:
generated_at: "2026-04-28T11:51:34Z"
generated_at: "2026-04-28T22:57:53Z"
model: gpt-5.5
provider: openai
source_hash: 432209fd9b8570a75639bc21b1611899d30a78217e55bb2a45bf3555988e3f40
source_hash: b425a43ea6e40b8380d3a295dc9b190e5dbce7a6d044df786133bfadf3b07c0d
source_path: gateway/configuration.md
workflow: 16
---
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> 配置。
OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
活动配置路径必须是常规文件。对于 OpenClaw 自有写入，不支持符号链接形式的 `openclaw.json`
布局；原子写入可能会替换该路径，而不是保留符号链接。如果你把配置保存在
布局；原子写入可能会替换
该路径，而不是保留符号链接。如果你将配置保存在
默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因：
- 连接渠道并控制谁可以给机器人发消息
- 连接渠道并控制谁可以给 bot 发消息
- 设置模型、工具、沙箱隔离或自动化（cron、钩子）
- 调整会话、媒体、网络或 UI
查看[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。
请参阅[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。
智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 查看精确的字段级
文档。本页提供面向任务的指导，[配置参考](/zh-CN/gateway/configuration-reference) 提供更完整的
字段地图和默认值。
智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确的字段级
文档。使用本页获取面向任务的指导，并使用
[配置参考](/zh-CN/gateway/configuration-reference) 查看更完整的
字段映射和默认值。
<Tip>
**刚开始配置？** 使用 `openclaw onboard` 进行交互式设置，或查看 [配置示例](/zh-CN/gateway/configuration-examples)指南以获取完整的可复制粘贴配置。
**刚开始接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [配置示例](/zh-CN/gateway/configuration-examples)指南，获取完整的可复制粘贴配置。
</Tip>
## 最小配置
@ -62,53 +64,54 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5
```
</Tab>
<Tab title="控制 UI">
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，使用 **配置** 标签页。
控制 UI 会根据实时配置 schema 渲染表单，其中包含字段
`title` / `description` 文档元数据，并在可用时包含插件和渠道 schema，
同时提供 **Raw JSON** 编辑器作为兜底入口。对于下钻
UI 和其他工具，Gateway 网关还会暴露 `config.schema.lookup`，用于
获取一个路径范围内的 schema 节点及其直接子项摘要。
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，并使用 **配置** 标签页。
控制 UI 会根据实时配置 schema 渲染表单，包括字段
`title` / `description` 文档元数据，以及可用的插件和渠道 schema，
并提供 **Raw JSON** 编辑器作为备用方式。对于下钻
UI 和其他工具，Gateway 网关还会暴露 `config.schema.lookup`，
用于获取一个限定路径的 schema 节点及其直接子项摘要。
</Tab>
<Tab title="直接编辑">
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监听该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
</Tab>
</Tabs>
## 严格校验
<Warning>
OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），以便编辑器附加 JSON Schema 元数据。
OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。
</Warning>
`openclaw config schema` 会打印控制 UI 和校验使用的规范 JSON Schema。
`config.schema.lookup` 会获取单个路径范围内的节点以及用于下钻工具的
子项摘要。字段 `title`/`description` 文档元数据会贯穿嵌套对象、通配符（`*`）、
数组项（`[]`）以及 `anyOf`/
`oneOf`/`allOf` 分支。加载 manifest registry 后，运行时插件和渠道 schema 会合并进来。
`openclaw config schema` 会打印控制 UI
和校验使用的权威 JSON Schema。`config.schema.lookup` 会获取单个限定路径的节点及
子项摘要，供下钻工具使用。字段 `title`/`description` 文档元数据会
传递到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
`oneOf`/`allOf` 分支中。加载 manifest 注册表后，运行时插件和渠道 schema 会合并进来。
校验失败时：
- Gateway 网关不会启动
- 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`）
- 运行 `openclaw doctor` 查看精确问题
- 运行 `openclaw doctor` 查看确切问题
- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复
Gateway 网关会在每次成功启动后保留一份可信的最后已知良好副本。
如果 `openclaw.json` 后续校验失败（或丢失 `gateway.mode`、体积
急剧缩小，或前面被误加一行日志），OpenClaw 会将损坏文件保留为
如果 `openclaw.json` 之后校验失败（或丢失 `gateway.mode`、大幅缩小，
或者前面被插入了一行杂散日志），OpenClaw 会将损坏的文件保留为
`.clobbered.*`，恢复最后已知良好副本，并记录恢复
原因。下一个智能体轮次也会收到系统事件警告，避免主
智能体盲目重写已恢复的配置。当候选内容包含已打码的密钥占位符（例如 `***`）时，
会跳过提升为最后已知良好副本。当所有校验问题都限定在 `plugins.entries.<id>...` 范围内时，
OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状态，并
暴露插件本地失败，以免插件 schema 或主机版本不匹配
原因。下一次智能体轮次也会收到系统事件警告，避免主
智能体盲目重写已恢复的配置。当候选配置包含经过遮蔽的密钥占位符（例如 `***`）时，
会跳过提升为最后已知良好副本。
当所有校验问题都限定在 `plugins.entries.<id>...` 范围内时，OpenClaw
不会执行整文件恢复。它会保持当前配置生效，并
呈现插件本地失败，以免插件 schema 或主机版本不匹配
回滚无关的用户设置。
## 常见任务
<AccordionGroup>
<Accordion title="设置渠道（WhatsApp、Telegram、Discord 等）">
每个渠道在 `channels.<provider>` 下都有自己的配置段。设置步骤请查看对应的渠道页面：
每个渠道在 `channels.<provider>` 下都有自己的配置部分。请查看对应的渠道页面了解设置步骤：
- [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
@ -139,7 +142,7 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
</Accordion>
<Accordion title="选择并配置模型">
设置主模型和可选回退：
设置主模型和可选回退模型：
```json5
{
@ -159,30 +162,30 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
```
- `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目，而不移除现有模型。如果普通替换会移除条目，则会被拒绝，除非你传入 `--replace`。
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图片降采样（默认 `1200`）；较低值通常会减少截图密集运行中的视觉 token 用量。
- 参见 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参见[模型故障转移](/zh-CN/concepts/model-failover)了解身份验证轮换和回退行为。
- 对于自定义/自托管提供商，请参见参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
- `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图片缩小尺寸（默认 `1200`）；较低的值通常会减少大量截图运行中的视觉 token 用量。
- 请参阅 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参阅[模型故障转移](/zh-CN/concepts/model-failover)了解认证轮换和回退行为。
- 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
</Accordion>
<Accordion title="控制谁可以给机器人发消息">
私信访问按渠道通过 `dmPolicy` 控制：
<Accordion title="控制谁可以给 bot 发消息">
私信访问通过每个渠道的 `dmPolicy` 控制：
- `"pairing"`（默认）：未知发送者会获得一次性配对码以供批准
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者）
- `"pairing"`（默认）：未知发送者会收到一次性配对码，用于批准
- `"allowlist"`：只允许 `allowFrom`（或已配对允许存储）中的发送者
- `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有私信
对于群组，使用 `groupPolicy` + `groupAllowFrom` 或渠道专用允许列表。
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定允许列表。
查看[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。
请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。
</Accordion>
<Accordion title="设置群聊提及门控">
群组消息默认**需要提及**。按智能体配置触发模式，并让可见房间回复保持在默认消息工具路径上，除非你明确需要旧版自动最终回复：
群消息默认**需要提及**。按智能体配置触发模式，并让可见的房间回复保留在默认消息工具路径上，除非你有意使用旧版自动最终回复：
```json5
{
@ -211,14 +214,14 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
- **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的安全正则模式
- **可见回复**：`message_tool` 会保持普通最终回复为私密；智能体必须调用 `message(action=send)` 才能在群组/渠道中可见发帖。
- 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每渠道覆盖和自聊模式。
- **可见回复**：`message_tool` 会保持普通最终回复私密；智能体必须调用 `message(action=send)` 才能在群组/渠道中可见地发布。
- 请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每个渠道的覆盖项以及自聊天模式。
</Accordion>
<Accordion title="按智能体限制 Skills">
使用 `agents.defaults.skills` 作为共享基线，然后用 `agents.list[].skills` 覆盖特定
智能体：
使用 `agents.defaults.skills` 设置共享基线，然后用 `agents.list[].skills`
覆盖特定智能体：
```json5
{
@ -235,16 +238,16 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
}
```
- 省略 `agents.defaults.skills`，默认不限制 Skills。
- 省略 `agents.list[].skills` 以继承默认值。
- 默认情况下省略 `agents.defaults.skills` 表示不限制 Skills。
- 省略 `agents.list[].skills` 表示继承默认值。
- 设置 `agents.list[].skills: []` 表示没有 Skills。
- 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和
- 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及
[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
</Accordion>
<Accordion title="调整 Gateway 网关渠道健康监控">
控制 Gateway 网关重启疑似停滞渠道的积极程度：
控制 Gateway 网关对看起来停滞的渠道执行重启的激进程度：
```json5
{
@ -268,8 +271,25 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
- 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。
- `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled` 可为单个渠道或账号禁用自动重启，而不禁用全局监控。
- 参见[健康检查](/zh-CN/gateway/health)进行运维调试，并参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可在不禁用全局监控器的情况下，为某个渠道或账号禁用自动重启。
- 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)查看所有字段。
</Accordion>
<Accordion title="调整 Gateway 网关 WebSocket 握手超时">
给本地客户端更多时间，在负载较高或低性能主机上完成认证前 WebSocket 握手：
```json5
{
gateway: {
handshakeTimeoutMs: 30000,
},
}
```
- 默认值为 `15000` 毫秒。
- `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 对一次性服务或 shell 覆盖仍然优先。
- 优先修复启动/事件循环停顿；这个旋钮适用于健康但预热期间较慢的主机。
</Accordion>
@ -296,8 +316,8 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
- 参见[会话管理](/zh-CN/concepts/session)，了解范围、身份链接和发送策略。
- 参见[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。
- 查看[会话管理](/zh-CN/concepts/session)，了解作用域、身份关联和发送策略。
- 查看[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。
</Accordion>
@ -319,12 +339,12 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
先构建镜像：`scripts/sandbox-setup.sh`
请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。
查看[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并查看[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。
</Accordion>
<Accordion title="为官方 iOS 构建启用 relay 后端推送">
relay 后端推送在 `openclaw.json` 中配置。
<Accordion title="为官方 iOS 构建启用中继支持的推送">
中继支持的推送在 `openclaw.json` 中配置。
在 Gateway 网关配置中设置：
@ -344,7 +364,7 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
}
```
等效 CLI：
CLI 等效命令：
```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
@ -352,35 +372,35 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
这会执行以下操作：
- 让 Gateway 网关通过外部 relay 发送 `push.test`、唤醒提醒和重连唤醒。
- 使用由已配对 iOS 应用转发的注册作用域发送授权。Gateway 网关不需要部署范围的 relay 令牌。
- 将每个 relay 后端注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。
- 让本地/手动 iOS 构建继续使用直接 APNs。relay 后端发送仅适用于通过 relay 注册的官方分发构建。
- 必须匹配内置到官方/TestFlight iOS 构建中的 relay 基础 URL，确保注册和发送流量到达同一个 relay 部署。
- 允许 Gateway 网关通过外部中继发送 `push.test`、唤醒提醒和重连唤醒。
- 使用由已配对 iOS 应用转发、限定于注册范围的发送授权。Gateway 网关不需要部署范围的中继令牌。
- 将每个中继支持的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。
- 让本地/手动 iOS 构建继续使用直接 APNs。中继支持的发送仅适用于通过中继注册的官方分发构建。
- 必须匹配内置到官方/TestFlight iOS 构建中的中继基础 URL，以便注册和发送流量到达同一个中继部署。
端到端流程：
1. 安装使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。
1. 安装使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。
2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与 Gateway 网关配对，并让节点和 operator 会话都连接。
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向 relay 注册，然后将 relay 后端 `push.apns.register` 载荷发布到已配对的 Gateway 网关。
5. Gateway 网关存储 relay handle 和发送授权，然后将它们用于 `push.test`、唤醒提醒和重连唤醒。
3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都连接。
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向中继注册，然后将中继支持的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 `push.test`、唤醒提醒和重连唤醒。
运维说明：
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它可以发布绑定到该 Gateway 网关的新 relay 注册。
- 如果你发布指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接该应用，以便它发布绑定到该 Gateway 网关的新中继注册。
- 如果你发布指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。
兼容性说明：
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP relay URL。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP 中继 URL。
请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解 relay 安全模型。
查看 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并查看[身份验证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。
</Accordion>
<Accordion title="设置 heartbeat（定期签到）">
<Accordion title="设置心跳（定期签到）">
```json5
{
agents: {
@ -396,12 +416,12 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
- `every`：持续时间字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
- `directPolicy`：对于私信风格的 heartbeat 目标，使用 `allow`（默认）或 `block`
- 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)获取完整指南。
- `directPolicy`：用于私信样式心跳目标的 `allow`（默认）或 `block`
- 查看[心跳](/zh-CN/gateway/heartbeat)获取完整指南。
</Accordion>
<Accordion title="配置 cron 任务">
<Accordion title="配置 cron 作业">
```json5
{
cron: {
@ -418,11 +438,11 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
- 请参阅 [Cron 任务](/zh-CN/automation/cron-jobs)了解功能概览和 CLI 示例。
- 查看 [Cron 作业](/zh-CN/automation/cron-jobs)了解功能概览和 CLI 示例。
</Accordion>
<Accordion title="设置 webhooks（hooks）">
<Accordion title="设置 webhook（hooks）">
在 Gateway 网关上启用 HTTP webhook 端点：
```json5
@ -447,15 +467,15 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
```
安全说明：
- 将所有 hook/webhook 载荷内容都视为不可信输入。
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关令牌。
- Hook 认证仅通过 header（`Authorization: Bearer ...` 或 `x-openclaw-token`）；query-string 令牌会被拒绝。
- `hooks.path` 不能是 `/`；请将 webhook 入口放在专用子路径上，例如 `/hooks`。
- 除非进行严格限定范围的调试，否则保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。
- 如果启用 `hooks.allowRequestSessionKey`，还要设置 `hooks.allowedSessionKeyPrefixes`，以约束调用方选择的会话键。
- 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并在可行时加上沙箱隔离）。
- 将所有 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 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅限消息发送，并尽可能加上沙箱隔离）。
请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。
查看[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。
</Accordion>
@ -477,12 +497,12 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
}
```
请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每个智能体的访问配置档案。
查看[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每智能体访问配置文件。
</Accordion>
<Accordion title="将配置拆分为多个文件（$include）">
使用 `$include` 组织大型配置：
使用 `$include` 来组织大型配置：
```json5
// ~/.openclaw/openclaw.json
@ -495,18 +515,14 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
}
```
- **单个文件**：替换所在对象
- **单个文件**：替换包含它的对象
- **文件数组**：按顺序深度合并（后者优先）
- **同级键**：在 include 之后合并（覆盖已 include 的值）
- **嵌套 includes**：最多支持 10 层
- **同级键**：在 include 后合并（覆盖已包含的值）
- **嵌套 include**：最多支持 10 层深度
- **相对路径**：相对于执行 include 的文件解析
- **OpenClaw 拥有的写入**：当一次写入只更改一个顶层 section，
且该 section 由单文件 include 支持（例如 `plugins: { $include: "./plugins.json5" }`）时，
OpenClaw 会更新该 include 文件，并保持 `openclaw.json` 不变
- **不支持的写穿透**：root includes、include 数组以及带同级覆盖的 includes
对 OpenClaw 拥有的写入会 fail closed，而不是
将配置扁平化
- **错误处理**：针对缺失文件、解析错误和循环 includes 提供清晰错误
- **OpenClaw 拥有的写入**：当写入只更改一个由单文件 include 支持的顶层区段时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变
- **不支持的透传写入**：root include、include 数组以及带同级覆盖的 include 会对 OpenClaw 拥有的写入失败关闭，而不是扁平化配置
- **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误
</Accordion>
</AccordionGroup>
@ -515,22 +531,11 @@ OpenClaw 不会执行整文件恢复。它会保持当前配置处于活动状
Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改，大多数设置无需手动重启。
直接文件编辑在通过验证前会被视为不可信。监视器会等待
编辑器临时写入/重命名抖动稳定，读取最终文件，并通过恢复
last-known-good 配置来拒绝无效的外部编辑。OpenClaw 拥有的
配置写入在写入前使用相同的 schema gate；破坏性覆盖
（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝，
并保存为 `.rejected.*` 以供检查。
直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并通过恢复上一个已知良好配置来拒绝无效的外部编辑。OpenClaw 拥有的配置写入在写入前使用同一个 schema 门禁；破坏性覆盖（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝，并保存为 `.rejected.*` 以供检查。
插件本地验证失败是例外：如果所有问题都位于
`plugins.entries.<id>...` 下，重载会保留当前配置并报告插件
问题，而不是恢复 `.last-good`。
插件本地验证失败是例外：如果所有问题都位于 `plugins.entries.<id>...` 下，重载会保留当前配置并报告插件问题，而不是恢复 `.last-good`。
如果你在日志中看到 `Config auto-restored from last-known-good` 或
`config reload restored last-known-good config`，请检查 `openclaw.json`
旁边匹配的 `.clobbered.*` 文件，修复被拒绝的载荷，然后运行
`openclaw config validate`。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)
获取恢复检查清单。
如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。查看 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)获取恢复检查清单。
### 重载模式
@ -549,13 +554,13 @@ last-known-good 配置来拒绝无效的外部编辑。OpenClaw 拥有的
}
```
### 哪些可热应用，哪些需要重启
### 哪些会热应用，哪些需要重启
大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
| 类别 | 字段 | 需要重启？ |
| 类别 | 字段 | 是否需要重启？ |
| ------------------- | ----------------------------------------------------------------- | --------------- |
| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置渠道和插件渠道 | 否 |
| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置和插件渠道 | 否 |
| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 |
| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
| 会话和消息 | `session`、`messages` | 否 |
@ -565,34 +570,31 @@ last-known-good 配置来拒绝无效的外部编辑。OpenClaw 拥有的
| 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** |
<Note>
`gateway.reload` 和 `gateway.remote` 是例外 — 更改它们**不会**触发重启。
`gateway.reload` 和 `gateway.remote` 是例外，更改它们**不会**触发重启。
</Note>
### 重载规划
当你编辑通过 `$include` 引用的源文件时，OpenClaw 会从源文件编写的布局
规划重载，而不是从扁平化的内存视图规划。这会让热重载决策
（热应用还是重启）保持可预测，即使单个顶层 section 位于自己的
include 文件中，例如 `plugins: { $include: "./plugins.json5" }`。
如果源布局存在歧义，重载规划会 fail closed。
OpenClaw 通过 `$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` 用于显式自更新并重启
- `update.status` 检查最新的更新重启 sentinel，并在重启后验证正在运行的版本
- `config.schema.lookup` 用于检查一个子树（浅层 schema 节点 + 子项摘要）
- `config.get` 用于获取当前快照以及 `hash`
- `config.patch` 用于部分更新（JSON 合并补丁：对象合并，`null` 删除，数组替换）
- 仅当你打算替换整个配置时才使用 `config.apply`
- `update.run` 用于显式自我更新并重启
- `update.status` 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本
智能体应将 `config.schema.lookup` 作为查看精确字段级文档和约束的第一站。当需要更完整的配置映射、默认值或指向专用子系统参考的链接时，请使用[配置参考](/zh-CN/gateway/configuration-reference)。
智能体应将 `config.schema.lookup` 视为获取精确字段级文档和约束的第一站。当需要更广泛的配置映射、默认值或专用子系统参考链接时，使用 [配置参考](/zh-CN/gateway/configuration-reference)。
<Note>
控制平面写入（`config.apply`、`config.patch`、`update.run`）按 `deviceId+clientIp` 每 60 秒最多 3 个请求进行速率限制。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。`update.status` 是只读的，但限定为管理员范围，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。
控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行限速。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。
`update.status` 是只读的，但作用域为管理员，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。
</Note>
部分补丁示例：
@ -605,11 +607,11 @@ openclaw gateway call config.patch --params '{
}'
```
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已存在时，这两种方法都要求提供 `baseHash`。
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已存在时，这两个方法都需要 `baseHash`。
## 环境变量
OpenClaw 会从父进程以及以下位置读取环境变量：
OpenClaw 会从父进程读取环境变量，并额外读取：
- 当前工作目录中的 `.env`（如果存在）
- `~/.openclaw/.env`（全局回退）
@ -626,7 +628,7 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
```
<Accordion title="Shell 环境导入（可选）">
如果启用且未设置预期键名，OpenClaw 会运行你的登录 shell，并仅导入缺失的键：
如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键：
```json5
{
@ -640,7 +642,7 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
</Accordion>
<Accordion title="配置值中的环境变量替换">
在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
使用 `${VAR_NAME}` 在任意配置字符串值中引用环境变量：
```json5
{
@ -653,13 +655,13 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`
- 缺失或为空的变量会在加载时抛出错误
- 使用 `$${VAR}` 转义以输出字面值
- 在 `$include` 文件中也可用
- 使用 `$${VAR}` 转义以输出字面量
- 可在 `$include` 文件中使用
- 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"`
</Accordion>
<Accordion title="密钥引用（env、file、exec）">
<Accordion title="Secret 引用（env、file、exec）">
对于支持 SecretRef 对象的字段，你可以使用：
```json5
@ -692,15 +694,15 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
}
```
SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见[密钥管理](/zh-CN/gateway/secrets)。
支持的凭证路径列在 [SecretRef 凭证范围](/zh-CN/reference/secretref-credential-surface)中。
SecretRef 详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见 [Secrets 管理](/zh-CN/gateway/secrets)。
支持的凭证路径列在 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) 中。
</Accordion>
有关完整优先级和来源，请参阅[环境](/zh-CN/help/environment)。
完整优先级和来源见 [环境](/zh-CN/help/environment)。
## 完整参考
如需完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。
完整的逐字段参考见 **[配置参考](/zh-CN/gateway/configuration-reference)**。
---

262
docs/zh-CN/install/docker.md
View File

@ -2,38 +2,38 @@
read_when:
- 你想使用容器化的 Gateway 网关，而不是本地安装
- 你正在验证 Docker 流程
summary: 可选的基于 Docker 的 OpenClaw 设置和新手引导
summary: OpenClaw 可选的基于 Docker 的设置和新手引导
title: Docker
x-i18n:
generated_at: "2026-04-28T11:56:02Z"
generated_at: "2026-04-28T22:57:52Z"
model: gpt-5.5
provider: openai
source_hash: d2fe308bdcc243b59923d2b05ba543d63fa146747b9df9bdd59eef76bac187c8
source_hash: 71027022ab9fe1c5a14aa67f0e3edabb0e2aa3c668752637caef49bab5a591de
source_path: install/docker.md
workflow: 16
---
Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证 Docker 流程时才使用它。
Docker 是**可选的**。只有在你想使用容器化 Gateway 网关或验证 Docker 流程时才需要使用它。
## Docker 适合我吗？
- **是**：你想要一个隔离、用完即丢的 Gateway 网关环境，或想在没有本地安装的主机上运行 OpenClaw。
- **否**：你正在自己的机器上运行，并且只想要最快的开发循环。请改用常规安装流程。
- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端使用 Docker，但沙箱隔离默认关闭，并且**不**要求完整 Gateway 网关在 Docker 中运行。SSH 和 OpenShell 沙箱后端也可用。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。
- **是**：你想要一个隔离的、可丢弃的 Gateway 网关环境，或想在没有本地安装的主机上运行 OpenClaw。
- **否**：你正在自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。
- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端会使用 Docker，但沙箱隔离默认关闭，并且**不**要求完整 Gateway 网关在 Docker 中运行。SSH 和 OpenShell 沙箱后端也可用。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。
## 前提条件
## 前置条件
- Docker Desktop（或 Docker Engine）+ Docker Compose v2
- 镜像构建至少需要 2 GB RAM（在 1 GB 主机上，`pnpm install` 可能因 OOM 被终止并以退出码 137 退出）
- 有足够磁盘空间存放镜像和日志
- 镜像构建至少需要 2 GB RAM（`pnpm install` 在 1 GB 主机上可能因 OOM 被终止，并以 137 退出）
- 足够的磁盘空间用于镜像和日志
- 如果在 VPS/公网主机上运行，请查看
[网络暴露的安全加固](/zh-CN/gateway/security)，
[网络暴露安全加固](/zh-CN/gateway/security)，
尤其是 Docker `DOCKER-USER` 防火墙策略。
## 容器化 Gateway 网关
<Steps>
<Step title="Build the image">
<Step title="构建镜像">
从仓库根目录运行设置脚本：
```bash
@ -53,23 +53,23 @@ Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证
</Step>
<Step title="Complete onboarding">
<Step title="完成新手引导">
设置脚本会自动运行新手引导。它会：
- 提示输入提供商 API 密钥
- 生成 Gateway 网关令牌并写入 `.env`
- 通过 Docker Compose 启动 Gateway 网关
在设置过程中，启动前的新手引导和配置写入会直接通过
`openclaw-gateway` 运行。`openclaw-cli` 用于在
Gateway 网关容器已经存在之后运行的命令。
设置期间，启动前的新手引导和配置写入会直接通过
`openclaw-gateway` 运行。`openclaw-cli` 用于 Gateway 网关容器已存在后
你运行的命令。
</Step>
<Step title="Open the Control UI">
在浏览器中打开 `http://127.0.0.1:18789/`，并将已配置的
共享密钥粘贴到设置中。设置脚本默认会将令牌写入 `.env`；
如果你把容器配置切换为密码认证，请改用该密码。
<Step title="打开 Control UI">
在浏览器中打开 `http://127.0.0.1:18789/`，并将配置好的
共享密钥粘贴到 Settings 中。设置脚本默认会将令牌写入 `.env`；
如果你将容器配置切换为密码认证，请改用该密码。
还需要再次获取 URL？
@ -79,7 +79,7 @@ Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证
</Step>
<Step title="Configure channels (optional)">
<Step title="配置渠道（可选）">
使用 CLI 容器添加消息渠道：
```bash
@ -100,7 +100,7 @@ Docker 是**可选**的。仅当你想要容器化 Gateway 网关，或想验证
### 手动流程
如果你更想自己运行每个步骤，而不是使用设置脚本：
如果你更希望自己逐步运行，而不是使用设置脚本：
```bash
docker build -t openclaw:local -f Dockerfile .
@ -112,52 +112,52 @@ docker compose up -d openclaw-gateway
```
<Note>
请从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS`
从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS`
或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`；
请用 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进来。
请使用 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进来。
</Note>
<Note>
因为 `openclaw-cli` 共享 `openclaw-gateway` 的网络命名空间，所以它是一个
启动后工具。在运行 `docker compose up -d openclaw-gateway` 之前，请通过
`openclaw-gateway` 并带上 `--no-deps --entrypoint node` 来运行新手引导
和设置时的配置写入。
启动后工具。在执行 `docker compose up -d openclaw-gateway` 之前，请通过
带有 `--no-deps --entrypoint node` 的 `openclaw-gateway` 运行新手引导
和设置时配置写入。
</Note>
### 环境变量
设置脚本接受这些可选环境变量：
设置脚本接受以下可选环境变量：
| 变量 | 用途 |
| ------------------------------------------ | --------------------------------------------------------------- |
| `OPENCLAW_IMAGE` | 使用远程镜像，而不是在本地构建 |
| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外 apt 包（以空格分隔） |
| `OPENCLAW_EXTENSIONS` | 在构建时预安装插件依赖（以空格分隔的名称） |
| `OPENCLAW_EXTRA_MOUNTS` | 额外主机绑定挂载（以逗号分隔的 `source:target[:opts]`） |
| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到一个命名 Docker 卷 |
| `OPENCLAW_DOCKER_APT_PACKAGES` | 构建期间安装额外 apt 包（空格分隔） |
| `OPENCLAW_EXTENSIONS` | 构建时预安装插件依赖（空格分隔的名称） |
| `OPENCLAW_EXTRA_MOUNTS` | 额外主机绑定挂载（逗号分隔的 `source:target[:opts]`） |
| `OPENCLAW_HOME_VOLUME` | 在命名 Docker 卷中持久化 `/home/node` |
| `OPENCLAW_PLUGIN_STAGE_DIR` | 生成的内置插件依赖和镜像的容器路径 |
| `OPENCLAW_SANDBOX` | 选择启用沙箱启动流程（`1`、`true`、`yes`、`on`） |
| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 |
| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） |
| `OPENCLAW_SKIP_ONBOARDING` | 跳过交互式新手引导步骤（`1`、`true`、`yes`、`on`） |
| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker 套接字路径 |
| `OPENCLAW_DISABLE_BONJOUR` | 禁用 Bonjour/mDNS 广播（Docker 默认值为 `1`） |
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源码绑定挂载覆盖层 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 用于 OpenTelemetry 导出的共享 OTLP/HTTP 收集器端点 |
| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 用于 traces、metrics 或 logs 的信号专用 OTLP 端点 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。当前仅支持 `http/protobuf` |
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源代码绑定挂载覆盖层 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 用于 OpenTelemetry 导出的共享 OTLP/HTTP 采集器端点 |
| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 面向 traces、metrics 或 logs 的信号专用 OTLP 端点 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。目前仅支持 `http/protobuf` |
| `OTEL_SERVICE_NAME` | 用于 OpenTelemetry 资源的服务名称 |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新的实验性 GenAI 语义属性 |
| `OPENCLAW_OTEL_PRELOADED` | 当已有一个 OpenTelemetry SDK 预加载时，跳过启动第二个 SDK |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新实验性 GenAI 语义属性 |
| `OPENCLAW_OTEL_PRELOADED` | 当已有一个 OpenTelemetry SDK 预加载时，跳过启动第二个 |
维护者可以通过将某个插件源码目录挂载到其打包源码路径上，针对打包镜像测试
内置插件源码，例如
维护者可以通过将某个插件源目录挂载到其打包源路径上，针对打包镜像测试内置插件源代码，例如
`OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`。
该挂载的源码目录会针对相同插件 id 覆盖匹配的已编译
该挂载的源目录会覆盖同一插件 ID 对应的已编译
`/app/dist/extensions/synology-chat` 包。
### 可观测性
OpenTelemetry 导出是从 Gateway 网关容器向你的 OTLP 收集器发出的出站流量。
它不需要发布 Docker 端口。如果你在本地构建镜像，并且希望镜像内可使用
内置 OpenTelemetry exporter，请包含它的运行时依赖：
OpenTelemetry 导出是从 Gateway 网关容器出站到你的 OTLP
采集器。它不需要发布 Docker 端口。如果你在本地构建镜像，并希望内置 OpenTelemetry 导出器在镜像内可用，
请包含其运行时依赖：
```bash
export OPENCLAW_EXTENSIONS="diagnostics-otel"
@ -167,33 +167,35 @@ export OTEL_SERVICE_NAME="openclaw-gateway"
```
官方 OpenClaw Docker 发布镜像包含内置
`diagnostics-otel` 插件源码。根据镜像和缓存状态，Gateway 网关在首次启用
该插件时仍可能会暂存插件本地的 OpenTelemetry 运行时依赖，因此请允许首次启动
访问包 registry，或在你的发布通道中预热镜像。若要启用导出，请在配置中允许并启用
`diagnostics-otel` 插件，然后设置 `diagnostics.otel.enabled=true`，或使用
[OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)中的配置示例。收集器认证头通过
`diagnostics-otel` 插件源代码。根据镜像和缓存状态，Gateway 网关在首次启用该插件时
可能仍会暂存插件本地 OpenTelemetry 运行时依赖，因此请允许首次启动访问包注册表，
或在你的发布流程中预热镜像。若要启用导出，请在配置中允许并启用
`diagnostics-otel` 插件，然后设置
`diagnostics.otel.enabled=true`，或使用
[OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)中的配置示例。采集器认证标头通过
`diagnostics.otel.headers` 配置，而不是通过 Docker 环境变量配置。
Prometheus 指标使用已经发布的 Gateway 网关端口。启用
Prometheus metrics 使用已发布的 Gateway 网关端口。启用
`diagnostics-prometheus` 插件，然后抓取：
```text
http://<gateway-host>:18789/api/diagnostics/prometheus
```
该路由受 Gateway 网关认证保护。不要暴露单独的公开 `/metrics` 端口或未认证的反向代理路径。参见
[Prometheus 指标](/zh-CN/gateway/prometheus)。
该路由受 Gateway 网关认证保护。不要暴露单独的公共
`/metrics` 端口或未认证的反向代理路径。参见
[Prometheus metrics](/zh-CN/gateway/prometheus)。
### 健康检查
容器探针端点（无需认证）：
容器探测端点（无需认证）：
```bash
curl -fsS http://127.0.0.1:18789/healthz # liveness
curl -fsS http://127.0.0.1:18789/readyz # readiness
```
Docker 镜像包含一个内置 `HEALTHCHECK`，用于 ping `/healthz`。
Docker 镜像包含一个内置 `HEALTHCHECK`，会 ping `/healthz`。
如果检查持续失败，Docker 会将容器标记为 `unhealthy`，编排系统可以重启或替换它。
已认证的深度健康快照：
@ -204,15 +206,16 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA
### LAN 与 loopback
`scripts/docker/setup.sh` 默认设置 `OPENCLAW_GATEWAY_BIND=lan`，因此主机可通过
`http://127.0.0.1:18789` 使用 Docker 端口发布来访问。
`scripts/docker/setup.sh` 默认设置 `OPENCLAW_GATEWAY_BIND=lan`，因此主机可以通过
`http://127.0.0.1:18789` 访问 Docker 发布的端口。
- `lan`（默认）：主机浏览器和主机 CLI 可以访问已发布的 Gateway 网关端口。
- `loopback`：只有容器网络命名空间内的进程可以直接访问 Gateway 网关。
- `loopback`：只有容器网络命名空间内的进程才能直接访问
Gateway 网关。
<Note>
请使用 `gateway.bind` 中的绑定模式值（`lan` / `loopback` / `custom` /
`tailnet` / `auto`），不要使用 `0.0.0.0` 或 `127.0.0.1` 这类主机别名。
在 `gateway.bind` 中使用绑定模式值（`lan` / `loopback` / `custom` /
`tailnet` / `auto`），不要使用 `0.0.0.0` 或 `127.0.0.1` 这样的主机别名。
</Note>
### 主机本地提供商
@ -220,16 +223,17 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA
当 OpenClaw 在 Docker 中运行时，容器内的 `127.0.0.1` 指的是容器本身，
而不是你的主机机器。对于在主机上运行的 AI 提供商，请使用 `host.docker.internal`：
| 提供商 | 主机默认 URL | Docker 设置 URL |
| 提供商 | 主机默认 URL | Docker 设置 URL |
| --------- | ------------------------ | ----------------------------------- |
| LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` |
| Ollama | `http://127.0.0.1:11434` | `http://host.docker.internal:11434` |
内置 Docker 设置会将这些主机 URL 用作 LM Studio 和 Ollama 的新手引导默认值，
并且 `docker-compose.yml` 会将 `host.docker.internal` 映射到 Linux Docker Engine
的 Docker 主机网关。Docker Desktop 已经在 macOS 和 Windows 上提供相同主机名。
内置 Docker 设置会将这些主机 URL 用作 LM Studio 和 Ollama
新手引导默认值，并且 `docker-compose.yml` 会在 Linux Docker Engine 上将
`host.docker.internal` 映射到 Docker 的主机 Gateway 网关。Docker Desktop 已在
macOS 和 Windows 上提供相同主机名。
主机服务也必须监听 Docker 可访问的地址：
主机服务还必须监听 Docker 可访问的地址：
```bash
lms server start --port 1234 --bind 0.0.0.0
@ -241,58 +245,52 @@ OLLAMA_HOST=0.0.0.0:11434 ollama serve
### Bonjour / mDNS
Docker bridge 网络通常无法可靠转发 Bonjour/mDNS 组播
Docker 桥接网络通常无法可靠转发 Bonjour/mDNS 多播
（`224.0.0.251:5353`）。因此，内置 Compose 设置默认使用
`OPENCLAW_DISABLE_BONJOUR=1`，使 Gateway 网关在 bridge 丢弃组播流量时不会崩溃循环或反复重启广播。
`OPENCLAW_DISABLE_BONJOUR=1`，避免 Gateway 网关在桥接网络丢弃多播流量时崩溃循环或反复重启广播。
对于 Docker 主机，请使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。
只有在使用 host networking、macvlan，或其他已知 mDNS 组播可以工作的网络时，
才设置 `OPENCLAW_DISABLE_BONJOUR=0`。
Docker 主机请使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。
只有在使用主机网络、macvlan 或其他已知 mDNS 多播可用的网络时，才设置
`OPENCLAW_DISABLE_BONJOUR=0`。
有关注意事项和故障排除，请参见 [Bonjour 发现](/zh-CN/gateway/bonjour)。
有关注意事项和故障排除，请参见 [Bonjour 设备发现](/zh-CN/gateway/bonjour)。
### 存储和持久化
Docker Compose 会将 `OPENCLAW_CONFIG_DIR` 绑定挂载到 `/home/node/.openclaw`，
并将 `OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，
因此这些路径会在容器替换后保留下来。
并将 `OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，因此这些路径
会在容器替换后保留。
该挂载的配置目录是 OpenClaw 存放以下内容的位置：
该挂载的配置目录是 OpenClaw 保存以下内容的位置：
- 用于行为配置的 `openclaw.json`
- 用于已存储提供商 OAuth/API-key 认证的 `agents/<agentId>/agent/auth-profiles.json`
- 用于环境变量支持的运行时密钥的 `.env`，例如 `OPENCLAW_GATEWAY_TOKEN`
- 用于已存储提供商 OAuth/API 密钥认证的 `agents/<agentId>/agent/auth-profiles.json`
- 用于环境变量支持的运行时密钥（如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env`
内置插件运行时依赖和镜像的运行时文件属于生成状态，不是用户配置。Compose 会将它们存储在名为
`openclaw-plugin-runtime-deps` 的 Docker 命名卷中，并挂载到
`/var/lib/openclaw/plugin-runtime-deps`。将这个高频变更的目录树排除在主机配置绑定挂载之外，
可以避免缓慢的 Docker Desktop/WSL 文件操作，以及冷启动 Gateway 网关时陈旧的 Windows 句柄问题。
内置插件运行时依赖和镜像运行时文件是生成状态，而不是用户配置。Compose 将它们存储在命名 Docker 卷
`openclaw-plugin-runtime-deps` 中，挂载点为
`/var/lib/openclaw/plugin-runtime-deps`。将这个高变更频率目录放在主机配置绑定挂载之外，
可避免 Docker Desktop/WSL 文件操作缓慢，以及冷启动 Gateway 网关期间出现过期的
Windows 句柄。
默认 Compose 文件会为 `openclaw-gateway` 和 `openclaw-cli` 都将
`OPENCLAW_PLUGIN_STAGE_DIR` 设置为该路径，因此 `openclaw doctor --fix`、渠道
登录/设置命令以及 Gateway 网关启动都会使用同一个生成运行时卷。
默认 Compose 文件会为 `openclaw-gateway` 和 `openclaw-cli` 将 `OPENCLAW_PLUGIN_STAGE_DIR` 设置为该路径，因此 `openclaw doctor --fix`、渠道登录/设置命令以及 Gateway 网关启动都会使用同一个生成的运行时卷。
有关 VM 部署上的完整持久化详情，请参阅
[Docker VM 运行时 - 哪些内容持久化在哪里](/zh-CN/install/docker-vm-runtime#what-persists-where)。
有关 VM 部署中完整的持久化详情，请参阅 [Docker VM 运行时 - 持久化内容的位置](/zh-CN/install/docker-vm-runtime#what-persists-where)。
**磁盘增长热点：**关注 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`、
`openclaw-plugin-runtime-deps` Docker 卷，以及
`/tmp/openclaw/` 下的滚动文件日志。
**磁盘增长热点：**留意 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`、`openclaw-plugin-runtime-deps` Docker 卷，以及 `/tmp/openclaw/` 下的滚动文件日志。
### Shell 辅助工具（可选）
为了让日常 Docker 管理更方便，请安装 `ClawDock`：
为了更轻松地进行日常 Docker 管理，请安装 `ClawDock`：
```bash
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
```
如果你此前从较旧的 `scripts/shell-helpers/clawdock-helpers.sh` 原始路径安装了 ClawDock，请重新运行上面的安装命令，让你的本地辅助工具文件跟踪新位置。
如果你是从旧的 `scripts/shell-helpers/clawdock-helpers.sh` raw 路径安装 ClawDock，请重新运行上面的安装命令，让你的本地辅助文件跟踪新位置。
然后使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行
`clawdock-help` 查看全部命令。
完整辅助工具指南请参阅 [ClawDock](/zh-CN/install/clawdock)。
然后使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行 `clawdock-help` 查看所有命令。完整辅助工具指南请参阅 [ClawDock](/zh-CN/install/clawdock)。
<AccordionGroup>
<Accordion title="为 Docker Gateway 网关启用智能体沙箱">
@ -301,7 +299,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
./scripts/docker/setup.sh
```
自定义套接字路径（例如无 root Docker）：
自定义 socket 路径（例如 rootless Docker）：
```bash
export OPENCLAW_SANDBOX=1
@ -309,9 +307,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
./scripts/docker/setup.sh
```
该脚本只会在沙箱前置条件通过后挂载 `docker.sock`。如果
沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode`
重置为 `off`。
脚本只会在沙箱先决条件通过后挂载 `docker.sock`。如果沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` 重置为 `off`。
</Accordion>
@ -326,16 +322,11 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="共享网络安全说明">
`openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，这样 CLI
命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将其视为共享的
信任边界。compose 配置会移除 `NET_RAW`/`NET_ADMIN`，并在
`openclaw-cli` 上启用
`no-new-privileges`。
`openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，因此 CLI 命令可以通过 `127.0.0.1` 访问 Gateway 网关。将其视为共享信任边界。compose 配置会移除 `NET_RAW`/`NET_ADMIN`，并在 `openclaw-cli` 上启用 `no-new-privileges`。
</Accordion>
<Accordion title="权限和 EACCES">
该镜像以 `node`（uid 1000）身份运行。如果你在
`/home/node/.openclaw` 上看到权限错误，请确保你的主机绑定挂载归 uid 1000 所有：
镜像以 `node`（uid 1000）运行。如果你在 `/home/node/.openclaw` 上看到权限错误，请确保主机 bind mount 归 uid 1000 所有：
```bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
@ -344,9 +335,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="更快重建">
调整你的 Dockerfile 顺序，让依赖层可以被缓存。这样除非锁文件发生变化，
否则可以避免重新运行
`pnpm install`：
排列你的 Dockerfile，让依赖层可被缓存。这样除非 lockfile 变更，否则可以避免重新运行 `pnpm install`：
```dockerfile
FROM node:24-bookworm
@ -369,56 +358,43 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="高级用户容器选项">
默认镜像以安全优先，并以非 root 的 `node` 身份运行。对于功能更完整的容器：
默认镜像以安全优先，并以非 root 的 `node` 身份运行。如需功能更完整的容器：
1. **持久化 `/home/node`**：`export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **烘焙系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
2. **预置系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **安装 Playwright 浏览器**：
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
4. **持久化浏览器下载内容**：设置
`PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用
`OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。
4. **持久化浏览器下载内容**：设置 `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用 `OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。
</Accordion>
<Accordion title="OpenAI Codex OAuth（无头 Docker）">
如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在
Docker 或无头设置中，请复制你最终到达的完整重定向 URL，并将其粘贴回
向导以完成认证。
如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 Docker 或无头设置中，复制你最终落到的完整重定向 URL，并将其粘贴回向导以完成认证。
</Accordion>
<Accordion title="基础镜像元数据">
主 Docker 运行时镜像使用 `node:24-bookworm-slim`，并发布 OCI
基础镜像注解，包括 `org.opencontainers.image.base.name`、
`org.opencontainers.image.source` 和其他注解。Node 基础摘要会
通过 Dependabot Docker 基础镜像 PR 刷新；发布构建不会运行
发行版升级层。请参阅
[OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。
主 Docker 运行时镜像使用 `node:24-bookworm-slim`，并发布 OCI 基础镜像注解，包括 `org.opencontainers.image.base.name`、`org.opencontainers.image.source` 等。Node 基础摘要会通过 Dependabot Docker 基础镜像 PR 刷新；发布构建不会运行发行版升级层。请参阅 [OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。
</Accordion>
</AccordionGroup>
### 在 VPS 上运行？
有关共享 VM 部署步骤，包括二进制烘焙、持久化和更新，请参阅 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和
[Docker VM 运行时](/zh-CN/install/docker-vm-runtime)。
请参阅 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和 [Docker VM 运行时](/zh-CN/install/docker-vm-runtime)，了解共享 VM 部署步骤，包括二进制预置、持久化和更新。
## 智能体沙箱
## Agent 沙箱
当 `agents.defaults.sandbox` 通过 Docker 后端启用时，Gateway 网关会在隔离的 Docker
容器中运行智能体工具执行（shell、文件读写等），而 Gateway 网关本身仍留在主机上。这为不受信任或多租户的智能体会话提供了一道硬边界，而不需要将整个
Gateway 网关容器化。
当 `agents.defaults.sandbox` 通过 Docker 后端启用时，Gateway 网关会在隔离的 Docker 容器中运行智能体工具执行（shell、文件读/写等），而 Gateway 网关本身仍保留在主机上。这样可以在不将整个 Gateway 网关容器化的情况下，为不受信任或多租户的智能体会话提供硬隔离边界。
沙箱作用域可以是按智能体（默认）、按会话或共享。每个作用域都有自己的工作区，挂载在 `/workspace`。你还可以配置
允许/拒绝工具策略、网络隔离、资源限制和浏览器容器。
沙箱范围可以是每智能体（默认）、每会话或共享。每个范围都会获得自己的工作区，并挂载在 `/workspace`。你还可以配置工具允许/拒绝策略、网络隔离、资源限制和浏览器容器。
有关完整配置、镜像、安全说明和多智能体配置文件，请参阅：
- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考
- [OpenShell](/zh-CN/gateway/openshell) -- 对沙箱容器的交互式 shell 访问
- [多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖
- [多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 每智能体覆盖项
### 快速启用
@ -445,29 +421,23 @@ scripts/sandbox-setup.sh
<AccordionGroup>
<Accordion title="镜像缺失或沙箱容器未启动">
使用
[`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)
构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。
容器会按会话在需要时自动创建。
使用 [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) 构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。容器会按需为每个会话自动创建。
</Accordion>
<Accordion title="沙箱中的权限错误">
将 `docker.user` 设置为与你挂载工作区所有权匹配的 UID:GID，
或对工作区文件夹运行 chown。
将 `docker.user` 设置为与你挂载的工作区所有权匹配的 UID:GID，或对工作区文件夹执行 chown。
</Accordion>
<Accordion title="沙箱中找不到自定义工具">
OpenClaw 使用 `sh -lc`（登录 shell）运行命令，它会加载
`/etc/profile`，并且可能重置 PATH。设置 `docker.env.PATH` 来前置你的
自定义工具路径，或在你的 Dockerfile 中的 `/etc/profile.d/` 下添加脚本。
OpenClaw 使用 `sh -lc`（login shell）运行命令，它会加载 `/etc/profile`，并且可能重置 PATH。设置 `docker.env.PATH` 以前置你的自定义工具路径，或在你的 Dockerfile 中将脚本添加到 `/etc/profile.d/` 下。
</Accordion>
<Accordion title="镜像构建期间被 OOM 终止（退出 137）">
VM 至少需要 2 GB RAM。请使用更大的机器规格后重试。
<Accordion title="镜像构建期间因 OOM 被终止（退出 137）">
VM 至少需要 2 GB RAM。使用更大的机器规格后重试。
</Accordion>
<Accordion title="Control UI 中未授权或需要配对">
获取新的仪表盘链接，并批准浏览器设备：
<Accordion title="Control UI 中显示未授权或需要配对">
获取新的 dashboard 链接并批准浏览器设备：
```bash
docker compose run --rm openclaw-cli dashboard --no-open
@ -475,7 +445,7 @@ scripts/sandbox-setup.sh
docker compose run --rm openclaw-cli devices approve <requestId>
```
更多详情：[仪表盘](/zh-CN/web/dashboard)、[设备](/zh-CN/cli/devices)。
更多详情：[Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。
</Accordion>
@ -490,7 +460,7 @@ scripts/sandbox-setup.sh
</Accordion>
</AccordionGroup>
## 相关内容
## 相关
- [安装概览](/zh-CN/install) — 所有安装方法
- [Podman](/zh-CN/install/podman) — Docker 的 Podman 替代方案