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-27 09:06:21 +00:00
parent b22252e255
commit 999dc1ed8c
5 changed files with 720 additions and 679 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
docs/zh-CN/gateway/configuration-examples.md
View File

@ -1,24 +1,24 @@
---
read_when:
- 学习如何配置 OpenClaw。
- 正在查找配置示例。
- 首次设置 OpenClaw。
summary: 常见 OpenClaw 配置场景的 schema 准确示例
- 学习如何配置 OpenClaw
- 查找配置示例
- 首次设置 OpenClaw
summary: 常见 OpenClaw 设置的符合 Schema 的配置示例
title: 配置示例
x-i18n:
generated_at: "2026-04-25T05:54:11Z"
generated_at: "2026-04-27T09:02:50Z"
model: gpt-5.4
provider: openai
source_hash: 2f31f70459d6232d2aefe668440312bb1800f18de0ef3c2783befa1de05f25f6
source_hash: 4317f7c4229fad8244f1179cc25fe8c6d2807b369347163b631bebee6eafa846
source_path: gateway/configuration-examples.md
workflow: 15
---
以下示例与当前配置 schema 保持一致。完整参考和各字段说明，请参见[配置](/zh-CN/gateway/configuration)。
以下示例与当前配置 Schema 保持一致。完整参考和各字段说明，请参阅 [配置](/zh-CN/gateway/configuration)。
## 快速开始
### 最小配置
### 绝对最小配置
```json5
{
@ -27,9 +27,9 @@ x-i18n:
}
```
保存到 `~/.openclaw/openclaw.json` 后，你就可以用这个号码向机器人发送私信。
保存到 `~/.openclaw/openclaw.json`，然后你就可以使用该号码向机器人发送私信。
### 推荐入门配置
### 推荐的入门配置
```json5
{
@ -57,7 +57,7 @@ x-i18n:
```json5
{
// 环境变量 + shell
// Environment + shell
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: {
@ -69,7 +69,7 @@ x-i18n:
},
},
// Auth 配置文件元数据（密钥保存在 auth-profiles.json 中）
// Auth profile metadata (secrets live in auth-profiles.json)
auth: {
profiles: {
"anthropic:default": { provider: "anthropic", mode: "api_key" },
@ -84,14 +84,14 @@ x-i18n:
},
},
// 身份
// Identity
identity: {
name: "Samantha",
theme: "helpful sloth",
emoji: "🦥",
},
// 日志
// Logging
logging: {
level: "info",
file: "/tmp/openclaw/openclaw.log",
@ -100,7 +100,7 @@ x-i18n:
redactSensitive: "tools",
},
// 消息格式
// Message formatting
messages: {
messagePrefix: "[openclaw]",
responsePrefix: ">",
@ -108,7 +108,7 @@ x-i18n:
ackReactionScope: "group-mentions",
},
// 路由 + 队列
// Routing + queue
routing: {
groupChat: {
mentionPatterns: ["@openclaw", "openclaw"],
@ -131,7 +131,7 @@ x-i18n:
},
},
// 工具
// Tooling
tools: {
media: {
audio: {
@ -139,7 +139,7 @@ x-i18n:
maxBytes: 20971520,
models: [
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
// 可选的 CLI 回退方案（Whisper 二进制文件）：
// Optional CLI fallback (Whisper binary):
// { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
],
timeoutSeconds: 120,
@ -152,10 +152,10 @@ x-i18n:
},
},
// 会话行为
// Session behavior
session: {
scope: "per-sender",
dmScope: "per-channel-peer", // 推荐用于多用户收件箱
dmScope: "per-channel-peer", // recommended for multi-user inboxes
reset: {
mode: "daily",
atHour: 4,
@ -171,9 +171,9 @@ x-i18n:
pruneAfter: "30d",
maxEntries: 500,
rotateBytes: "10mb",
resetArchiveRetention: "30d", // 时长或 false
maxDiskBytes: "500mb", // 可选
highWaterBytes: "400mb", // 可选（默认是 maxDiskBytes 的 80%）
resetArchiveRetention: "30d", // duration or false
maxDiskBytes: "500mb", // optional
highWaterBytes: "400mb", // optional (defaults to 80% of maxDiskBytes)
},
typingIntervalSeconds: 5,
sendPolicy: {
@ -182,7 +182,7 @@ x-i18n:
},
},
// 渠道
// Channels
channels: {
whatsapp: {
dmPolicy: "pairing",
@ -234,7 +234,7 @@ x-i18n:
},
},
// 智能体运行时
// Agent runtime
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
@ -251,7 +251,7 @@ x-i18n:
"anthropic/claude-sonnet-4-6": { alias: "sonnet" },
"openai/gpt-5.4": { alias: "gpt" },
},
skills: ["github", "weather"], // 由省略 list[].skills 的智能体继承
skills: ["github", "weather"], // inherited by agents that omit list[].skills
thinkingDefault: "low",
verboseDefault: "off",
elevatedDefault: "on",
@ -276,7 +276,7 @@ x-i18n:
every: "30m",
model: "anthropic/claude-sonnet-4-6",
target: "last",
directPolicy: "allow", // allow（默认）| block
directPolicy: "allow", // allow (default) | block
to: "+15555550123",
prompt: "HEARTBEAT",
ackMaxChars: 300,
@ -291,7 +291,7 @@ x-i18n:
},
sandbox: {
mode: "non-main",
scope: "session", // 优先于旧版 perSession: true
scope: "session", // preferred over legacy perSession: true
workspaceRoot: "~/.openclaw/sandboxes",
docker: {
image: "openclaw-sandbox:bookworm-slim",
@ -310,15 +310,15 @@ x-i18n:
{
id: "main",
default: true,
// 继承 defaults.skills -> github, weather
thinkingDefault: "high", // 每个智能体单独的 thinking 覆盖
reasoningDefault: "on", // 每个智能体单独的推理可见性
fastModeDefault: false, // 每个智能体单独的快速模式
// inherits defaults.skills -> github, weather
thinkingDefault: "high", // per-agent thinking override
reasoningDefault: "on", // per-agent reasoning visibility
fastModeDefault: false, // per-agent fast mode
},
{
id: "quick",
skills: [], // 这个智能体没有 Skills
fastModeDefault: true, // 这个智能体始终以快速模式运行
skills: [], // no skills for this agent
fastModeDefault: true, // this agent always runs fast
thinkingDefault: "off",
},
],
@ -346,7 +346,7 @@ x-i18n:
},
},
// 自定义模型提供商
// Custom model providers
models: {
mode: "merge",
providers: {
@ -372,11 +372,11 @@ x-i18n:
},
},
// Cron 任务
// Cron jobs
cron: {
enabled: true,
store: "~/.openclaw/cron/cron.json",
maxConcurrentRuns: 2,
maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
sessionRetention: "24h",
runLog: {
maxBytes: "2mb",
@ -384,7 +384,7 @@ x-i18n:
},
},
// Webhook
// Webhooks
hooks: {
enabled: true,
path: "/hooks",
@ -427,7 +427,7 @@ x-i18n:
},
},
// Gateway 网关 + 网络
// Gateway + networking
gateway: {
mode: "local",
port: 18789,
@ -466,7 +466,7 @@ x-i18n:
## 常见模式
### 共享 Skills 基线，并为其中一个进行覆盖
### 共享 Skills 基线并为单个智能体覆盖
```json5
{
@ -485,7 +485,7 @@ x-i18n:
- `agents.defaults.skills` 是共享基线。
- `agents.list[].skills` 会替换某个智能体的该基线。
- 如果某个智能体不应看到任何 Skills，请使用 `skills: []`。
- 当某个智能体不应看到任何 Skills 时，使用 `skills: []`。
### 多平台设置
@ -510,7 +510,7 @@ x-i18n:
### 受信任节点网络自动批准
除非你控制网络路径，否则请保持设备配对为手动模式。对于专用实验室或 tailnet 子网，你可以通过精确的 CIDR 或 IP，选择性启用首次节点设备自动批准：
除非你控制网络路径，否则请保持设备配对为手动模式。对于专用实验室或 tailnet 子网，你可以选择使用精确的 CIDR 或 IP，为首次节点设备启用自动批准：
```json5
{
@ -524,25 +524,25 @@ x-i18n:
}
```
未设置时，此功能保持关闭。它仅适用于没有请求作用域的全新 `role: node` 配对。操作员/浏览器客户端，以及 role、scope、metadata 或公钥升级，仍然需要手动批准。
未设置时，此功能保持关闭。它仅适用于没有请求作用域的全新 `role: node` 配对。操作员 / 浏览器客户端，以及角色、作用域、元数据或公钥升级，仍然需要手动批准。
### 安全私信模式（共享收件箱 / 多用户私信）
如果有多个人可以向你的机器人发送私信（`allowFrom` 中有多个条目、为多个人批准了配对，或 `dmPolicy: "open"`），请启用**安全私信模式**，这样来自不同发送者的私信默认不会共享同一个上下文：
如果不止一个人可以向你的机器人发送私信（`allowFrom` 中有多个条目、为多人批准了配对，或者 `dmPolicy: "open"`），请启用**安全私信模式**，这样不同发送者发来的私信默认不会共享同一个上下文：
```json5
{
// 安全私信模式（推荐用于多用户或敏感私信智能体）
// Secure DM mode (recommended for multi-user or sensitive DM agents)
session: { dmScope: "per-channel-peer" },
channels: {
// 示例：WhatsApp 多用户收件箱
// Example: WhatsApp multi-user inbox
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15555550123", "+15555550124"],
},
// 示例：Discord 多用户收件箱
// Example: Discord multi-user inbox
discord: {
enabled: true,
token: "YOUR_DISCORD_BOT_TOKEN",
@ -552,8 +552,7 @@ x-i18n:
}
```
对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，发送者授权默认优先基于 ID。
只有在你明确接受该风险时，才应通过各渠道的 `dangerouslyAllowNameMatching: true` 启用直接的、可变的姓名/邮箱/昵称匹配。
对于 Discord / Slack / Google Chat / Microsoft Teams / Mattermost / IRC，发送者授权默认优先按 ID 匹配。只有在你明确接受该风险时，才应通过各渠道的 `dangerouslyAllowNameMatching: true` 启用直接的可变姓名 / 邮箱 / 昵称匹配。
### Anthropic API 密钥 + MiniMax 回退
@ -614,7 +613,7 @@ x-i18n:
}
```
### 仅本地模型
### 仅使用本地模型
```json5
{
@ -649,9 +648,9 @@ x-i18n:
## 提示
- 如果你设置了 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。
- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。请参阅提供商文档确认格式。
- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。请参考提供商文档确认格式。
- 可稍后添加的可选部分包括：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
- 更深入的设置说明，请参见[提供商](/zh-CN/providers)和[故障排除](/zh-CN/gateway/troubleshooting)。
- 更深入的设置说明，请参阅 [提供商](/zh-CN/providers) 和 [故障排除](/zh-CN/gateway/troubleshooting)。
## 相关内容

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

@ -2,76 +2,76 @@
read_when:
- 你需要精确到字段级别的配置语义或默认值
- 你正在验证渠道、模型、Gateway 网关或工具配置块
summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值以及指向专用子系统参考文档的链接
summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考文档的链接
title: 配置参考
x-i18n:
generated_at: "2026-04-27T06:34:22Z"
generated_at: "2026-04-27T09:02:33Z"
model: gpt-5.4
provider: openai
source_hash: 497bd9147b0c08e04195ab7b697f76bd69513f63f5c5a248a8fead3c9cecd570
source_hash: f394e6a9ed0de3f8e8677fb4a2f611979dae24619723f99d342430c4898d5be9
source_path: gateway/configuration-reference.md
workflow: 15
---
`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。
`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。
本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有自己更深入的参考文档时提供跳转链接。由渠道和插件拥有的命令目录，以及更深入的 memory/QMD 调节项，分别位于各自独立页面，而不在本页中展开。
本页涵盖主要的 OpenClaw 配置面，并在某个子系统拥有更深入的独立参考文档时提供外链。由渠道和插件负责的命令目录，以及更深层的 memory/QMD 调整项，分别位于它们自己的页面，而不是本页。
代码事实依据：
- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据
- `config.schema.lookup` 会返回单个按路径限定的 schema 节点，供下钻工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面对配置文档基线哈希进行验证
- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，供逐层深入工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希
智能体查找路径：编辑前请使用 `gateway` 工具动作 `config.schema.lookup` 获取精确到字段级别的文档和约束。面向任务的指导请参阅 [Configuration](/zh-CN/gateway/configuration)，而本页用于查看更广泛的字段映射、默认值以及子系统参考链接。
智能体查找路径：编辑前，使用 `gateway` 工具动作 `config.schema.lookup`
来获取精确到字段级别的文档和约束。面向任务的指导请使用
[Configuration](/zh-CN/gateway/configuration)，而本页则用于查看更广泛的字段映射、默认值以及指向子系统参考文档的链接。
专用深度参考：
专门的深度参考文档：
- [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [Slash commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 随附命令目录
- 对应渠道 / 插件页面，适用于特定渠道的命令面
- [Memory configuration reference](/zh-CN/reference/memory-config) 用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [Slash commands](/zh-CN/tools/slash-commands) 用于当前内置 + 打包提供的命令目录
- 对于渠道专有的命令面，请参见对应渠道/插件所属页面
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。
配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— OpenClaw 在省略时会使用安全默认值。
---
## 渠道
每个渠道的配置键已移至专门页面 —— 请参阅
每个渠道的配置键已移至专门页面 —— 请参见
[Configuration — channels](/zh-CN/gateway/config-channels) 了解 `channels.*`，
包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他
内置渠道（认证、访问控制、多账号、提及门控）。
## 智能体默认值、多智能体、会话和消息
已移至专门页面 —— 请参阅
已移至专门页面 —— 请参见
[Configuration — agents](/zh-CN/gateway/config-agents)，内容包括：
- `agents.defaults.*`（工作区、模型、思考、心跳、memory、媒体、Skills、沙箱）
- `multiAgent.*`（多智能体路由和绑定）
- `session.*`（会话生命周期、压缩、清理）
- `messages.*`（消息传递、TTS、Markdown 渲染）
- `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱）
- `multiAgent.*`（多智能体路由与绑定）
- `session.*`（会话生命周期、压缩、裁剪）
- `messages.*`（消息投递、TTS、Markdown 渲染）
- `talk.*`（Talk 模式）
- `talk.speechLocale`：用于 iOS/macOS 上 Talk 语音识别的可选 BCP 47 locale id
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）
- `talk.speechLocale`：可选的 BCP 47 locale id，用于 iOS/macOS 上 Talk 语音识别
- `talk.silenceTimeoutMs`：未设置时，Talk 会保留平台默认的暂停窗口后再发送转录文本（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）
## 工具和自定义提供商
工具策略、实验性开关、由提供商支持的工具配置，以及自定义
provider / base-URL 设置已移至专门页面 —— 请参阅
provider / base-URL 设置已移至专门页面 —— 请参见
[Configuration — tools and custom providers](/zh-CN/gateway/config-tools)。
## MCP
由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，
供嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、
`show`、`set` 和 `unset` 命令可管理此配置块，且在编辑配置时不会连接到
目标服务器。
由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由内嵌 Pi 及其他运行时适配器使用。`openclaw mcp list`、
`show`、`set` 和 `unset` 命令可在编辑配置时管理该配置块，而无需连接到目标服务器。
```json5
{
mcp: {
// 可选。默认：600000 ms（10 分钟）。设为 0 可禁用空闲驱逐。
// Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
sessionIdleTtlMs: 600000,
servers: {
docs: {
@ -90,15 +90,14 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
}
```
- `mcp.servers`：已命名的 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。
- `mcp.sessionIdleTtlMs`：面向会话作用域的内置 MCP 运行时的空闲 TTL。
一次性嵌入式运行会请求在运行结束时清理；此 TTL 是针对长生命周期
会话和未来调用方的兜底机制。
- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。
下一次工具发现 / 使用时会根据新配置重新创建，因此已移除的
`mcp.servers` 条目会被立即回收，而不是等待空闲 TTL 到期。
- `mcp.servers`：供运行时使用的具名 stdio 或远程 MCP 服务器定义，这些运行时会暴露已配置的 MCP 工具。
- `mcp.sessionIdleTtlMs`：面向会话范围内置 MCP 运行时的空闲 TTL。
一次性内嵌运行会请求在运行结束时清理；此 TTL 是为长生命周期会话和未来调用方提供的兜底机制。
- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。
下一次工具发现/使用时，会基于新配置重新创建它们，因此被移除的
`mcp.servers` 条目会立即回收，而不是等到空闲 TTL 到期。
运行时行为请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和
运行时行为请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和
[CLI backends](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。
## Skills
@ -126,13 +125,13 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
}
```
- `allowBundled`：仅对内置 Skills 生效的可选允许列表（托管 / 工作区 Skills 不受影响）。
- `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。
- `install.preferBrew`：为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。
- `install.nodeManager`：用于 `metadata.openclaw.install`
规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使某个 skill 已内置 / 已安装，也会将其禁用。
- `entries.<skillKey>.apiKey`：针对声明了主环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。
- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/workspace Skills 不受影响）。
- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。
- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。
- `install.nodeManager`：`metadata.openclaw.install`
规范所使用的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使某个 Skill 已内置/已安装，也会将其禁用。
- `entries.<skillKey>.apiKey`：为声明主要环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。
---
@ -161,41 +160,41 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
```
- 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
- **配置更改需要重启 Gateway 网关。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（当插件支持时）。
- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundle。
- **配置变更需要重启 Gateway 网关。**
- `allow`：可选允许列表（只有列出的插件会被加载）。`deny` 优先生效。
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（插件支持时可用）。
- `plugins.entries.<id>.env`：插件作用域环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会变更提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end` 等类型化钩子中读取原始对话内容。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任该插件可以为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：针对受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你确实想允许任意模型时才使用 `"*"`。
- `plugins.entries.<id>.config`：由插件定义的配置对象（若可用，则由原生 OpenClaw 插件 schema 验证）。
- 渠道插件的账号 / 运行时设置位于 `channels.<id>` 下，应由所属插件 manifest 的 `channelConfigs` 元数据描述，而不是由集中式 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch provider 设置。
- `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。
- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持 bundle 提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end` 等类型化钩子中读取原始会话内容。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖可使用的规范 `provider/model` 目标可选允许列表。只有在你明确希望允许任意模型时，才使用 `"*"`。
- `plugins.entries.<id>.config`：插件自定义配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。
- 渠道插件的账号/运行时设置位于 `channels.<id>` 下，应由所属插件 manifest 中的 `channelConfigs` 元数据描述，而不是由集中式 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。
- `apiKey`：Firecrawl API key（接受 SecretRef）。回退顺序为 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API 基础 URL（默认：`https://api.firecrawl.dev`）。
- `onlyMainContent`：仅提取页面主体内容（默认：`true`）。
- `maxAgeMs`：最大缓存时长，单位为毫秒（默认：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时时间，单位为秒（默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。
- `enabled`：启用 X Search provider。
- `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。
- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
- `enabled`：dreaming 主开关（默认 `false`）。
- `maxAgeMs`：缓存最大存活时间（毫秒）（默认：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web search）设置。
- `enabled`：启用 X Search 提供商。
- `model`：搜索使用的 Grok 模型（例如 `"grok-4-1-fast"`）。
- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `enabled`：dreaming 总开关（默认 `false`）。
- `frequency`：每次完整 dreaming 扫描的 cron 频率（默认值为 `"0 3 * * *"`）。
- 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
- 完整 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)：
- 完整的 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)：
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些值作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
- `plugins.slots.memory`：选择活动的 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。
- `plugins.slots.contextEngine`：选择活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供内嵌 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置来应用，而不是作为原始 OpenClaw 配置补丁。
- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
请参阅 [Plugins](/zh-CN/tools/plugin)。
请参见 [Plugins](/zh-CN/tools/plugin)。
---
@ -208,7 +207,7 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
evaluateEnabled: true,
defaultProfile: "user",
ssrfPolicy: {
// dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景下选择启用
// dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
// allowPrivateNetwork: true, // legacy alias
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
@ -246,34 +245,47 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
```
- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
- `tabCleanup` 会在空闲一段时间后，或当某个会话超出其上限时，回收受跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 0 可分别禁用这些单独的清理模式。
- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。
- `tabCleanup` 会在空闲超时后，或当某个
会话超过其上限时，回收已跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为
0，可分别禁用这些单独的清理模式。
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格模式。
- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 发现检查期间也会受到相同的私有网络阻止策略约束。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间同样会受到私有网络拦截限制。
- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来配置显式例外。
- 远程配置文件仅支持附加（不支持启动 / 停止 / 重置）。
- 远程配置文件仅支持附加模式（禁用 start/stop/reset）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。
当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；当你的提供商直接提供 DevTools WebSocket URL 时，请使用 WS(S)。
- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程以及
`attachOnly` CDP 的可达性检查和标签页打开请求。受管的 loopback
配置文件仍使用本地 CDP 默认值。
当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)；使用 WS(S)
则适用于你的提供商直接给出 DevTools WebSocket URL 的情况。
- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和
`attachOnly` CDP 的可达性检查，以及标签页打开请求。受管的 local loopback
配置文件则继续使用本地 CDP 默认值。
- 如果某个外部管理的 CDP 服务可通过 loopback 访问，请将该
配置文件的 `attachOnly: true` 设为 true；否则 OpenClaw 会将该 loopback 端口视为本地受管浏览器配置文件，并可能报告本地端口归属错误。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机上，或通过已连接的浏览器节点附加。
配置文件的 `attachOnly: true` 打开；否则 OpenClaw 会将该 loopback 端口视为
本地受管浏览器配置文件，并可能报告本地端口所有权错误。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到
所选主机上，或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的
Chromium 系浏览器配置文件，例如 Brave 或 Edge。
基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：
使用 snapshot/ref 驱动的操作而不是基于 CSS 选择器的定位，仅支持单文件上传钩子，不支持对话框超时覆盖，不支持 `wait --load networkidle`，也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才需要显式设置 `cdpUrl`。
使用 snapshot/ref 驱动的操作，而不是 CSS 选择器定位；单文件上传
钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持
`responsebody`、PDF 导出、下载拦截或批量操作。
- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下
才需要显式设置 `cdpUrl`。
- 本地受管配置文件可以设置 `executablePath` 来覆盖该配置文件的全局
`browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。
- 本地受管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 等待启动后的 CDP websocket 就绪。在较慢的主机上，如果 Chrome 已成功启动但就绪检查与启动过程发生竞争，请提高这些值。两个值都必须是大于 0 且不超过 `120000` ms 的整数；无效配置值会被拒绝。
- 自动检测顺序：默认浏览器（如果是 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 都支持在 Chromium 启动前，将 `~` 和 `~/...` 解析为你的操作系统主目录。
`existing-session` 配置文件上的逐配置文件 `userDataDir` 也会进行波浪号展开。
- 控制服务：仅 loopback（端口从 `gateway.port` 派生，默认 `18791`）。
- `extraArgs` 会将额外的启动标志追加到本地 Chromium 启动参数中（例如
`browser.executablePath`。可用它让一个配置文件运行在
Chrome 中，另一个运行在 Brave 中。
- 本地受管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP
发现，并使用 `browser.localCdpReadyTimeoutMs` 检查
启动后 CDP websocket 是否就绪。对于 Chrome 虽能成功启动但就绪检查与启动过程发生竞争的较慢主机，请调高这两个值。两个值都必须是
不超过 `120000` ms 的正整数；无效配置值会被拒绝。
- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 都
支持在 Chromium 启动前将 `~` 和 `~/...` 解析为你的操作系统主目录。
`existing-session` 配置文件中的每个配置文件 `userDataDir` 也支持波浪线展开。
- Control 服务：仅 loopback（端口派生自 `gateway.port`，默认 `18791`）。
- `extraArgs` 会将额外启动标志追加到本地 Chromium 启动命令中（例如
`--disable-gpu`、窗口大小设置或调试标志）。
---
@ -292,7 +304,7 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
}
```
- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。
- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。
- `assistant`：Control UI 身份覆盖。未设置时回退到当前活动智能体身份。
---
@ -340,20 +352,20 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
// password: "your-password",
},
trustedProxies: ["10.0.0.1"],
// 可选。默认 false。
// Optional. Default false.
allowRealIpFallback: false,
nodes: {
pairing: {
// 可选。默认未设置 / 禁用。
// Optional. Default unset/disabled.
autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
},
allowCommands: ["canvas.navigate"],
denyCommands: ["system.run"],
},
tools: {
// 额外的 /tools/invoke HTTP 拒绝列表
// Additional /tools/invoke HTTP denies
deny: ["browser"],
// 从默认 HTTP 拒绝列表中移除工具
// Remove tools from the default HTTP deny list
allow: ["gateway"],
},
push: {
@ -373,42 +385,48 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。只有在 `local` 模式下，Gateway 网关才允许启动。
- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以在所有接口上监听。
- **认证**：默认必须启用。非 loopback bind 要求 Gateway 网关认证。实际意味着你需要使用共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成一个 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设为 `token` 或 `password`。如果两者都已配置但未设置 mode，启动以及服务安装 / 修复流程都会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示不会提供此选项，这是有意为之。
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同机 loopback 反向代理不满足 trusted-proxy 认证要求。
- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份头可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。这种无 token 流程假定 Gateway 网关主机是受信任的。
- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关将无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有网络接口。
- **认证**：默认必须启用。非 loopback bind 要求启用 Gateway 网关认证。实际情况下，这意味着使用共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。如果两者都已配置但 mode 未设置，启动以及服务安装/修复流程都会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示不会故意提供此选项。
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求代理来源是**非 loopback**；同机 loopback 反向代理不满足 trusted-proxy 认证条件。
- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。这个无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在写入失败记录之前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配竞态通过。
- `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你确实希望连 localhost 流量也受限流时（例如测试环境或严格代理部署），请设为 `false`。
- 来自浏览器源的 WS 认证尝试始终会被限流，且不会启用 loopback 豁免（作为对基于浏览器的 localhost 暴力破解的纵深防御）。
- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` 值隔离，因此来自某个 localhost origin 的重复失败不会自动锁定另一个 origin。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预计浏览器客户端来自非 loopback origin 时，这是必需项。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，会为有意依赖 Host 头 origin 策略的部署启用 Host 头 origin 回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须为 `ws://` 或 `wss://`。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量级别的紧急放行覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然仅允许对 loopback 使用明文。`openclaw.json` 中没有对应项，且浏览器私有网络配置（例如 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不会影响 Gateway 网关 WebSocket 客户端。
- `gateway.remote.token` / `.password`：远程客户端凭据字段。它们本身不会配置 Gateway 网关认证。
- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方版 / TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。
- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间，单位为毫秒。默认值为 `10000`。
- 基于 relay 的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将基于注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于覆盖上述 relay 配置的临时环境变量。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发环境的逃生开关，用于 loopback HTTP relay URL。生产环境 relay URL 应保持为 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监测间隔，单位为分钟。设为 `0` 可全局禁用健康监测重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道 / 账号允许的最大健康监测重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：按渠道选择退出健康监测重启，同时保留全局监测启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道中的逐账号覆盖。设置后，其优先级高于渠道级覆盖。
- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才能将 `gateway.remote.*` 用作回退。
- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未解析成功，则解析会以关闭方式失败（不会被远程回退掩盖）。
- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只列出你控制的代理。loopback 条目对于同机代理 / 本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**让 loopback 请求满足 `gateway.auth.mode: "trusted-proxy"` 的条件。
- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败即关闭的行为。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于在未请求任何作用域时自动批准首次节点设备配对。未设置时为禁用状态。这不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在完成配对和允许列表评估后，对已声明节点命令进行全局允许 / 拒绝塑形。
- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。
- 在异步 Tailscale Serve Control UI 路径中，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配直接竞争通过。
- `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你有意希望 localhost 流量也被限流（用于测试环境或严格代理部署），请将其设为 `false`。
- 来自浏览器源的 WS 认证尝试始终会启用限流，并禁用 loopback 豁免（作为防御纵深，用于防止基于浏览器的 localhost 暴力破解）。
- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin`
值彼此隔离，因此某个 localhost 源的重复失败不会自动
锁定另一个不同的源。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时，此项为必需。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头源策略的部署启用 Host 头源回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量级别的紧急放行开关，允许对受信任私有网络
IP 使用明文 `ws://`；默认情况下，明文连接仍仅限于 loopback。`openclaw.json`
中没有等效配置，而且像
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 这样的浏览器私有网络配置也不会影响 Gateway 网关
WebSocket 客户端。
- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置 Gateway 网关认证。
- `gateway.push.apns.relay.baseUrl`：供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后使用的外部 APNs relay 基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。
- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。
- 基于 relay 的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个作用域为该注册的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用这个已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：针对上述 relay 配置的临时环境变量覆盖项。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的逃生口，允许使用 loopback HTTP relay URL。生产环境的 relay URL 应保持使用 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号允许的最大健康监控重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：渠道级别的健康监控重启退出设置，同时保持全局监控启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道的账号级覆盖设置。设置后，其优先级高于渠道级覆盖。
- 本地 Gateway 网关调用路径仅会在 `gateway.auth.*` 未设置时，才将 `gateway.remote.*` 用作回退。
- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未能解析，则解析会以关闭方式失败（不会用远程回退来掩盖问题）。
- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只应列出你控制的代理。loopback 条目对于同机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。
- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持关闭式失败行为。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于在首次节点设备配对且未请求任何作用域时自动批准。未设置时即为禁用。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在完成配对和允许列表评估后，对已声明节点命令进行全局允许/拒绝约束。
- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认拒绝列表）。
- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。
</Accordion>
@ -421,13 +439,13 @@ provider / base-URL 设置已移至专门页面 —— 请参阅
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 获取。
和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。
- 可选响应加固头：
- `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
- `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
### 多实例隔离
在同一主机上运行多个 Gateway 网关时，请使用唯一的端口和状态目录：
通过使用唯一端口和状态目录，可在一台主机上运行多个 Gateway 网关：
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -435,9 +453,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`），`--profile <name>`（使用 `~/.openclaw-<name>`）。
便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。
请参阅 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。
请参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。
### `gateway.tls`
@ -456,9 +474,9 @@ openclaw gateway --port 19001
```
- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。
- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书 / 密钥对；仅适用于本地 / 开发环境。
- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅适用于本地/开发环境。
- `certPath`：TLS 证书文件的文件系统路径。
- `keyPath`：TLS 私钥文件的文件系统路径；应限制其权限。
- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。
- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。
### `gateway.reload`
@ -475,13 +493,13 @@ openclaw gateway --port 19001
}
```
- `mode`：控制如何在运行时应用配置编辑。
- `mode`：控制在运行时如何应用配置编辑。
- `"off"`：忽略实时编辑；更改需要显式重启。
- `"restart"`：配置变更时始终重启 Gateway 网关进程。
- `"hot"`：在不重启的情况下于进程内应用更改。
- `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。
- `debounceMs`：应用配置变更前的防抖窗口，单位为毫秒（非负整数）。
- `deferralTimeoutMs`：可选的最长等待时间，单位为毫秒，用于等待进行中的操作结束后再强制重启。省略或设为 `0` 表示无限等待，并定期记录仍在等待的警告。
- `deferralTimeoutMs`：可选的最大等待时间，单位为毫秒，用于等待正在进行的操作完成后再强制重启。省略此项或设为 `0` 表示无限等待，并定期记录仍在等待中的警告。
---
@ -519,15 +537,15 @@ openclaw gateway --port 19001
```
认证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
查询字符串中的 hook token 会被拒绝。
拒绝使用查询字符串中的 hook token。
验证和安全说明：
验证与安全说明：
- `hooks.enabled=true` 要求 `hooks.token` 为非空。
- `hooks.token` 必须与 `gateway.auth.token` **不同**；重用 Gateway 网关 token 会被拒绝。
- `hooks.enabled=true` 要求提供非空的 `hooks.token`。
- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。
- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。
- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果某个 mapping 或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要此显式启用。
- 如果某个 mapping 或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要这个显式启用。
**端点：**
@ -535,30 +553,30 @@ openclaw gateway --port 19001
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认：`false`）。
- `POST /hooks/<name>` → 通过 `hooks.mappings` 解析
- 模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。
- 模板渲染后的映射 `sessionKey` 值会被视为外部提供，因此也要求 `hooks.allowRequestSessionKey=true`。
<Accordion title="映射详情">
- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
- `match.source` 匹配通用路径中的某个负载字段。
- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。
- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。
- `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。
- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取数据。
- `transform` 可指向一个返回 hook 动作的 JS/TS 模块。
- `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。
- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。
- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及由模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化的 `sessionKey` 时，它会成为必填项。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。
- `model` 会覆盖此次 hook 运行使用的 LLM（如果设置了模型目录，则该模型必须被允许）。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或 preset 使用模板化 `sessionKey` 时，该项就变为必需。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。
- `model`：为此次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。
</Accordion>
### Gmail 集成
- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 限制为与 Gmail 命名空间匹配，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不要使用默认的模板化值。
- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并限制 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该 preset，而不是使用模板化默认值。
```json5
{
@ -582,11 +600,11 @@ openclaw gateway --port 19001
```
- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。
- 不要在 Gateway 网关旁边额外运行单独的 `gog gmail watch serve`。
---
## Canvas host
## Canvas 主机
```json5
{
@ -602,12 +620,12 @@ openclaw gateway --port 19001
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。
- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。
- 节点 WebView 通常不会发送认证头；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问公布节点作用域能力 URL。
- 能力 URL 绑定到当前活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
- 会向所提供的 HTML 中注入实时重载客户端。
- 为空时会自动创建初始 `index.html`。
- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。
- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，要求 Gateway 网关认证（token/password/trusted-proxy）。
- 节点 WebView 通常不会发送认证头；在节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问广播节点作用域能力 URL。
- 能力 URL 会绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。
- 会向提供的 HTML 注入实时重载客户端。
- 为空时会自动创建起始 `index.html`。
- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。
- 更改需要重启 Gateway 网关。
- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。
@ -627,8 +645,8 @@ openclaw gateway --port 19001
}
```
- `minimal`（默认）：在 TXT 记录中省略 `cliPath` 和 `sshPort`。
- `full`：包含 `cliPath` 和 `sshPort`。
- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。
- `full`：包含 `cliPath` + `sshPort`。
- 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
### 广域（DNS-SD）
@ -641,7 +659,7 @@ openclaw gateway --port 19001
}
```
会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若需跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）和 Tailscale split DNS 使用。
会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，请结合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 使用。
设置：`openclaw dns setup --apply`。
@ -666,10 +684,10 @@ openclaw gateway --port 19001
}
```
- 仅当进程环境中缺少对应键时，才会应用内联环境变量。
- `.env` 文件：当前工作目录的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
- 只有在进程环境中缺少该键时，才会应用内联环境变量。
- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（二者都不会覆盖已有变量）。
- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。
- 完整优先级请参阅 [Environment](/zh-CN/help/environment)。
- 完整优先级请参见 [Environment](/zh-CN/help/environment)。
### 环境变量替换
@ -684,8 +702,8 @@ openclaw gateway --port 19001
```
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失 / 为空的变量会在加载配置时抛出错误。
- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。
- 缺失/为空的变量会在配置加载时抛出错误。
- 使用 `$${VAR}` 转义，以表示字面量 `${VAR}`。
- 对 `$include` 同样有效。
---
@ -696,7 +714,7 @@ SecretRef 是增量式的：明文值仍然可用。
### `SecretRef`
使用以下对象形态：
使用以下对象形态之一：
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
@ -705,18 +723,18 @@ SecretRef 是增量式的：明文值仍然可用。
验证规则：
- `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$`
- `source: "env"` 的 `id` 模式：`^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` 的 `id`：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`）
- `source: "exec"` 的 `id` 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"` 的 `id` 不能包含以 `/` 分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝）
- `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`）
- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"` 的 id 不能包含 `.` 或 `..` 这样的斜杠分隔路径段（例如 `a/../b` 会被拒绝）
### 支持的凭据面
### 支持的凭据范围
- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 以受支持的 `openclaw.json` 凭据路径为目标。
- `auth-profiles.json` 中的引用已纳入运行时解析和审计覆盖范围。
- `secrets apply` 会作用于受支持的 `openclaw.json` 凭据路径。
- `auth-profiles.json` 中的 refs 也纳入运行时解析和审计覆盖范围。
### Secret provider 配置
### Secret 提供商配置
```json5
{
@ -746,14 +764,14 @@ SecretRef 是增量式的：明文值仍然可用。
说明：
- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 `singleValue` 模式下，`id` 必须为 `"value"`）。
- 当 Windows ACL 验证不可用时，file 和 exec provider 路径会以关闭方式失败。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。
- `exec` provider 要求 `command` 为绝对路径，并通过 stdin/stdout 使用协议负载。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍验证其解析后的目标路径。
- 如果配置了 `trustedDirs`，受信任目录检查将应用于解析后的目标路径。
- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传入所需变量。
- Secret 引用会在激活时解析为内存中的快照，之后请求路径只会读取该快照。
- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动 / 重载失败，而未激活表面会被跳过并附带诊断信息。
- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。
- 当 Windows ACL 验证不可用时，文件和 exec 提供商路径会以关闭方式失败。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
- `exec` 提供商要求 `command` 使用绝对路径，并通过 stdin/stdout 上传协议负载。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍验证解析后的目标路径。
- 如果配置了 `trustedDirs`，则受信任目录检查会应用于解析后的目标路径。
- 默认情况下，`exec` 子进程环境极简；请通过 `passEnv` 显式传入所需变量。
- Secret refs 会在激活时解析为内存中的快照，之后请求路径只读取该快照。
- 激活期间会应用活动表面过滤：已启用表面上的未解析 refs 会导致启动/重载失败，而非活动表面会被跳过并记录诊断信息。
---
@ -776,12 +794,12 @@ SecretRef 是增量式的：明文值仍然可用。
```
- 每个智能体的 profile 存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持静态凭据模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- `auth-profiles.json` 支持值级 refs（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）以支持静态凭据模式。
- OAuth 模式 profile（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭据。
- 静态运行时凭据来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会将其清除。
- 静态运行时凭据来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会清理。
- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。
- 请参阅 [OAuth](/zh-CN/concepts/oauth)。
- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参阅 [Secrets Management](/zh-CN/gateway/secrets)。
- 请参见 [OAuth](/zh-CN/concepts/oauth)。
- Secrets 运行时行为及 `audit/configure/apply` 工具：请参见 [Secrets Management](/zh-CN/gateway/secrets)。
### `auth.cooldowns`
@ -803,15 +821,20 @@ SecretRef 是增量式的：明文值仍然可用。
}
```
- `billingBackoffHours`：当 profile 因真实的计费 / 余额不足错误而失败时的基础退避时长（小时）（默认：`5`）。即使在 `401` / `403` 响应中，只要文本明确表示计费问题，也可能归入这里；但 provider 特定的文本匹配器仍只作用于拥有它们的 provider（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：按 provider 设置计费退避小时数的可选覆盖。
- `billingBackoffHours`：当某个 profile 因真实
计费/余额不足错误失败时，使用的基础退避时间（小时）（默认：`5`）。即使在 `401`/`403` 响应上，
明确的计费文本仍可能落入这里，但特定提供商的文本
匹配器仍只作用于拥有它们的提供商（例如 OpenRouter
`Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或
organization/workspace 支出限制消息则仍归入 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：按提供商覆盖计费退避小时数的可选配置。
- `billingMaxHours`：计费退避指数增长的上限小时数（默认：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认：`60`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟）（默认：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认：`60`）。
- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。
- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退之前，允许的同 provider auth-profile 轮换最大次数（默认：`1`）。像 `ModelNotReadyException` 这样的 provider 忙碌形态会归入这里。
- `overloadedBackoffMs`：在重试 overloaded provider/profile 轮换前的固定延迟，单位为毫秒（默认：`0`）。
- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退之前，允许的同 provider auth-profile 轮换最大次数（默认：`1`）。该 rate-limit 桶包括 provider 形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
- `overloadedProfileRotations`：对过载错误，在切换到模型回退之前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商繁忙形态也归入这里。
- `overloadedBackoffMs`：在重试过载的提供商/profile 轮换前的固定延迟（默认：`0`）。
- `rateLimitedProfileRotations`：对速率限制错误，在切换到模型回退之前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。该速率限制桶包括诸如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted` 之类带有提供商特征的文本。
---
@ -831,9 +854,9 @@ SecretRef 是增量式的：明文值仍然可用。
```
- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
- 设置 `logging.file` 可使用稳定路径。
- 设置 `logging.file` 可使用固定路径。
- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
- `maxFileBytes`：轮转前活动日志文件的最大大小，单位为字节（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁最多保留五个带编号的归档文件。
- `maxFileBytes`：轮转前活动日志文件的最大大小（字节）（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁边保留最多五个带编号的归档文件。
- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录以及持久化会话转录文本进行尽力脱敏。
---
@ -882,25 +905,25 @@ SecretRef 是增量式的：明文值仍然可用。
}
```
- `enabled`：仪表输出总开关（默认：`true`）。
- `flags`：启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。
- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的时长阈值，单位为毫秒。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。完整配置、信号目录和隐私模型请参阅 [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。
- `otel.endpoint`：用于 OTel 导出的 collector URL。
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的按信号划分的 OTLP 端点。设置后，它们只会覆盖该信号的 `otel.endpoint`。
- `enabled`：仪表数据输出总开关（默认：`true`）。
- `flags`：用于启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。
- `stuckSessionWarnMs`：当会话仍处于处理中状态时，用于发出卡住会话警告的年龄阈值（毫秒）。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。完整配置、信号目录和隐私模型请参见 [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。
- `otel.endpoint`：用于 OTel 导出的收集器 URL。
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的按信号划分的 OTLP 端点。设置后，它们只会对对应信号覆盖 `otel.endpoint`。
- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。
- `otel.serviceName`：资源属性中的服务名称。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。
- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。
- `otel.flushIntervalMs`：定期刷新遥测数据的间隔，单位为毫秒。
- `otel.captureContent`：选择启用对 OTEL span 属性中的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息 / 工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于启用最新实验性 GenAI span provider 属性的环境变量开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 使用有界语义属性。
- `OPENCLAW_OTEL_PRELOADED=1`：适用于已经注册了全局 OpenTelemetry SDK 的主机的环境变量开关。此时 OpenClaw 会跳过由插件拥有的 SDK 启动 / 关闭流程，同时保持诊断监听器处于活动状态。
- `otel.sampleRate`：trace 采样率 `0`–`1`。
- `otel.flushIntervalMs`：周期性遥测刷新间隔（毫秒）。
- `otel.captureContent`：选择启用用于 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式则可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于启用最新实验性 GenAI span 提供商属性的环境变量开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 使用有界语义属性。
- `OPENCLAW_OTEL_PRELOADED=1`：适用于已注册全局 OpenTelemetry SDK 的主机的环境变量开关。此时 OpenClaw 会跳过由插件负责的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当对应配置键未设置时使用的按信号划分端点环境变量。
- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。
- `cacheTrace.enabled`：记录内嵌运行的缓存跟踪快照（默认：`false`）。
- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含的内容（默认全部为 `true`）。
---
@ -925,9 +948,9 @@ SecretRef 是增量式的：明文值仍然可用。
- `channel`：用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。
- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。
- `auto.stableDelayHours`：稳定渠道自动应用前的最短延迟，单位为小时（默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：稳定渠道额外的发布分散窗口，单位为小时（默认：`12`；最大：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道执行检查的频率，单位为小时（默认：`1`；最大：`24`）。
- `auto.stableDelayHours`：稳定渠道自动应用前的最小时延（小时）（默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外小时数（默认：`12`；最大：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。
---
@ -960,23 +983,23 @@ SecretRef 是增量式的：明文值仍然可用。
}
```
- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分发和生成入口）。
- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。
- `backend`：默认 ACP 运行时后端 id（必须与已注册的 ACP 运行时插件匹配）。
- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 会隐藏 ACP 分发和 spawn 入口）。
- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可保留 ACP 命令可用，同时阻止执行。
- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。
如果设置了 `plugins.allow`，请包含后端插件 id（例如 `acpx`），否则内置默认插件将不会加载。
- `defaultAgent`：当生成操作未指定显式目标时，所使用的 ACP 目标智能体 id 回退值。
- `defaultAgent`：当 spawn 未指定显式目标时使用的 ACP 回退目标智能体 id。
- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示没有额外限制。
- `maxConcurrentSessions`：允许同时处于活动状态的 ACP 会话最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位为毫秒。
- `stream.maxChunkChars`：分割流式块投影前允许的最大块大小。
- `stream.repeatSuppression`：按轮次抑制重复的状态 / 工具行（默认：`true`）。
- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。
- `stream.maxChunkChars`：在拆分流式分块投影前的最大块大小。
- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认：`true`）。
- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。
- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。
- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认：`"paragraph"`）。
- `stream.maxOutputChars`：每个 ACP 轮次投影的智能体输出最大字符数。
- `stream.maxSessionUpdateChars`：投影的 ACP 状态 / 更新行最大字符数。
- `stream.tagVisibility`：记录标签名称到布尔可见性覆盖值的映射，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL，单位为分钟。
- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。
- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。
- `stream.tagVisibility`：tag 名称到布尔可见性覆盖的记录，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL（分钟）。
- `runtime.installCommand`：可选安装命令，用于引导 ACP 运行时环境。
---
@ -993,9 +1016,9 @@ SecretRef 是增量式的：明文值仍然可用。
```
- `cli.banner.taglineMode` 控制横幅标语样式：
- `"random"`（默认）：轮换的有趣 / 季节性标语。
- `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
- `"off"`：不显示标语文本（仍显示横幅标题 / 版本）。
- `"random"`（默认）：轮换的有趣/季节性标语。
- `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。
- `"off"`：不显示标语文本（仍显示横幅标题/版本）。
- 若要隐藏整个横幅（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
---
@ -1020,13 +1043,13 @@ SecretRef 是增量式的：明文值仍然可用。
## 身份
请参阅 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。
请参见 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。
---
## Bridge protocol（旧版节点，历史参考）（旧版，已移除）
当前构建版本已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；可使用 `openclaw doctor --fix` 清除未知键）。
当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以移除未知键）。
<Accordion title="旧版 bridge 配置（历史参考）">
@ -1054,7 +1077,7 @@ SecretRef 是增量式的：明文值仍然可用。
{
cron: {
enabled: true,
maxConcurrentRuns: 2,
maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
sessionRetention: "24h", // duration string or false
@ -1066,11 +1089,11 @@ SecretRef 是增量式的：明文值仍然可用。
}
```
- `sessionRetention`：在从 `sessions.json` 清理前，保留已完成的隔离 cron 运行会话多长时间。也控制已归档已删除 cron 转录的清理。默认值：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在清理前的最大大小。默认值：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。
- `webhookToken`：用于 cron webhook POST 发送（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送认证头。
- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储作业。
- `sessionRetention`：在从 `sessions.json` 中裁剪前，已完成隔离 cron 运行会话的保留时长。也控制已归档的已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在裁剪前的最大大小。默认：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。
- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略则不会发送认证头。
- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。
### `cron.retry`
@ -1086,9 +1109,9 @@ SecretRef 是增量式的：明文值仍然可用。
}
```
- `maxAttempts`：一次性作业在瞬时错误下允许的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试的退避延迟数组，单位为毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。
- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会对所有瞬时类型重试。
- `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试使用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。
- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会对所有瞬时类型进行重试。
仅适用于一次性 cron 作业。周期性作业使用单独的失败处理逻辑。
@ -1110,11 +1133,11 @@ SecretRef 是增量式的：明文值仍然可用。
```
- `enabled`：为 cron 作业启用失败告警（默认：`false`）。
- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。
- `cooldownMs`：同一作业重复告警之间的最小间隔，单位为毫秒（非负整数）。
- `after`：触发告警前允许的连续失败次数（正整数，最小值：`1`）。
- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒）（非负整数）。
- `includeSkipped`：是否将连续跳过的运行计入告警阈值（默认：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。
- `mode`：发送模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 POST。
- `accountId`：用于限定告警发送范围的可选账号或渠道 id。
- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 发送到已配置的 webhook。
- `accountId`：可选的账号或渠道 id，用于限定告警投递范围。
### `cron.failureDestination`
@ -1131,16 +1154,16 @@ SecretRef 是增量式的：明文值仍然可用。
}
```
- 所有作业共用的 cron 失败通知默认目标。
- 所有作业共用的默认 cron 失败通知目标。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。
- `channel`：announce 发送的渠道覆盖值。`"last"` 会复用上次已知的发送渠道。
- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。
- `accountId`：可选的发送账号覆盖值。
- 每个作业的 `delivery.failureDestination` 会覆盖该全局默认值。
- 当全局和逐作业失败目标都未设置时，那些原本已通过 `announce` 发送的作业在失败时会回退到其主 announce 目标。
- `delivery.failureDestination` 仅对 `sessionTarget="isolated"` 的作业受支持，除非该作业的主 `delivery.mode` 为 `"webhook"`。
- `channel`：announce 投递的渠道覆盖值。`"last"` 会复用最后一次已知投递渠道。
- `to`：显式 announce 目标或 webhook URL。webhook 模式下为必填。
- `accountId`：可选的投递账号覆盖值。
- 每个作业的 `delivery.failureDestination` 会覆盖这个全局默认值。
- 当全局和每个作业的失败目标都未设置时，那些已经通过 `announce` 投递的作业会在失败时回退到其主 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。
请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。
请参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。
---
@ -1148,34 +1171,34 @@ SecretRef 是增量式的：明文值仍然可用。
在 `tools.media.models[].args` 中展开的模板占位符：
| Variable | 说明 |
| ------------------ | ---- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（不含历史记录 / 发送者包装） |
| 变量 | 说明 |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（不含历史记录/发送者包装） |
| `{{BodyStripped}}` | 去除群组提及后的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 id |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 新会话创建时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（image/audio/document/…） |
| `{{Transcript}}` | 音频转录文本 |
| `{{Prompt}}` | 用于 CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | 用于 CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力提供） |
| `{{GroupMembers}}` | 群组成员预览（尽力提供） |
| `{{SenderName}}` | 发送者显示名称（尽力提供） |
| `{{SenderE164}}` | 发送者电话号码（尽力提供） |
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 id |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 新建会话时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（image/audio/document/…） |
| `{{Transcript}}` | 音频转录文本 |
| `{{Prompt}}` | CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力而为） |
| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
| `{{SenderName}}` | 发送者显示名称（尽力而为） |
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
---
## 配置 include（`$include`）
将配置拆分到多个文件中：
将配置拆分为多个文件：
```json5
// ~/.openclaw/openclaw.json
@ -1190,14 +1213,14 @@ SecretRef 是增量式的：明文值仍然可用。
**合并行为：**
- 单个文件：替换其所在的包含对象。
- 单个文件：替换其所在的容器对象。
- 文件数组：按顺序深度合并（后者覆盖前者）。
- 同级键：在 includes 之后合并（覆盖已包含的值）。
- 嵌套 includes：最多支持 10 层。
- 路径：相对于包含它的文件解析，但必须保持在顶级配置目录（`openclaw.json` 的 `dirname`）内。只有在最终仍解析到该边界内时，才允许使用绝对路径 / `../` 形式。
- 当 OpenClaw 自有写入仅更改某个由单文件 include 支持的顶级 section 时，会直接写回该包含文件。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 的更新写入 `plugins.json5`，并保持 `openclaw.json` 不变。
- 根 includes、include 数组，以及带有同级覆盖的 includes 对于 OpenClaw 自有写入是只读的；这些写入会以关闭方式失败，而不是将配置展平。
- 错误：对于缺失文件、解析错误和循环 include，会提供清晰的错误消息。
- 同级键：在 includes 之后合并（覆盖 include 的值）。
- 嵌套 includes：最多支持 10 层深度。
- 路径：相对于发起 include 的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在最终仍解析到该边界内时，才允许使用绝对路径或 `../` 形式。
- 只变更某一个由单文件 include 支撑的顶层分区时，由 OpenClaw 负责的写入会直接写回该 include 文件。例如，`plugins install` 会把 `plugins: { $include: "./plugins.json5" }` 的更新写入 `plugins.json5`，并保持 `openclaw.json` 不变。
- 根级 include、include 数组以及带同级覆盖的 include 对于由 OpenClaw 负责的写入都是只读的；这些写入会以关闭方式失败，而不会将配置拍平。
- 错误：对缺失文件、解析错误和循环 include 提供清晰的报错信息。
---

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

@ -2,36 +2,37 @@
read_when:
- 首次设置 OpenClaw
- 查找常见配置模式
- 跳转到特定配置章节
- 导航到特定配置部分
summary: 配置概览：常见任务、快速设置，以及完整参考的链接
title: 配置
x-i18n:
generated_at: "2026-04-26T04:11:41Z"
generated_at: "2026-04-27T09:02:34Z"
model: gpt-5.4
provider: openai
source_hash: dc1148b93c00d30e34aad0ffb5e1d4dae5438a195a531f5247bbc9a261142350
source_hash: 1ceaa76b7bcf27240a21cfa4796c795f17d96128fd20e1ea8ed1d7dab59d4290
source_path: gateway/configuration.md
workflow: 15
---
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
当前使用的配置路径必须是一个常规文件。对于由 OpenClaw 管理的写入操作，不支持使用符号链接的 `openclaw.json`
布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
生效的配置路径必须是常规文件。对于 OpenClaw 自有写入，不支持使用符号链接的 `openclaw.json`
布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将
`OPENCLAW_CONFIG_PATH` 直接指向真实文件。
如果文件缺失，OpenClaw 会使用安全的默认值。常见的添加配置原因包括：
如果文件不存在，OpenClaw 会使用安全的默认值。添加配置的常见原因包括：
- 连接渠道并控制谁可以给机器人发消息
- 连接渠道并控制谁可以向机器人发送消息
- 设置模型、工具、沙箱隔离或自动化（cron、hooks）
- 调整会话、媒体、网络或 UI
请参阅[完整参考](/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>
## 最小配置
@ -53,7 +54,7 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
openclaw configure # 配置向导
```
</Tab>
<Tab title="CLI（单行命令）">
<Tab title="CLI（一行命令）">
```bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
@ -61,12 +62,12 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
```
</Tab>
<Tab title="Control UI">
打开 [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 节点及其直接子节点摘要。
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，使用 **配置** 选项卡。
Control UI 会根据实时配置 schema 渲染表单，包括字段
`title` / `description` 文档元数据，以及在可用时提供的插件和渠道 schema，
另有 **原始 JSON** 编辑器作为兜底入口。对于逐层下钻的
UI 和其他工具，Gateway 网关 还会公开 `config.schema.lookup`，用于获取
单个路径范围的 schema 节点及其直接子节点摘要。
</Tab>
<Tab title="直接编辑">
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
@ -76,37 +77,40 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
## 严格校验
<Warning>
OpenClaw 只接受完全匹配 schema 的配置。未知键名、错误类型或无效值都会导致 Gateway 网关 **拒绝启动**。根级别唯一的例外是 `$schema`（字符串），以便编辑器附加 JSON Schema 元数据。
OpenClaw 只接受完全符合 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关 **拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器才能附加 JSON Schema 元数据。
</Warning>
`openclaw config schema` 会打印 Control UI
和校验所使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围内的节点及其
子节点摘要，供深入查看工具使用。字段 `title`/`description` 文档元数据
会传递到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
`oneOf`/`allOf` 分支。在加载 manifest 注册表后，运行时插件和渠道 schema 也会合并进来。
和校验所使用的标准 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 会将损坏的文件保留为
`.clobbered.*`，恢复“最近一次正常配置”副本，并记录恢复原因。下一次智能体轮次
还会收到一条 system-event 警告，这样主智能体就不会盲目重写已恢复的配置。当候选配置包含诸如 `***` 之类被脱敏的密钥占位符时，
将其提升为“最近一次正常配置”的操作会被跳过。
每次成功启动后，Gateway 网关 都会保留一份可信的“最后已知可用”副本。
如果之后 `openclaw.json` 校验失败（或缺少 `gateway.mode`、内容
显著缩小，或前面意外插入了一行日志），OpenClaw 会将损坏的文件
保留为 `.clobbered.*`，恢复最后已知可用副本，并记录恢复原因。
下一次智能体轮次还会收到一条系统事件警告，这样主智能体就不会盲目重写已恢复的配置。
当候选配置包含诸如 `***` 之类的已脱敏密钥占位符时，
不会将其提升为最后已知可用版本。
当所有校验问题都限定在 `plugins.entries.<id>...` 范围内时，OpenClaw
不会执行整文件恢复。它会保持当前配置继续生效，并呈现插件局部失败，
以避免插件 schema 或宿主版本不匹配导致无关的用户设置被回滚。
不会执行整文件恢复。它会保持当前配置继续生效，并
展示插件局部失败信息，这样插件 schema 或宿主版本不匹配
就不会回滚无关的用户设置。
## 常见任务
<AccordionGroup>
<Accordion title="设置渠道（WhatsApp、Telegram、Discord 等）">
每个渠道在 `channels.<provider>` 下都有自己的配置章节。设置步骤请参见对应的专用渠道页面：
<Accordion title="设置一个渠道（WhatsApp、Telegram、Discord 等）">
每个渠道在 `channels.<provider>` 下都有自己的配置部分。设置步骤请参阅对应的渠道页面：
- [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
@ -119,7 +123,7 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
- [iMessage](/zh-CN/channels/imessage) — `channels.imessage`
- [Mattermost](/zh-CN/channels/mattermost) — `channels.mattermost`
所有渠道都共享相同的私信策略模式：
所有渠道都共享同一种私信策略模式：
```json5
{
@ -137,7 +141,7 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
</Accordion>
<Accordion title="选择并配置模型">
设置主模型和可选的回退模型：
设置主模型以及可选的回退模型：
```json5
{
@ -157,30 +161,30 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
```
- `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/tool 图像缩放的最大尺寸（默认 `1200`）；在大量使用截图的运行中，较低的值通常可减少视觉 token 使用量。
- 参见 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，参见 [Model Failover](/zh-CN/concepts/model-failover) 了解凭证轮换和回退行为。
- 对于自定义/自托管提供商，请参见参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图像的缩放下限（默认 `1200`）；较低的值通常会减少以截图为主的运行中的视觉 token 使用量。
- 参阅 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，参阅 [Model Failover](/zh-CN/concepts/model-failover) 了解凭证轮换和回退行为。
- 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
</Accordion>
<Accordion title="控制谁可以给机器人发消息">
私信访问通过各渠道的 `dmPolicy` 控制：
<Accordion title="控制谁可以向机器人发送消息">
私信访问通过每个渠道的 `dmPolicy` 控制：
- `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准
- `"allowlist"`：只有 `allowFrom`（或已配对允许存储）中的发送者才可访问
- `"pairing"`（默认）：未知发送者会收到一个一次性配对码以供批准
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者）
- `"open"`：允许所有传入私信（要求 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有私信
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的允许列表。
各渠道详情请参见[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)。
每个渠道的详细信息请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)。
</Accordion>
<Accordion title="设置群聊提及门控">
群组消息默认**要求提及**。可按智能体配置模式：
群消息默认**要求提及**。可按智能体配置模式：
```json5
{
@ -203,13 +207,13 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
```
- **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的安全 regex 模式
- 各渠道覆盖和 self-chat 模式请参见[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)。
- **文本模式**：`mentionPatterns` 中的安全正则表达式模式
- 每个渠道的覆盖规则和 self-chat 模式请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)。
</Accordion>
<Accordion title="按智能体限制 Skills">
使用 `agents.defaults.skills` 作为共享基线，然后通过
使用 `agents.defaults.skills` 作为共享基线，然后用
`agents.list[].skills` 覆盖特定智能体：
```json5
@ -219,24 +223,24 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
skills: ["github", "weather"],
},
list: [
{ id: "writer" }, // 继承 github、weather
{ id: "docs", skills: ["docs-search"] }, // 替换默认值
{ id: "locked-down", skills: [] }, // 不使用任何 Skills
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
{ id: "locked-down", skills: [] }, // no skills
],
},
}
```
- 省略 `agents.defaults.skills` 表示默认不限制 Skills。
- 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。
- 省略 `agents.list[].skills` 表示继承默认值。
- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。
- 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 以及
- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
- 参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 以及
[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
</Accordion>
<Accordion title="调整 Gateway 网关 渠道健康监控">
控制 Gateway 网关 对看起来卡住的渠道执行重启的积极程度：
<Accordion title="调整 gateway 渠道健康监控">
控制 gateway 对看起来已停滞的渠道执行重启的激进程度：
```json5
{
@ -260,13 +264,13 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
- 设置 `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="配置会话和重置">
会话控制对话的连续性和隔离性：
会话控制对话连续性和隔离：
```json5
{
@ -288,8 +292,8 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
- `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>
@ -311,7 +315,7 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
请先构建镜像：`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>
@ -336,43 +340,43 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
}
```
等效的 CLI 命令：
对应的 CLI：
```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```
这会执行以下操作：
作用如下：
- 允许 Gateway 网关 通过外部 relay 发送 `push.test`、唤醒 nudges 和重连唤醒。
- 使用由已配对 iOS 应用转发的、以注册为范围的发送授权。Gateway 网关 不需要部署范围的 relay token。
- 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关 身份，因此其他 Gateway 网关 无法复用已存储的注册信息。
- 本地/手动 iOS 构建仍然直接使用 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发构建。
- 必须与官方/TestFlight iOS 构建中内置的 relay 基础 URL 一致，这样注册和发送流量才能到达同一个 relay 部署。
- 让 gateway 能够通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
- 使用由已配对 iOS 应用转发的、作用域限定为注册的发送授权。gateway 不需要部署范围的 relay token。
- 将每个基于 relay 的注册绑定到 iOS 应用所配对的 gateway 身份，因此其他 gateway 无法复用已存储的注册。
- 让本地/手动构建的 iOS 版本继续使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。
- 必须与官方/TestFlight iOS 构建中固化的 relay 基础 URL 匹配，这样注册和发送流量才能到达同一个 relay 部署。
端到端流程：
1. 安装一个使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。
2. 在 Gateway 网关 上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与 Gateway 网关 配对，并让节点会话和操作员会话都连接。
4. iOS 应用会获取 Gateway 网关 身份，使用 App Attest 和应用收据向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
5. Gateway 网关 存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒 nudges 和重连唤醒。
2. 在 gateway 上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与 gateway 配对，并让节点会话和操作员会话都连接上。
4. iOS 应用会获取 gateway 身份，使用 App Attest 和应用收据向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 gateway。
5. gateway 会存储 relay 句柄和发送授权，并将其用于 `push.test`、唤醒提示和重连唤醒。
运行说明：
运维说明：
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布一个绑定到该 Gateway 网关 的新 relay 注册。
- 如果你将 iOS 应用切换到另一个 gateway，请重新连接应用，以便它发布一个绑定到该 gateway 的新 relay 注册。
- 如果你发布了一个指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。
兼容性说明：
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然是仅限 local loopback 的开发兜底方案；不要在配置中持久化 HTTP relay URL。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 loopback 的开发逃生舱；不要在配置中持久保存 HTTP relay URL。
端到端流程请参见 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参见[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。
端到端流程请参阅 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参阅[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。
</Accordion>
<Accordion title="设置 heartbeat（定期签到）">
<Accordion title="设置 heartbeat（定期检查）">
```json5
{
agents: {
@ -388,8 +392,8 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
- `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
- `directPolicy`：对于私信风格的 heartbeat 目标，使用 `allow`（默认）或 `block`
- 完整指南请参见 [Heartbeat](/zh-CN/gateway/heartbeat)。
- `directPolicy`：对私信式 heartbeat 目标使用 `allow`（默认）或 `block`
- 完整指南请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。
</Accordion>
@ -398,7 +402,7 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
{
cron: {
enabled: true,
maxConcurrentRuns: 2,
maxConcurrentRuns: 2, // cron 分发 + 隔离的 cron 智能体轮次执行
sessionRetention: "24h",
runLog: {
maxBytes: "2mb",
@ -408,13 +412,13 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
}
```
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
- `sessionRetention`：从 `sessions.json` 清理已完成的隔离运行会话（默认 `24h`；设为 `false` 可禁用）。
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
- 功能概览和 CLI 示例请参见 [Cron jobs](/zh-CN/automation/cron-jobs)。
- 功能概览和 CLI 示例请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)。
</Accordion>
<Accordion title="设置 webhooks（hooks）">
<Accordion title="设置 webhook（hooks）">
在 Gateway 网关 上启用 HTTP webhook 端点：
```json5
@ -439,20 +443,20 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
```
安全说明：
- 将所有 hook/webhook 负载内容都视为不受信任的输入。
- 将所有 hook/webhook 负载内容都视为不可信输入。
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 token。
- Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。
- `hooks.path` 不能为 `/`；请将 webhook 入口保持在专用子路径下，例如 `/hooks`。
- 保持不安全内容绕过标志处于禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在进行严格限定范围的调试。
- `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径下，例如 `/hooks`。
- 除非是在进行严格限定范围的调试，否则请保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。
- 如果你启用了 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选择的会话键。
- 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如尽可能仅限消息传递并配合沙箱隔离）。
- 对于由 hook 驱动的智能体，优先使用强力的现代模型层级和严格的工具策略（例如仅消息发送，并尽可能启用沙箱隔离）。
所有映射选项和 Gmail 集成请参见[完整参考](/zh-CN/gateway/configuration-reference#hooks)。
所有映射选项和 Gmail 集成请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。
</Accordion>
<Accordion title="配置多智能体路由">
运行多个隔离的智能体，并分别使用不同的工作区和会话：
运行多个相互隔离的智能体，并为它们设置独立的工作区和会话：
```json5
{
@ -469,11 +473,11 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
}
```
绑定规则和每个智能体的访问配置文件请参见 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)。
绑定规则和按智能体区分的访问配置文件请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)。
</Accordion>
<Accordion title="将配置拆分为多个文件（$include）">
<Accordion title="将配置拆分到多个文件中（$include）">
使用 `$include` 组织大型配置：
```json5
@ -487,49 +491,49 @@ Gateway 网关 会在每次成功启动后保留一份可信的“最近一次
}
```
- **单个文件**：替换其所在的对象
- **单个文件**：替换所在对象
- **文件数组**：按顺序深度合并（后者优先）
- **同级键**：在 include 之后合并（覆盖被包含的值）
- **嵌套 include**：支持，最多 10 层深度
- **同级键**：在 include 之后合并（覆盖被 include 的值）
- **嵌套 include**：支持，最多 10 层
- **相对路径**：相对于包含它的文件解析
- **由 OpenClaw 管理的写入**：当一次写入仅更改一个顶层章节，
且该章节由单文件 include 提供支持，例如 `plugins: { $include: "./plugins.json5" }`，
OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变
- **不支持的透传写入**：根级 include、include 数组以及带有
同级覆盖的 includes，在由 OpenClaw 管理的写入中会以失败关闭的方式处理，而不是
将配置展平
- **错误处理**：对于缺失文件、解析错误和循环 includes 提供清晰错误信息
- **OpenClaw 自有写入**：当一次写入只更改一个由单文件 include 支持的顶层部分时，
例如 `plugins: { $include: "./plugins.json5" }`，
OpenClaw 会更新该被 include 的文件，并保持 `openclaw.json` 不变
- **不支持透传写入**：根级 include、include 数组，以及带有同级覆盖的 include，
在 OpenClaw 自有写入场景下会以失败关闭，而不是
将配置拍平
- **错误处理**：对于缺失文件、解析错误和循环 include，会给出清晰错误
</Accordion>
</AccordionGroup>
## 配置热重载
Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——对于大多数设置，无需手动重启。
Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置都不需要手动重启。
直接编辑文件会在通过校验前被视为不受信任。监视器会等待
编辑器的临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复最近一次正常配置来拒绝
无效的外部编辑。由 OpenClaw 管理的
配置写入在写入前也会经过相同的 schema 闸门；诸如删除 `gateway.mode` 或文件体积缩小超过一半之类的破坏性覆盖
会被拒绝，并保存为 `.rejected.*` 以供检查。
直接编辑文件会在通过校验前被视为不可信。监视器会等待
编辑器临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复最后已知可用配置来拒绝
无效的外部编辑。OpenClaw 自有配置写入在落盘前也会经过同样的 schema 校验；诸如
删除 `gateway.mode` 或将文件缩小到原来一半以下之类的破坏性覆盖
会被拒绝，并另存为 `.rejected.*` 以供检查。
插件局部校验失败是个例外：如果所有问题都位于
`plugins.entries.<id>...` 下，重载会保持当前配置并报告该插件问题，
插件局部校验失败是一个例外：如果所有问题都位于
`plugins.entries.<id>...` 下，重载会保持当前配置，并报告插件问题，
而不是恢复 `.last-good`。
如果你在日志中看到 `Config auto-restored from last-known-good` 或
`config reload restored last-known-good config`，请检查 `openclaw.json` 旁边对应的
`config reload restored last-known-good config`，请检查 `openclaw.json` 同目录下对应的
`.clobbered.*` 文件，修复被拒绝的负载，然后运行
`openclaw config validate`。恢复检查清单请参见[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
`openclaw config validate`。恢复检查清单请参阅[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
### 重载模式
| 模式 | 行为 |
| ---------------------- | --------------------------------------------------------------------------------------- |
| **`hybrid`**（默认） | 立即热应用安全变更。对于关键变更会自动重启。 |
| **`hot`** | 仅热应用安全变更。当需要重启时记录警告——由你自行处理。 |
| **`restart`** | 对任何配置变更都重启 Gateway 网关，无论是否安全。 |
| **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 |
| **`hybrid`**（默认） | 立即热应用安全更改。对关键更改会自动重启。 |
| **`hot`** | 仅热应用安全更改。当需要重启时记录警告——由你手动处理。 |
| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 |
| **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 |
```json5
{
@ -541,11 +545,11 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
### 哪些可以热应用，哪些需要重启
大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会被自动处理。
大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
| 类别 | 字段 | 需要重启？ |
| ------------------- | ----------------------------------------------------------------- | --------------- |
| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置和插件渠道 | 否 |
| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置和插件渠道 | 否 |
| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 |
| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
| 会话和消息 | `session`、`messages` | 否 |
@ -560,39 +564,39 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
### 重载规划
当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会根据源文件编写时的布局来规划
重载，而不是依据展平后的内存视图。
这样即使某个
单独的顶层章节位于其自己的被包含文件中，例如
`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也仍然可预测。
如果源布局存在歧义，重载规划会以失败关闭的方式处理。
当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会根据源作者编写的布局来规划
重载，而不是根据拍平后的内存视图。
即使某个顶层部分单独存放在它自己的 include 文件中，
例如 `plugins: { $include: "./plugins.json5" }`，
这也能让热重载决策（热应用还是重启）保持可预测。
如果源布局存在歧义，重载规划会以失败关闭。
## 配置 RPC（程序化更新）
对于通过 Gateway 网关 API 写入配置的工具，优先使用以下流程：
对于通过 gateway API 写入配置的工具，优先使用以下流程：
- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子节点
摘要）
- 使用 `config.get` 获取当前快照及其 `hash`
- 使用 `config.patch` 进行部分更新（JSON merge patch：对象合并，`null`
- 使用 `config.get` 获取当前快照以及 `hash`
- 对于部分更新，使用 `config.patch`（JSON merge patch：对象合并，`null`
删除，数组替换）
- 仅在你打算替换整个配置时使用 `config.apply`
- 使用 `update.run` 显式执行自更新并重启
- 仅当你打算替换整个配置时才使用 `config.apply`
- 对于显式自更新加重启，使用 `update.run`
智能体应将 `config.schema.lookup` 视为获取精确
字段级文档和约束的首选入口。当它们需要更广泛的配置映射、默认值或指向专用
子系统参考的链接时，请使用[配置参考](/zh-CN/gateway/configuration-reference)。
字段级文档和约束的第一站。若需要更完整的配置映射、默认值或指向专用
子系统参考的链接，请使用[配置参考](/zh-CN/gateway/configuration-reference)。
<Note>
控制平面写入（`config.apply`、`config.patch`、`update.run`）会
按每个 `deviceId+clientIp` 在每 60 秒内限制为 3 次请求。
重启请求会合并处理，然后在两次重启周期之间强制 30 秒冷却时间。
控制平面写入（`config.apply`、`config.patch`、`update.run`）受到
速率限制：每个 `deviceId+clientIp` 在 60 秒内最多 3 次请求。
重启请求会被合并，然后在两次重启周期之间强制执行 30 秒冷却时间。
</Note>
部分 patch 示例：
示例部分 patch：
```bash
openclaw gateway call config.get --params '{}' # 获取 payload.hash
openclaw gateway call config.get --params '{}' # 捕获 payload.hash
openclaw gateway call config.patch --params '{
"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
"baseHash": "<hash>"
@ -608,7 +612,7 @@ openclaw gateway call config.patch --params '{
OpenClaw 会从父进程读取环境变量，另外还会读取：
- 当前工作目录中的 `.env`（如果存在）
- `~/.openclaw/.env`（全局兜底）
- `~/.openclaw/.env`（全局回退）
这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量：
@ -621,8 +625,8 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
}
```
<Accordion title="导入 Shell 环境变量（可选）">
如果启用，并且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键：
<Accordion title="Shell 环境导入（可选）">
如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键：
```json5
{
@ -632,10 +636,10 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
}
```
等效环境变量：`OPENCLAW_LOAD_SHELL_ENV=1`
环境变量等价写法：`OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="在配置值中替换环境变量">
<Accordion title="配置值中的环境变量替换">
你可以在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
```json5
@ -648,14 +652,14 @@ 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="SecretRef 引用（env、file、exec）">
对于支持 SecretRef 对象的字段，你可以使用：
```json5
@ -688,15 +692,15 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
}
```
SecretRef 的详细说明（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）请参见[Secrets Management](/zh-CN/gateway/secrets)。
支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见[密钥管理](/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)**。
---
@ -706,4 +710,4 @@ _相关内容：[配置示例](/zh-CN/gateway/configuration-examples) · [配置
- [配置参考](/zh-CN/gateway/configuration-reference)
- [配置示例](/zh-CN/gateway/configuration-examples)
- [Gateway 网关 运行手册](/zh-CN/gateway)
- [Gateway 网关 runbook](/zh-CN/gateway)

70
docs/zh-CN/install/updating.md
View File

@ -3,17 +3,17 @@ read_when:
- 更新 OpenClaw
- 更新后出现问题
summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略
title: 更新
title: 更新中
x-i18n:
generated_at: "2026-04-27T08:25:07Z"
generated_at: "2026-04-27T09:02:34Z"
model: gpt-5.4
provider: openai
source_hash: 6a509edaeb31b65f11d6dfe8656f8d415565fa4e0ea0cb6945b7cff2958bd70d
source_hash: 1f0ab7bf825068a5e2590011faab637d3ffe8d475f1737051d1726c93316af2a
source_path: install/updating.md
workflow: 15
---
让 OpenClaw 保持最新。
保持 OpenClaw 为最新版本。
## 推荐：`openclaw update`
@ -23,7 +23,7 @@ x-i18n:
openclaw update
```
要切换渠道或指定特定版本：
如需切换渠道或指定特定版本：
```bash
openclaw update --channel beta
@ -32,11 +32,11 @@ openclaw update --tag main
openclaw update --dry-run # 仅预览，不实际应用
```
`--channel beta` 会优先选择 beta，但当 beta 标签缺失或版本旧于最新稳定版时，运行时会回退到 stable/latest。若你想在一次性的包更新中使用原始 npm beta dist-tag，请使用 `--tag beta`。
`--channel beta` 会优先选择 beta，但当 beta 标签不存在，或其版本比最新 stable 发布更旧时，运行时会回退到 stable/latest。如果你想要一次性使用原始 npm beta dist-tag 进行包更新，请使用 `--tag beta`。
关于渠道语义，请参阅[开发渠道](/zh-CN/install/development-channels)。
有关渠道语义，请参阅 [Development channels](/zh-CN/install/development-channels)。
## 在 npm 安装和 git 安装之间切换
## 在 npm 和 git 安装之间切换
当你想更改安装类型时，请使用渠道。更新器会保留你在 `~/.openclaw` 中的状态、配置、凭证和工作区；它只会更改 CLI 和 Gateway 网关所使用的 OpenClaw 代码安装来源。
@ -48,42 +48,42 @@ openclaw update --channel dev
openclaw update --channel stable
```
先使用 `--dry-run` 运行，以预览具体的安装模式切换：
先使用 `--dry-run` 预览确切的安装模式切换：
```bash
openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run
```
`dev` 渠道会确保存在一个 git 检出，对其进行构建，并从该检出安装全局 CLI。`stable` 和 `beta` 渠道使用包安装。如果 Gateway 网关已经安装，`openclaw update` 会刷新服务元数据并重启它，除非你传入 `--no-restart`。
`dev` 渠道会确保存在一个 git 检出，对其进行构建，并从该检出安装全局 CLI。`stable` 和 `beta` 渠道使用包安装方式。如果 Gateway 网关已经安装，`openclaw update` 会刷新服务元数据并重启它，除非你传入 `--no-restart`。
## 替代方案：重新运行安装程序
## 备选方案：重新运行安装脚本
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
添加 `--no-onboard` 可跳过新手引导。若要通过安装程序强制指定特定安装类型，请传入 `--install-method git --no-onboard` 或 `--install-method npm --no-onboard`。
添加 `--no-onboard` 可跳过新手引导。要通过安装脚本强制指定安装类型，请传入 `--install-method git --no-onboard` 或 `--install-method npm --no-onboard`。
如果 `openclaw update` 在 npm 包安装阶段之后失败，请重新运行安装程序。安装程序不会调用旧的更新器；它会直接运行全局包安装，并且可以恢复部分更新的 npm 安装。
如果 `openclaw update` 在 npm 包安装阶段之后失败，请重新运行安装脚本。安装脚本不会调用旧版更新器；它会直接运行全局包安装，因此可以恢复部分更新失败的 npm 安装。
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
```
要将恢复固定到特定版本或 dist-tag，请添加 `--version`：
如需将恢复固定到特定版本或 dist-tag，请添加 `--version`：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
```
## 替代方案：手动使用 npm、pnpm 或 bun
## 备选方案：手动使用 npm、pnpm 或 bun
```bash
npm i -g openclaw@latest
```
当 `openclaw update` 管理全局 npm 安装时，它会先运行常规的全局安装命令。如果该命令失败，OpenClaw 会使用 `--omit=optional` 重试一次。这次重试有助于处理那些无法编译原生可选依赖的主机，同时如果回退方案也失败，仍会保留原始失败信息。
当 `openclaw update` 管理全局 npm 安装时，它会先运行常规的全局安装命令。如果该命令失败，OpenClaw 会使用 `--omit=optional` 重试一次。这次重试有助于解决原生可选依赖无法编译的主机场景，同时如果回退方案也失败，原始失败信息仍会保留并可见。
```bash
pnpm add -g openclaw@latest
@ -97,12 +97,12 @@ bun add -g openclaw@latest
<AccordionGroup>
<Accordion title="只读包树">
即使当前用户对全局包目录具有写权限，OpenClaw 在运行时仍会将打包后的全局安装视为只读。内置插件的运行时依赖会暂存到一个可写的运行时目录，而不是直接修改包树。这样可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体在同一次安装中修复插件依赖时发生竞争。
OpenClaw 在运行时会将打包的全局安装视为只读，即使当前用户对全局包目录具有写权限也是如此。内置插件的运行时依赖会暂存到可写的运行时目录中，而不是直接修改包树。这样可以避免在同一次安装期间，`openclaw update` 与正在修复插件依赖的 Gateway 网关或本地智能体发生竞争。
一些 Linux npm 环境会将全局包安装到由 root 拥有的目录中，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过同样的外部暂存路径支持这种布局。
某些 Linux npm 配置会将全局包安装到由 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过相同的外部暂存路径支持这种布局。
</Accordion>
<Accordion title="加固的 systemd 单元">
<Accordion title="强化的 systemd 单元">
设置一个包含在 `ReadWritePaths` 中的可写暂存目录：
```ini
@ -110,29 +110,30 @@ bun add -g openclaw@latest
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
```
`OPENCLAW_PLUGIN_STAGE_DIR` 也接受路径列表。OpenClaw 会按从左到右的顺序，在列出的根路径中解析内置插件运行时依赖，将靠前的根视为只读的预装层，并且只会安装或修复到最后一个可写根中：
`OPENCLAW_PLUGIN_STAGE_DIR` 也接受路径列表。OpenClaw 会按照从左到右的顺序，在列出的根目录中解析内置插件的运行时依赖，将前面的根目录视为只读的预安装层，并且只在最后一个可写根目录中安装或修复：
```ini
Environment=OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
```
如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，当 systemd 提供 `$STATE_DIRECTORY` 时，OpenClaw 会使用它；否则回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存区视为 OpenClaw 自有的本地包根目录，并忽略用户的 npm prefix 和全局设置，因此全局安装的 npm 配置不会将内置插件依赖重定向到 `~/node_modules` 或全局包树中。
如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，当 systemd 提供 `$STATE_DIRECTORY` 时，OpenClaw 会优先使用它；否则回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存目录视为 OpenClaw 自有的本地包根目录，并忽略用户的 npm prefix 和全局设置，因此全局安装 npm 配置不会把内置插件依赖重定向到 `~/node_modules` 或全局包树中。
</Accordion>
<Accordion title="磁盘空间预检查">
在进行包更新和内置运行时依赖修复之前，OpenClaw 会尽力对目标卷执行磁盘空间检查。空间不足会产生一条包含已检查路径的警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的 npm 安装、复制和安装后验证仍然是最终依据。
在包更新和内置运行时依赖修复之前，OpenClaw 会尽力对目标卷执行磁盘空间检查。空间不足时会针对被检查路径发出警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的 npm 安装、复制和安装后验证仍然是最终依据。
</Accordion>
<Accordion title="内置插件运行时依赖">
打包安装会将内置插件运行时依赖保留在只读包树之外。在启动时以及执行 `openclaw doctor --fix` 期间，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于活跃状态、通过旧版渠道配置处于活跃状态，或由其内置清单默认启用的插件。仅有已持久化的渠道认证状态，并不会触发 Gateway 网关启动时的运行时依赖修复。
打包安装会将内置插件运行时依赖保留在只读包树之外。在启动期间以及执行 `openclaw doctor --fix` 时，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置清单默认启用。仅有已持久化的渠道认证状态，并不会触发 Gateway 网关启动时的运行时依赖修复。
显式禁用优先。已禁用的插件或渠道不会仅因存在于包中就修复其运行时依赖。外部插件和自定义加载路径仍然使用 `openclaw plugins install` 或 `openclaw plugins update`。
显式禁用优先。被禁用的插件或渠道不会仅因为存在于安装包中就触发其运行时依赖修复。外部插件和自定义加载路径仍然应使用 `openclaw plugins install` 或 `openclaw plugins update`。
</Accordion>
</AccordionGroup>
## 自动更新器
自动更新器默认关闭。在 `~/.openclaw/openclaw.json` 中启用它：
自动更新器默认关闭。在 `~/.openclaw/openclaw.json` 中启用：
```json5
{
@ -148,13 +149,14 @@ bun add -g openclaw@latest
}
```
| Channel | 行为 |
| -------- | ---- |
| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内以确定性的抖动时间应用更新（分散发布）。 |
| 渠道 | 行为 |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内使用确定性抖动进行应用（分散发布）。 |
| `beta` | 每隔 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 |
| `dev` | 不会自动应用。请手动使用 `openclaw update`。 |
| `dev` | 不自动应用。请手动使用 `openclaw update`。 |
Gateway 网关还会在启动时记录一条更新提示（可通过 `update.checkOnStart: false` 禁用）。
Gateway 网关也会在启动时记录更新提示（可通过 `update.checkOnStart: false` 禁用）。
对于降级或事故恢复，请在 Gateway 网关环境中设置 `OPENCLAW_NO_AUTO_UPDATE=1`，即使已配置 `update.auto.enabled` 也会阻止自动应用。除非同时禁用 `update.checkOnStart`，否则启动时的更新提示仍可能运行。
## 更新后
@ -166,7 +168,7 @@ Gateway 网关还会在启动时记录一条更新提示（可通过 `update.che
openclaw doctor
```
迁移配置、审计私信策略，并检查 Gateway 网关健康状态。详情参见：[Doctor](/zh-CN/gateway/doctor)
迁移配置、审计私信策略，并检查 Gateway 网关健康状态。详情请参阅：[Doctor](/zh-CN/gateway/doctor)
### 重启 Gateway 网关
@ -196,7 +198,7 @@ openclaw gateway restart
`npm view openclaw version` 会显示当前已发布版本。
</Tip>
### 固定到某个提交（源码）
### 固定提交（源码）
```bash
git fetch origin
@ -205,12 +207,12 @@ pnpm install && pnpm build
openclaw gateway restart
```
要返回到最新版本：`git checkout main && git pull`。
要恢复到最新版本：`git checkout main && git pull`。
## 如果你卡住了
- 再次运行 `openclaw doctor`，并仔细阅读输出内容。
- 对于源码检出中的 `openclaw update --channel dev`，更新器会在需要时自动引导安装 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。
- 对于源码检出上的 `openclaw update --channel dev`，更新器会在需要时自动引导安装 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。
- 查看：[故障排除](/zh-CN/gateway/troubleshooting)
- 在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd)

333
docs/zh-CN/tools/browser.md
View File

@ -3,37 +3,37 @@ read_when:
- 添加由智能体控制的浏览器自动化
- 调试为什么 openclaw 会干扰你自己的 Chrome
- 在 macOS 应用中实现浏览器设置 + 生命周期
summary: 集成的浏览器控制服务 + 操作命令
title: 浏览器（OpenClaw 管理）
summary: 集成浏览器控制服务 + 操作命令
title: 浏览器（由 OpenClaw 管理）
x-i18n:
generated_at: "2026-04-27T08:44:47Z"
generated_at: "2026-04-27T09:02:34Z"
model: gpt-5.4
provider: openai
source_hash: 65397ea2405aeb34d4e08c8968f3dc15ab8ed446c69d77274f069fc72f90c59a
source_hash: a8f0456505f4e1711626a539a0a0c48d67ca10d4788838eb53855bc83c766d2f
source_path: tools/browser.md
workflow: 15
---
OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。
它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理（仅 loopback）。
它与你的个人浏览器隔离，并通过 Gateway 网关 内部的一个小型本地控制服务进行管理
（仅限 loopback）。
新手视角：
初学者视角：
- 把它看作一个**独立的、仅供智能体使用的浏览器**。
- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。
- `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。
- 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。
- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的已登录 Chrome 会话。
- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的、已登录的 Chrome 会话。
## 你会获得什么
## 你将获得什么
- 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。
- 可预测的标签页控制（列出/打开/聚焦/关闭）。
- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。
- 一个内置的 `browser-automation` Skills，用于在启用浏览器插件时，教会智能体使用 snapshot、stable-tab、stale-ref 和 manual-blocker 恢复循环。
- 一个内置的 `browser-automation` Skills，在启用浏览器插件时，会教会智能体使用快照、稳定标签页、过期引用和手动阻塞恢复循环。
- 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。
这个浏览器**不是**你日常使用的主力浏览器。
它是一个安全、隔离的表面，用于智能体自动化和验证。
这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的界面，用于智能体自动化和验证。
## 快速开始
@ -46,13 +46,14 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。
如果你看到“浏览器已禁用”，请在配置中启用它（见下文），然后重启
Gateway 网关。
如果 `openclaw browser` 完全不存在，或者智能体提示浏览器工具不可用，请跳转到[缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。
如果根本没有 `openclaw browser`，或者智能体提示浏览器工具不可用，请跳转到[缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。
## 插件控制
默认的 `browser` 工具是一个内置插件。禁用它即可用另一个注册相同 `browser` 工具名称的插件替换它：
默认的 `browser` 工具是一个内置插件。禁用它可以用另一个注册同名 `browser` 工具的插件来替换它：
```json5
{
@ -66,13 +67,14 @@ openclaw browser --browser-profile openclaw snapshot
}
```
默认值需要同时设置 `plugins.entries.browser.enabled` **以及** `browser.enabled=true`。如果只禁用插件，就会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保持不变，以供替代方案使用。
默认值需要同时设置 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。仅禁用插件会将 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务作为一个整体移除；你的 `browser.*` 配置会保持不变，以便替换方案继续使用。
浏览器配置更改需要重启 Gateway 网关，以便插件重新注册其服务。
浏览器配置更改需要重启 Gateway 网关，这样插件才能重新注册其服务。
## 智能体指引
工具配置文件说明：`tools.profile: "coding"` 包含 `web_search` 和 `web_fetch`，但不包含完整的 `browser` 工具。如果智能体或生成的子智能体需要使用浏览器自动化，请在配置文件阶段添加 browser：
工具配置文件说明：`tools.profile: "coding"` 包含 `web_search` 和
`web_fetch`，但不包含完整的 `browser` 工具。如果智能体或生成的子智能体应该使用浏览器自动化，请在配置文件阶段加入 browser：
```json5
{
@ -84,18 +86,18 @@ openclaw browser --browser-profile openclaw snapshot
```
对于单个智能体，使用 `agents.list[].tools.alsoAllow: ["browser"]`。
仅设置 `tools.subagents.tools.allow: ["browser"]` 还不够，因为子智能体策略会在配置文件过滤之后应用。
仅设置 `tools.subagents.tools.allow: ["browser"]` 还不够，因为子智能体策略会在配置文件过滤之后才应用。
浏览器插件提供两个层级的智能体指引：
浏览器插件提供两层智能体指引：
- `browser` 工具说明携带精简且始终启用的契约：选择正确的配置文件，在同一标签页中保持 refs，使用 `tabId`/标签来定位标签页，并在多步骤任务中加载浏览器 Skills。
- 内置的 `browser-automation` Skills 携带更长的操作循环：先检查状态/标签页，为任务标签页打标签，操作前先做快照，UI 变化后重新快照，过期引用恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。
- `browser` 工具说明携带了精简的始终启用契约：选择正确的配置文件，在同一个标签页中保持引用，使用 `tabId`/标签 来定位标签页，并在多步骤任务中加载浏览器 Skills。
- 内置的 `browser-automation` Skills 携带了更完整的操作循环：先检查状态/标签页，给任务标签页加标签，操作前先做快照，在 UI 变化后重新快照，过期引用恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是靠猜测处理。
启用插件后，插件内置 Skills 会列在智能体可用 Skills 中。完整的 Skills 指令按需加载，因此日常轮次不会承担完整的 token 成本。
启用插件后，插件内置的 Skills 会列在智能体可用 Skills 中。完整的 Skills 指令会按需加载，因此常规轮次无需承担完整的 token 成本。
## 缺少浏览器命令或工具
如果升级后 `openclaw browser` 无法识别、`browser.request` 缺失，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`，并且不存在根级 `browser` 配置块。请添加它：
如果升级后 `openclaw browser` 未知、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表遗漏了 `browser`，并且不存在根级 `browser` 配置块。请添加它：
```json5
{
@ -105,20 +107,20 @@ openclaw browser --browser-profile openclaw snapshot
}
```
显式的根级 `browser` 块，例如 `browser.enabled=true` 或 `browser.profiles.<name>`，即使在严格的 `plugins.allow` 下，也会激活内置浏览器插件，这与渠道配置行为一致。仅设置 `plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 本身不能替代 allowlist 成员资格。完全移除 `plugins.allow` 也会恢复默认行为。
显式的根级 `browser` 配置块，例如 `browser.enabled=true` 或 `browser.profiles.<name>`，即使在限制性的 `plugins.allow` 下，也会激活内置浏览器插件，这与渠道配置行为一致。仅靠 `plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 并不能替代 allowlist 成员资格。完全移除 `plugins.allow` 也会恢复默认行为。
## 配置文件：`openclaw` 与 `user`
- `openclaw`：受管、隔离的浏览器（无需扩展）。
- `openclaw`：受管理、隔离的浏览器（无需扩展）。
- `user`：内置的 Chrome MCP 附加配置文件，用于你的**真实已登录 Chrome** 会话。
对于智能体浏览器工具调用：
- 默认：使用隔离的 `openclaw` 浏览器。
- 当已有登录会话很重要，并且用户在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。
- 当你想指定特定浏览器模式时，`profile` 是显式覆盖项。
- 当现有已登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。
- 当你想要特定浏览器模式时，`profile` 是显式覆盖项。
如果你希望默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。
如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。
## 配置
@ -179,49 +181,51 @@ openclaw browser --browser-profile openclaw snapshot
<AccordionGroup>
<Accordion title="端口与可达性">
<Accordion title="端口和可达性">
- 控制服务绑定到 loopback 上，其端口根据 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让同一端口族中的派生端口一起变化。
- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅远程 CDP 需要设置这些项。未设置时，`cdpUrl` 默认使用受管本地 CDP 端口。
- 控制服务绑定到 loopback 上的一个端口，该端口从 `gateway.port` 派生而来（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会以同一端口族方式平移这些派生端口。
- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要设置这些值。未设置时，`cdpUrl` 默认为受管理的本地 CDP 端口。
- `remoteCdpTimeoutMs` 适用于远程和 `attachOnly` CDP HTTP 可达性检查，以及打开标签页的 HTTP 请求；`remoteCdpHandshakeTimeoutMs` 适用于它们的 CDP WebSocket 握手。
- `localLaunchTimeoutMs` 是本地启动的受管 Chrome 进程暴露其 CDP HTTP 端点的时间预算。`localCdpReadyTimeoutMs` 是在发现该进程后，为 CDP websocket 就绪预留的后续时间预算。在 Raspberry Pi、低配 VPS 或较旧硬件上，如果 Chromium 启动较慢，请提高这些值。取值必须是正整数，且不超过 `120000` ms；无效的配置值会被拒绝。
- `actionTimeoutMs` 是浏览器 `act` 请求的默认时间预算，当调用方未传递 `timeoutMs` 时使用。客户端传输层会增加一个较小的宽限窗口，以便较长等待可以完成，而不是在 HTTP 边界超时。
- `tabCleanup` 是针对由主智能体浏览器会话打开的标签页的尽力清理。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们明确跟踪的标签页；主会话会保留活动标签页以便复用，然后在后台关闭空闲或超出数量的已跟踪标签页。
- `localLaunchTimeoutMs` 是本地启动的受管理 Chrome 进程暴露其 CDP HTTP 端点的时间预算。`localCdpReadyTimeoutMs` 是在发现进程后，为 CDP websocket 就绪提供的后续时间预算。在 Raspberry Pi、低端 VPS 或 Chromium 启动较慢的旧硬件上，可以提高这些值。值必须是最大不超过 `120000` ms 的正整数；无效的配置值会被拒绝。
- 对于反复发生的受管理 Chrome 启动/就绪失败，会按配置文件进行熔断处理。在连续失败数次后，OpenClaw 会短暂停止新的启动尝试，而不是在每次浏览器工具调用时都生成一个 Chromium 进程。请修复启动问题、在不需要时禁用浏览器，或在修复后重启 Gateway 网关。
- `actionTimeoutMs` 是浏览器 `act` 请求的默认时间预算，当调用方未传递 `timeoutMs` 时使用。客户端传输层会增加一个小的宽限窗口，让长时间等待能够完成，而不会在 HTTP 边界处超时。
- `tabCleanup` 是针对主智能体浏览器会话所打开标签页的尽力清理机制。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们显式跟踪的标签页；主会话会让活动标签页保持可复用，然后在后台关闭空闲或超量的已跟踪标签页。
</Accordion>
<Accordion title="SSRF 策略">
- 浏览器导航和打开标签页在导航前会受到 SSRF 防护，并会在导航完成后的最终 `http(s)` URL 上进行尽力重新检查。
- 浏览器导航和打开标签页在导航前会受到 SSRF 防护，并在最终 `http(s)` URL 上尽力再次检查。
- 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。
- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理 OpenClaw 管理的浏览器。默认情况下，受管 Chrome 会直接启动，因此提供商代理设置不会削弱浏览器 SSRF 检查。
- 如果要代理受管浏览器本身，请通过 `browser.extraArgs` 传递显式 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。除非明确启用了私有网络浏览器访问，否则严格 SSRF 模式会阻止显式浏览器代理路由。
- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理由 OpenClaw 管理的浏览器。受管理的 Chrome 默认直接启动，因此提供商代理设置不会削弱浏览器 SSRF 检查。
- 如需代理受管理浏览器本身，请通过 `browser.extraArgs` 传递显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式浏览器代理路由，除非已明确启用私有网络浏览器访问。
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；只有在你明确可信任私有网络浏览器访问时才启用它。
- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧别名受到支持。
- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受到支持。
</Accordion>
<Accordion title="配置文件行为">
- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已运行时附加。
- `headless` 可以全局设置，也可以按本地受管配置文件设置。按配置文件设置的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持 headless，而另一个保持可见。
- `POST /start?headless=true` 和 `openclaw browser start --headless` 会为本地受管配置文件请求一次性的 headless 启动，而不会改写 `browser.headless` 或配置文件配置。现有会话、仅附加和远程 CDP 配置文件会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。
- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，如果环境或配置文件/全局配置都没有显式选择有界面模式，本地受管配置文件会自动默认使用 headless。`openclaw browser status --json` 会将 `headlessSource` 报告为 `env`、`profile`、`config`、`request`、`linux-display-fallback` 或 `default`。
- `OPENCLAW_BROWSER_HEADLESS=1` 会强制当前进程启动的本地受管浏览器使用 headless。`OPENCLAW_BROWSER_HEADLESS=0` 会强制普通启动使用有界面模式，并在没有显示服务器的 Linux 主机上返回可操作的错误；显式的 `start --headless` 请求仍会在该次启动中优先生效。
- `executablePath` 可以全局设置，也可以按本地受管配置文件设置。按配置文件设置的值会覆盖 `browser.executablePath`，因此不同的受管配置文件可以启动不同的基于 Chromium 的浏览器。这两种形式都接受 `~` 作为你的操作系统主目录。
- `color`（顶层和按配置文件）会为浏览器 UI 着色，以便你看到当前活动的是哪个配置文件。
- 默认配置文件是 `openclaw`（受管独立模式）。使用 `defaultProfile: "user"` 可选择已登录用户浏览器。
- 自动检测顺序：如果系统默认浏览器基于 Chromium，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。
- `attachOnly: true` 表示绝不启动本地浏览器；只有在浏览器已经运行时才附加。
- `headless` 可以全局设置，也可以按本地受管理配置文件单独设置。按配置文件设置的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持无头模式，而另一个仍保持可见。
- `POST /start?headless=true` 和 `openclaw browser start --headless` 会为本地受管理配置文件请求一次性无头启动，而不会改写 `browser.headless` 或配置文件配置。existing-session、attach-only 和远程 CDP 配置文件会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。
- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，如果环境或配置文件/全局配置都没有显式选择有头模式，则本地受管理配置文件会自动默认使用无头模式。`openclaw browser status --json` 会将 `headlessSource` 报告为 `env`、`profile`、`config`、`request`、`linux-display-fallback` 或 `default`。
- `OPENCLAW_BROWSER_HEADLESS=1` 会为当前进程强制本地受管理启动使用无头模式。`OPENCLAW_BROWSER_HEADLESS=0` 会为普通启动强制有头模式，并在没有显示服务器的 Linux 主机上返回可执行的错误信息；显式的 `start --headless` 请求仍会在那一次启动中优先生效。
- `executablePath` 可以全局设置，也可以按本地受管理配置文件单独设置。按配置文件设置的值会覆盖 `browser.executablePath`，因此不同的受管理配置文件可以启动不同的 Chromium 系浏览器。这两种形式都接受 `~` 来表示你的操作系统主目录。
- `color`（顶层和按配置文件）会为浏览器 UI 着色，以便你看出当前活动的是哪个配置文件。
- 默认配置文件是 `openclaw`（受管理的独立模式）。使用 `defaultProfile: "user"` 可选择默认使用已登录的用户浏览器。
- 自动检测顺序：如果系统默认浏览器是 Chromium 系，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。
- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为该驱动设置 `cdpUrl`。
- 当 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles.<name>.userDataDir`。这个路径同样接受 `~` 作为你的操作系统主目录。
- 当 existing-session 配置文件应附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles.<name>.userDataDir`。该路径同样接受 `~` 来表示你的操作系统主目录。
</Accordion>
</AccordionGroup>
## 使用 Brave 或其他基于 Chromium 的浏览器
## 使用 Brave 或其他 Chromium 系浏览器
如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖自动检测。顶层和按配置文件设置的 `executablePath` 值都接受 `~` 作为你的操作系统主目录：
如果你的**系统默认**浏览器是 Chromium 系（Chrome/Brave/Edge 等），
OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖自动检测。顶层和按配置文件的 `executablePath` 值都接受 `~` 表示你的操作系统主目录：
```bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"
@ -260,46 +264,47 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C
</Tab>
</Tabs>
按配置文件设置的 `executablePath` 只会影响 OpenClaw 启动的本地受管配置文件。`existing-session` 配置文件则会附加到一个已经运行的浏览器，而远程 CDP 配置文件使用 `cdpUrl` 背后的浏览器。
按配置文件设置的 `executablePath` 仅影响由 OpenClaw 启动的本地受管理配置文件。`existing-session` 配置文件会附加到一个已在运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。
## 本地控制与远程控制
- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并且可以启动本地浏览器。
- **远程控制（节点主机）：** 在拥有浏览器的机器上运行节点主机；Gateway 网关会将浏览器操作代理到该节点主机。
- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
- 对于运行在 loopback 上的外部管理 CDP 服务（例如发布到 `127.0.0.1` 的 Docker 中的 Browserless），还需要设置 `attachOnly: true`。如果 loopback CDP 未设置 `attachOnly`，则会被视为由 OpenClaw 管理的本地浏览器配置文件。
- `headless` 仅影响 OpenClaw 启动的本地受管配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。
- `executablePath` 遵循相同的本地受管配置文件规则。在一个正在运行的本地受管配置文件上更改它时，该配置文件会被标记为需要重启/协调，以便下一次启动使用新的二进制文件。
- **本地控制（默认）：** Gateway 网关 启动 loopback 控制服务，并且可以启动本地浏览器。
- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关 会将浏览器操作代理到该节点主机。
- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程的 Chromium 系浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
- 对于运行在 loopback 上的外部管理 CDP 服务（例如在 Docker 中发布到 `127.0.0.1` 的 Browserless），还要设置 `attachOnly: true`。如果 loopback CDP 未设置 `attachOnly`，则会被视为本地的 OpenClaw 受管理浏览器配置文件。
- `headless` 仅影响由 OpenClaw 启动的本地受管理配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。
- `executablePath` 遵循相同的本地受管理配置文件规则。在一个正在运行的本地受管理配置文件上更改它时，该配置文件会被标记为需要重启/协调，以便下一次启动时使用新的二进制文件。
停止行为会因配置文件模式而异：
停止行为因配置文件模式而异：
- 本地受管配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程
- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭活动控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、配色方案、区域设置、时区、离线模式及类似状态），即使浏览器进程并非由 OpenClaw 启动
- 本地受管理配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程
- attach-only 和远程 CDP 配置文件：`openclaw browser stop` 会关闭活动控制会话，并释放 Playwright/CDP 模拟覆盖（视口、配色方案、区域设置、时区、离线模式及类似状态），即使没有任何浏览器进程是由 OpenClaw 启动的
远程 CDP URL 可以包含认证信息：
- 查询参数 token（例如 `https://provider.example?token=<token>`）
- HTTP Basic auth（例如 `https://user:pass@provider.example`）
- HTTP Basic 认证（例如 `https://user:pass@provider.example`）
OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时都会保留这些认证信息。对于 token，优先使用环境变量或密钥管理器，而不是将其提交到配置文件中。
OpenClaw 在调用 `/json/*` 端点以及连接 CDP WebSocket 时都会保留认证信息。对于 token，优先使用环境变量或密钥管理器，而不是将其提交到配置文件中。
## 节点浏览器代理（默认零配置）
如果你在拥有浏览器的机器上运行了**节点主机**，OpenClaw 可以自动将浏览器工具调用路由到该节点，而无需任何额外的浏览器配置。对于远程 Gateway 网关，这是默认路径。
如果你在拥有浏览器的机器上运行了一个**节点主机**，OpenClaw 可以将浏览器工具调用自动路由到该节点，而无需任何额外浏览器配置。
这是远程 Gateway 网关 的默认路径。
说明：
- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。
- 配置文件来自节点自己的 `browser.profiles` 配置（与本地相同）。
- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空即可保留旧版/默认行为：所有已配置的配置文件都可通过该代理访问，包括配置文件创建/删除路由。
- `nodeHost.browserProxy.allowProfiles` 是可选的。留空即可保留旧版/默认行为：所有已配置的配置文件都仍可通过代理访问，包括配置文件创建/删除路由。
- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的配置文件可以作为目标，并且持久化配置文件创建/删除路由会在代理表面被阻止。
- 如果你不想启用它，可以禁用：
- 如果你不想启用它，可将其禁用：
- 在节点上：`nodeHost.browserProxy.enabled=false`
- 在 gateway 上：`gateway.nodes.browser.mode="off"`
## Browserless（托管远程 CDP）
[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，它通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 可以使用任一形式，但对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中提供的直接 WebSocket URL。
[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 两种形式都可以使用，但对于远程浏览器配置文件，最简单的方式是使用 Browserless 连接文档中的直接 WebSocket URL。
示例：
@ -322,13 +327,13 @@ OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时都会保留
说明：
- 将 `<BROWSERLESS_API_KEY>` 替换为你真实的 Browserless token。
- 选择与你的 Browserless 账户匹配的区域端点（见其文档）。
- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 以建立直接 CDP 连接，或者保留该 HTTPS URL，让 OpenClaw 去发现 `/json/version`。
- 将 `<BROWSERLESS_API_KEY>` 替换为你的真实 Browserless token。
- 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。
- 如果 Browserless 提供的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 以建立直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw 去发现 `/json/version`。
### 同一主机上的 Browserless Docker
当 Browserless 以 Docker 形式自托管，而 OpenClaw 运行在宿主机上时，应将 Browserless 视为一个外部管理的 CDP 服务：
当 Browserless 在 Docker 中自托管，而 OpenClaw 在主机上运行时，应将 Browserless 视为一个外部管理的 CDP 服务：
```json5
{
@ -346,22 +351,23 @@ OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时都会保留
}
```
`browser.profiles.browserless.cdpUrl` 中的地址必须能被 OpenClaw 进程访问。Browserless 也必须通告一个同样可访问的匹配端点；将 Browserless 的 `EXTERNAL` 设置为同一个面向 OpenClaw 的 WebSocket 基地址，例如 `ws://127.0.0.1:3000`、`ws://browserless:3000`，或稳定的私有 Docker 网络地址。如果 `/json/version` 返回的 `webSocketDebuggerUrl` 指向的是 OpenClaw 无法访问的地址，那么 CDP HTTP 看起来可能正常，但 WebSocket 附加仍会失败。
`browser.profiles.browserless.cdpUrl` 中的地址必须能从 OpenClaw 进程访问到。Browserless 还必须通告一个同样可达的匹配端点；请将 Browserless 的 `EXTERNAL` 设置为同一个从 OpenClaw 可访问的 WebSocket 基址，例如 `ws://127.0.0.1:3000`、`ws://browserless:3000` 或稳定的私有 Docker 网络地址。如果 `/json/version` 返回的 `webSocketDebuggerUrl` 指向了 OpenClaw 无法访问的地址，那么 CDP HTTP 看起来可能正常，但 WebSocket 附加仍然会失败。
对于 loopback Browserless 配置文件，不要让 `attachOnly` 保持未设置。没有 `attachOnly` 时，OpenClaw 会将该 loopback 端口视为本地受管浏览器配置文件，并且可能报告该端口正在使用但不属于 OpenClaw。
不要让 loopback Browserless 配置文件的 `attachOnly` 保持未设置。没有 `attachOnly` 时，OpenClaw 会把该 loopback 端口视为本地受管理浏览器配置文件，并可能报告该端口已被占用但并非由 OpenClaw 持有。
## 直接 WebSocket CDP 提供商
一些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略：
有些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略：
- **HTTP(S) 发现** —— `http://host[:port]` 或 `https://host[:port]`。
OpenClaw 调用 `/json/version` 来发现 WebSocket 调试器 URL，然后再连接。没有 WebSocket 回退。
- **直接 WebSocket 端点** —— `ws://host[:port]/devtools/<kind>/<id>` 或带有 `/devtools/browser|page|worker|shared_worker|service_worker/<id>` 路径的 `wss://...`。OpenClaw 直接通过 WebSocket 握手连接，并完全跳过 `/json/version`。
- **裸 WebSocket 根地址** —— 没有 `/devtools/...` 路径的 `ws://host[:port]` 或 `wss://host[:port]`（例如 [Browserless](https://browserless.io)、[Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP `/json/version` 发现（把协议规范化为 `http`/`https`）；如果发现过程返回了 `webSocketDebuggerUrl`，则使用它，否则 OpenClaw 会回退到在裸根地址上直接进行 WebSocket 握手。如果通告的 WebSocket 端点拒绝 CDP 握手，但已配置的裸根地址接受它，OpenClaw 也会回退到该根地址。这样一来，指向本地 Chrome 的裸 `ws://` 依然可以连接，因为 Chrome 只接受 `/json/version` 中特定按目标划分路径上的 WebSocket 升级；而托管提供商在其发现端点通告了不适用于 Playwright CDP 的短时 URL 时，仍然可以使用它们的根 WebSocket 端点。
- **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。
OpenClaw 调用 `/json/version` 来发现 WebSocket 调试器 URL，然后进行连接。没有 WebSocket 回退。
- **直接 WebSocket 端点** — `ws://host[:port]/devtools/<kind>/<id>` 或
`wss://...`，路径为 `/devtools/browser|page|worker|shared_worker|service_worker/<id>`。OpenClaw 直接通过 WebSocket 握手连接，并完全跳过 `/json/version`。
- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，没有 `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、[Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP `/json/version` 发现（将协议规范化为 `http`/`https`）；如果发现结果返回了 `webSocketDebuggerUrl`，则使用它，否则 OpenClaw 会回退到裸根路径上的直接 WebSocket 握手。如果通告的 WebSocket 端点拒绝 CDP 握手，但配置的裸根路径可以接受，OpenClaw 也会回退到该根路径。这使得指向本地 Chrome 的裸 `ws://` 仍然可以连接，因为 Chrome 只接受来自 `/json/version` 中特定每目标路径的 WebSocket 升级；而托管提供商在其发现端点通告了不适合 Playwright CDP 的短时效 URL 时，仍可以使用其根 WebSocket 端点。
### Browserbase
[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行带有内置 CAPTCHA 求解、隐身模式和住宅代理的 headless 浏览器。
[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行无头浏览器，内置 CAPTCHA 解决、隐身模式和住宅代理。
```json5
{
@ -382,52 +388,55 @@ OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时都会保留
说明：
- [注册](https://www.browserbase.com/sign-up)，并从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。
- 将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
- [注册](https://www.browserbase.com/sign-up) 后，从[概览仪表板](https://www.browserbase.com/overview)复制你的 **API Key**。
- 将 `<BROWSERBASE_API_KEY>` 替换为你的真实 Browserbase API key。
- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此不需要手动创建会话。
- 免费套餐每月允许一个并发会话和一个浏览器小时。有关付费套餐限制，请参阅 [pricing](https://www.browserbase.com/pricing)。
- 完整的 API 参考、SDK 指南和集成示例，请参阅 [Browserbase docs](https://docs.browserbase.com)。
- 免费层每月允许一个并发会话和一个浏览器小时。
付费计划限制请参见 [pricing](https://www.browserbase.com/pricing)。
- 完整的 API 参考、SDK 指南和集成示例，请参见 [Browserbase docs](https://docs.browserbase.com)。
## 安全
## 安全性
关键点：
关键理念：
- 浏览器控制仅限 loopback；访问通过 Gateway 网关认证或节点配对进行。
- 独立的 loopback 浏览器 HTTP API **仅**使用共享密钥认证：gateway token bearer auth、`x-openclaw-password`，或使用已配置 gateway 密码的 HTTP Basic auth。
- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"` **不会**对这个独立的 loopback 浏览器 API 进行认证。
- 如果启用了浏览器控制且未配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。
- 浏览器控制仅限 loopback；访问通过 Gateway 网关 的认证或节点配对进行。
- 独立的 loopback 浏览器 HTTP API **仅**使用共享密钥认证：
gateway token bearer auth、`x-openclaw-password`，或使用已配置 gateway 密码的 HTTP Basic auth。
- Tailscale Serve 身份头以及 `gateway.auth.mode: "trusted-proxy"`
**不能**为这个独立的 loopback 浏览器 API 提供认证。
- 如果启用了浏览器控制，但未配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。
- 当 `gateway.auth.mode` 已经是 `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。
- 请将 Gateway 网关和任何节点主机保持在私有网络中（Tailscale）；避免公开暴露。
- 将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。
- 请将 Gateway 网关 和任何节点主机保持在私有网络中（Tailscale）；避免公开暴露。
- 请将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。
远程 CDP 提示：
- 尽可能优先使用加密端点（HTTPS 或 WSS）和短时 token。
- 尽可能优先使用加密端点（HTTPS 或 WSS）以及短时效 token。
- 避免将长期有效的 token 直接嵌入配置文件。
## 配置文件（多浏览器）
OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是：
- **OpenClaw 管理**：一个专用的、基于 Chromium 的浏览器实例，具有自己的用户数据目录 + CDP 端口
- **远程**：显式 CDP URL（运行在其他地方的基于 Chromium 的浏览器）
- **现有会话**：通过 Chrome DevTools MCP 自动连接你的现有 Chrome 配置文件
- **由 OpenClaw 管理**：一个专用的 Chromium 系浏览器实例，拥有自己的用户数据目录 + CDP 端口
- **远程**：显式的 CDP URL（在其他地方运行的 Chromium 系浏览器）
- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件
默认值：
- 如果缺失，会自动创建 `openclaw` 配置文件。
- `user` 配置文件是内置的，用于通过 Chrome MCP 附加到 existing-session。
- 除 `user` 之外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建它们。
- 如果缺少，`openclaw` 配置文件会自动创建。
- `user` 配置文件是内置的，用于 Chrome MCP existing-session 附加。
- 除 `user` 外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建。
- 本地 CDP 端口默认从 **18800–18899** 分配。
- 删除配置文件时，其本地数据目录会被移到废纸篓。
- 删除配置文件时，会将其本地数据目录移到废纸篓。
所有控制端点都接受 `?profile=<name>`；CLI 使用 `--browser-profile`。
## 通过 Chrome DevTools MCP 附加现有会话
## 通过 Chrome DevTools MCP 使用现有会话
OpenClaw 还可以通过官方的 Chrome DevTools MCP 服务器附加到一个正在运行的基于 Chromium 的浏览器配置文件。这样可以复用该浏览器配置文件中已经打开的标签页和登录状态。
OpenClaw 还可以通过官方的 Chrome DevTools MCP 服务器附加到一个正在运行的 Chromium 系浏览器配置文件。这样可以复用该浏览器配置文件中已打开的标签页和登录状态。
官方背景与设置参考：
官方背景和设置参考：
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
@ -436,13 +445,13 @@ OpenClaw 还可以通过官方的 Chrome DevTools MCP 服务器附加到一个
- `user`
可选：如果你想使用不同的名称、颜色或浏览器数据目录，可以创建你自己的自定义 existing-session 配置文件。
可选：如果你想要不同的名称、颜色或浏览器数据目录，也可以创建你自己的自定义 existing-session 配置文件。
默认行为：
- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome 配置文件。
对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件，请使用 `userDataDir`。
对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`。
`~` 会展开为你的操作系统主目录：
```json5
@ -481,67 +490,68 @@ openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
```
成功时应看到的结果：
成功时应表现为：
- `status` 显示 `driver: existing-session`
- `status` 显示 `transport: chrome-mcp`
- `status` 显示 `running: true`
- `tabs` 列出你已经打开的浏览器标签页
- `snapshot` 返回来自所选实时标签页的 refs
- `snapshot` 返回所选实时标签页中的 refs
如果附加不起作用，请检查：
- 目标的基于 Chromium 的浏览器版本是 `144+`
- 目标 Chromium 系浏览器版本为 `144+`
- 已在该浏览器的 inspect 页面中启用远程调试
- 浏览器显示了附加同意提示，并且你已接受
- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器端的远程调试
- 浏览器已显示附加同意提示，并且你已接受
- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已本地安装，但它无法替你在浏览器端启用远程调试
智能体使用：
- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。
- 如果你使用自定义 existing-session 配置文件，请传入该明确的配置文件名称。
- 仅当用户在电脑前可以批准附加提示时，才选择此模式。
- Gateway 网关或节点主机可以生成 `npx chrome-devtools-mcp@latest --autoConnect`
- 当你需要用户已登录的浏览器状态时，请使用 `profile="user"`。
- 如果你使用的是自定义 existing-session 配置文件，请传递该显式配置文件名称。
- 仅当用户就在电脑前可以批准附加提示时，才选择此模式。
- Gateway 网关 或节点主机可以生成 `npx chrome-devtools-mcp@latest --autoConnect`
说明：
- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以在你已登录的浏览器会话中执行操作。
- 对于这个驱动，OpenClaw 不会启动浏览器；它只会进行附加。
- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，它会被传递下去，以定位该用户数据目录。
- Existing-session 可以附加到所选主机上，或通过已连接的浏览器节点进行附加。如果 Chrome 位于其他地方且没有连接浏览器节点，请改用远程 CDP 或节点主机。
- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以在你已登录的浏览器会话内执行操作。
- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。
- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，则会将其透传，以便定位到该用户数据目录。
- existing-session 可以附加到所选主机上，或通过已连接的浏览器节点进行附加。如果 Chrome 位于其他地方，且没有浏览器节点连接，请改用远程 CDP 或节点主机。
### 自定义 Chrome MCP 启动
当默认的 `npx chrome-devtools-mcp@latest` 流程不是你想要的方式时（离线主机、固定版本、随附二进制文件），可以按配置文件覆盖所生成的 Chrome DevTools MCP 服务器：
当默认的 `npx chrome-devtools-mcp@latest` 流程不符合你的需求时（离线主机、固定版本、内置二进制文件），可以按配置文件覆盖所生成的 Chrome DevTools MCP 服务器：
| 字段 | 作用 |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `mcpCommand` | 要生成的可执行文件，用来替代 `npx`。按原样解析；支持绝对路径。 |
| `mcpArgs` | 原样传递给 `mcpCommand` 的参数数组。会替换默认的 `chrome-devtools-mcp@latest --autoConnect` 参数。 |
| `mcpArgs` | 原样传递给 `mcpCommand` 的参数数组。会替换默认的 `chrome-devtools-mcp@latest --autoConnect` 参数。 |
当在 existing-session 配置文件上设置了 `cdpUrl` 时，OpenClaw 会跳过 `--autoConnect`，并自动将该端点转发给 Chrome MCP：
当在 existing-session 配置文件上设置了 `cdpUrl` 时，OpenClaw 会跳过
`--autoConnect`，并自动将该端点转发给 Chrome MCP：
- `http(s)://...` → `--browserUrl <url>`（DevTools HTTP 发现端点）。
- `ws(s)://...` → `--wsEndpoint <url>`（直接 CDP WebSocket）。
端点标志与 `userDataDir` 不能组合使用：设置了 `cdpUrl` 时，Chrome MCP 启动会忽略 `userDataDir`，因为 Chrome MCP 会附加到端点背后正在运行的浏览器，而不是打开一个配置文件目录。
端点标志与 `userDataDir` 不能组合使用：当设置了 `cdpUrl` 时，`userDataDir` 会在 Chrome MCP 启动中被忽略，因为 Chrome MCP 会附加到端点背后的正在运行浏览器，而不是打开某个配置文件目录。
<Accordion title="Existing-session 功能限制">
<Accordion title="existing-session 功能限制">
与受管的 `openclaw` 配置文件相比，existing-session 驱动受到更多限制：
与受管理的 `openclaw` 配置文件相比，existing-session 驱动的限制更多：
- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面或基于 ref 的元素截图不需要 Playwright。
- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要 snapshot ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用单独设置超时。`select` 接受单个值。
- **等待 / 上传 / 对话框** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子要求使用 `ref` 或 `inputRef`，一次一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。
- **仅受管功能** —— 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要使用受管浏览器路径。
- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合。页面截图或基于 ref 的元素截图不需要 Playwright。
- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click-coords` 会点击可见视口坐标，不需要 snapshot ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用设置超时。`select` 接受单个值。
- **等待 / 上传 / 对话框** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，一次一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。
- **仅限受管理模式的功能** —— 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管理浏览器路径。
</Accordion>
## 隔离保证
- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。
- **专用端口**：避免使用 `9222`，防止与开发工作流冲突。
- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄，例如 `t1`、可选标签，以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍然保留用于调试和兼容性。
- **专用端口**：避免使用 `9222`，以防与开发工作流冲突。
- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄（如 `t1`）、可选标签以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍可用于调试和兼容性场景。
## 浏览器选择
@ -553,7 +563,7 @@ openclaw browser --browser-profile user snapshot --format ai
4. Chromium
5. Chrome Canary
你可以使用 `browser.executablePath` 进行覆盖。
你可以通过 `browser.executablePath` 覆盖它。
平台：
@ -563,20 +573,23 @@ openclaw browser --browser-profile user snapshot --format ai
## 控制 API（可选）
对于脚本编写和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，以及对应的 `openclaw browser` CLI（快照、refs、wait 增强、JSON 输出、调试工作流）。完整参考请参阅[Browser control API](/zh-CN/tools/browser-control)。
为了便于脚本编写和调试，Gateway 网关 暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，并提供匹配的 `openclaw browser` CLI（快照、refs、wait 增强能力、JSON 输出、调试工作流）。完整参考请参见
[浏览器控制 API](/zh-CN/tools/browser-control)。
## 故障排除
有关 Linux 特有问题（尤其是 snap Chromium），请参阅[Browser 故障排除](/zh-CN/tools/browser-linux-troubleshooting)。
关于 Linux 特定问题（尤其是 snap Chromium），请参见
[浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。
有关 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参阅[WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。
关于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参见
[WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。
### CDP 启动失败与导航 SSRF 阻止
### CDP 启动失败 与 导航 SSRF 阻止
这是两类不同的失败，它们指向不同的代码路径。
这是两类不同的失败，它们分别指向不同的代码路径。
- **CDP 启动或就绪失败**表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
- **导航 SSRF 阻止**表示浏览器控制平面是健康的，但页面导航目标被策略拒绝。
- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标因策略而被拒绝。
常见示例：
@ -585,9 +598,9 @@ openclaw browser --browser-profile user snapshot --format ai
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
- `Port <port> is in use for profile "<name>" but not by openclaw`，当 loopback 外部 CDP 服务配置时未设置 `attachOnly: true`
- 导航 SSRF 阻止：
- 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败
- `open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败，但 `start` 和 `tabs` 仍然正常
使用以下最小命令序列来区分这两类问题：
使用以下最小序列来区分这两者：
```bash
openclaw browser --browser-profile openclaw start
@ -595,48 +608,48 @@ openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
```
结果解读方式：
如何解读结果：
- 如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪问题。
- 如果 `start` 成功但 `tabs` 失败，控制平面仍然不健康。请将其视为 CDP 可达性问题，而不是页面导航问题。
- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面已经正常，失败发生在导航策略或目标页面上。
- 如果 `start`、`tabs` 和 `open` 都成功，则说明基础的受管浏览器控制路径是健康的。
- 如果 `start` 成功但 `tabs` 失败，则控制平面仍不健康。请将其视为 CDP 可达性问题，而不是页面导航问题。
- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则浏览器控制平面已启动，故障出在导航策略或目标页面上。
- 如果 `start`、`tabs` 和 `open` 全部成功，则基础的受管理浏览器控制路径是健康的。
重要行为细节：
- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会采用失败即关闭的 SSRF 策略对象。
- 对于本地 loopback 的 `openclaw` 受管配置文件，CDP 健康检查会有意跳过浏览器 SSRF 可达性强制检查，以便 OpenClaw 自己的本地控制平面能够正常工作。
- 对于本地 loopback 的 `openclaw` 受管理配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制。
- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着后续的 `open` 或 `navigate` 目标一定被允许。
安全指引：
- **不要**默认放宽浏览器 SSRF 策略。
- 优先使用范围较窄的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛的私有网络访问。
- 仅在明确受信任、确实需要私有网络浏览器访问并且已经过审查的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
- 优先使用精确的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛地允许私有网络访问。
- 仅在明确受信任、确实需要并且经过审查的私有网络浏览器访问环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
## 智能体工具 + 控制工作原理
## 智能体工具 + 控制如何工作
智能体获得**一个工具**来进行浏览器自动化：
智能体会获得**一个工具**用于浏览器自动化：
- `browser` — doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
它的映射方式如下：
映射方式：
- `browser snapshot` 返回一个稳定的 UI 树（AI 或 ARIA）。
- `browser act` 使用 snapshot `ref` ID 来执行 click/type/drag/select。
- `browser screenshot` 捕获像素（整页、元素或带标签的 refs）。
- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪状态。
- `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。
- `browser act` 使用 snapshot 的 `ref` ID 来执行点击/输入/拖拽/选择。
- `browser screenshot` 捕获像素内容（整页、元素或带标签的 refs）。
- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪情况。
- `browser` 接受：
- `profile` 用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。
- `target`（`sandbox` | `host` | `node`）用于选择浏览器所在位置。
- `profile`，用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。
- `target`（`sandbox` | `host` | `node`），用于选择浏览器所在位置。
- 在沙箱隔离会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。
- 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱隔离会话默认使用 `host`。
- 如果连接了具备浏览器能力的节点，工具可能会自动路由到它，除非你固定指定 `target="host"` 或 `target="node"`。
- 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱会话默认使用 `host`。
- 如果已连接支持浏览器的节点，除非你固定指定 `target="host"` 或 `target="node"`，否则该工具可能会自动路由到该节点。
这样可以让智能体保持确定性，并避免脆弱的选择器。
这样可以让智能体行为保持可预测，并避免脆弱的选择器。
## 相关内容
- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具
- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制
- [安全](/zh-CN/gateway/security) — 浏览器控制的风险与加固
- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固