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-24 02:41:26 +00:00
parent 089dc0be42
commit ef90ad76a4
5 changed files with 1103 additions and 1020 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
docs/zh-CN/cli/acp.md
View File

@ -1,29 +1,33 @@
---
read_when:
- 设置基于 ACP 的 IDE 集成
- 调试到 Gateway 网关的 ACP 会话路由
summary: 运行用于 IDE 集成的 ACP bridge
- 调试 ACP 会话路由到 Gateway 网关
summary: 为 IDE 集成运行 ACP 桥接器
title: ACP
x-i18n:
generated_at: "2026-04-23T20:42:42Z"
generated_at: "2026-04-24T02:39:42Z"
model: gpt-5.4
provider: openai
source_hash: b535e84f8ba5f143340af5b6a1e651b0711ba8d5fa58bfb76863612718ed07bb
source_hash: 04a1413c23464489a192f5d99cd97f128c0ddc080f3ae637073147a2b07ce305
source_path: cli/acp.md
workflow: 15
---
运行与 OpenClaw Gateway 网关通信的 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge。
运行与 OpenClaw Gateway 网关通信的 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 桥接器。
此命令通过 stdio 为 IDE 提供 ACP，并通过 WebSocket 将提示转发到 Gateway 网关。它会将 ACP 会话持续映射到 Gateway 网关会话键。
此命令通过 `stdio` 为 IDE 提供 ACP，并通过 WebSocket 将提示转发到 Gateway 网关。
它会让 ACP 会话持续映射到 Gateway 网关会话键。
`openclaw acp` 是一个由 Gateway 网关支持的 ACP bridge，而不是完整的原生 ACP 编辑器运行时。它专注于会话路由、提示传递和基础流式更新。
`openclaw acp` 是一个由 Gateway 网关支持的 ACP 桥接器，不是完整的 ACP 原生编辑器
运行时。它专注于会话路由、提示传递和基础的流式更新。
如果你希望外部 MCP 客户端直接与 OpenClaw 渠道会话通信，而不是托管 ACP harness 会话，请改用 [`openclaw mcp serve`](/zh-CN/cli/mcp)。
如果你希望外部 MCP 客户端直接与 OpenClaw 渠道
会话通信，而不是托管 ACP harness 会话，请改用
[`openclaw mcp serve`](/zh-CN/cli/mcp)。
## 这不是什么
本页经常与 ACP harness 会话混淆。
此页面经常与 ACP harness 会话混淆。
`openclaw acp` 的含义是：
@ -31,47 +35,61 @@ x-i18n:
- IDE 或 ACP 客户端连接到 OpenClaw
- OpenClaw 将这些工作转发到 Gateway 网关会话中
这与 [ACP Agents](/zh-CN/tools/acp-agents) 不同，后者是 OpenClaw 通过 `acpx` 运行外部 harness，例如 Codex 或 Claude Code。
这不同于 [ACP Agents](/zh-CN/tools/acp-agents)，后者中 OpenClaw 会通过 `acpx` 运行
外部 harness，例如 Codex 或 Claude Code。
快速判断规则：
快速规则：
- 编辑器/客户端想通过 ACP 与 OpenClaw 通信：使用 `openclaw acp`
- OpenClaw 应启动 Codex/Claude/Gemini 作为 ACP harness：使用 `/acp spawn` 和 [ACP Agents](/zh-CN/tools/acp-agents)
## 兼容性矩阵
| ACP 区域 | 状态 | 说明 |
| --------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `initialize`、`newSession`、`prompt`、`cancel` | 已实现 | 通过 stdio 到 Gateway 网关 `chat/send` + 中止的核心 bridge 流程。 |
| `listSessions`、斜杠命令 | 已实现 | 会话列表可基于 Gateway 网关会话状态工作；命令通过 `available_commands_update` 对外公布。 |
| `loadSession` | 部分支持 | 将 ACP 会话重新绑定到 Gateway 网关会话键，并重放已存储的用户/助手文本历史。工具/系统历史目前尚未重建。 |
| 提示内容（`text`、嵌入式 `resource`、图像） | 部分支持 | 文本/资源会被展平成聊天输入；图像会变为 Gateway 网关附件。 |
| 会话模式 | 部分支持 | 支持 `session/set_mode`，且 bridge 会暴露初始的 Gateway 网关支持的会话控制，包括 thought level、tool verbosity、reasoning、usage detail 和 elevated actions。更广泛的 ACP 原生模式/配置界面仍不在范围内。 |
| 会话信息和使用量更新 | 部分支持 | bridge 会根据缓存的 Gateway 网关会话快照发出 `session_info_update` 和尽力而为的 `usage_update` 通知。使用量是近似值，且仅当 Gateway 网关将 token 总量标记为新鲜时才会发送。 |
| 工具流式传输 | 部分支持 | `tool_call` / `tool_call_update` 事件包含原始 I/O、文本内容，以及在 Gateway 网关工具参数/结果暴露这些内容时尽力而为提取的文件位置。嵌入式终端和更丰富的原生 Diffs 输出目前仍未暴露。 |
| 每会话 MCP 服务器（`mcpServers`） | 不支持 | bridge 模式会拒绝每会话 MCP 服务器请求。请改为在 OpenClaw gateway 或智能体上配置 MCP。 |
| 客户端文件系统方法（`fs/read_text_file`、`fs/write_text_file`） | 不支持 | bridge 不会调用 ACP 客户端文件系统方法。 |
| 客户端终端方法（`terminal/*`） | 不支持 | bridge 不会创建 ACP 客户端终端，也不会通过工具调用流式传输终端 ID。 |
| 会话计划 / thought 流式传输 | 不支持 | bridge 当前发出的是输出文本和工具状态，而不是 ACP 计划或 thought 更新。 |
| ACP 区域 | 状态 | 说明 |
| --------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialize`, `newSession`, `prompt`, `cancel` | 已实现 | 通过 `stdio` 到 Gateway 网关 chat/send + abort 的核心桥接流程。 |
| `listSessions`, 斜杠命令 | 已实现 | 会话列表基于 Gateway 网关会话状态工作；命令通过 `available_commands_update` 进行通告。 |
| `loadSession` | 部分支持 | 将 ACP 会话重新绑定到 Gateway 网关会话键，并重放存储的用户/助手文本历史。工具/系统历史尚未重建。 |
| 提示内容（`text`、嵌入式 `resource`、图片） | 部分支持 | 文本/资源会被展平为 chat 输入；图片会成为 Gateway 网关附件。 |
| 会话模式 | 部分支持 | 支持 `session/set_mode`，并且桥接器公开了初始的 Gateway 网关支持会话控制，用于 thought level、tool verbosity、reasoning、usage detail 和 elevated actions。更广泛的 ACP 原生模式/配置表面仍不在当前范围内。 |
| 会话信息和用量更新 | 部分支持 | 桥接器会根据缓存的 Gateway 网关会话快照发出 `session_info_update` 和尽力而为的 `usage_update` 通知。用量是近似值，且仅当 Gateway 网关将 token 总量标记为最新时才会发送。 |
| 工具流式传输 | 部分支持 | `tool_call` / `tool_call_update` 事件会包含原始 I/O、文本内容，以及当 Gateway 网关工具参数/结果暴露这些信息时尽力而为提供的文件位置。嵌入式终端和更丰富的原生 Diffs 输出仍未暴露。 |
| 每会话 MCP 服务器（`mcpServers`） | 不支持 | 桥接模式会拒绝每会话 MCP 服务器请求。请改为在 OpenClaw gateway 或智能体上配置 MCP。 |
| 客户端文件系统方法（`fs/read_text_file`, `fs/write_text_file`） | 不支持 | 该桥接器不会调用 ACP 客户端文件系统方法。 |
| 客户端终端方法（`terminal/*`） | 不支持 | 该桥接器不会创建 ACP 客户端终端，也不会通过工具调用流式传输终端 ID。 |
| 会话计划 / thought 流式传输 | 不支持 | 该桥接器当前会发出输出文本和工具状态，而不是 ACP 计划或 thought 更新。 |
## 已知限制
- `loadSession` 会重放已存储的用户和助手文本历史，但不会重建历史工具调用、系统通知或更丰富的 ACP 原生事件类型。
- 如果多个 ACP 客户端共享同一个 Gateway 网关会话键，事件和取消路由仅为尽力而为，而不是严格按客户端隔离。若你需要清晰的编辑器本地轮次，优先使用默认隔离的 `acp:<uuid>` 会话。
- Gateway 网关停止状态会被转换为 ACP 停止原因，但这种映射的表达能力弱于完整的 ACP 原生运行时。
- 初始会话控制目前只暴露一组聚焦的 Gateway 网关选项：thought level、tool verbosity、reasoning、usage detail 和 elevated actions。模型选择和 exec-host 控制尚未作为 ACP 配置选项暴露。
- `session_info_update` 和 `usage_update` 来源于 Gateway 网关会话快照，而不是实时 ACP 原生运行时统计。使用量是近似值，不包含成本数据，并且只有当 Gateway 网关将总 token 数据标记为新鲜时才会发出。
- 工具跟随数据是尽力而为的。bridge 可以展示已知工具参数/结果中出现的文件路径，但目前尚不会发出 ACP 终端或结构化文件 Diffs。
- `loadSession` 会重放存储的用户和助手文本历史，但不会
重建历史工具调用、系统通知或更丰富的 ACP 原生事件
类型。
- 如果多个 ACP 客户端共享同一个 Gateway 网关会话键，事件和取消
路由将是尽力而为，而不是严格按客户端完全隔离。若你需要
干净的编辑器本地轮次，优先使用默认隔离的 `acp:<uuid>` 会话。
- Gateway 网关停止状态会被转换为 ACP 停止原因，但这种映射
不如完整 ACP 原生运行时那样具有表现力。
- 初始会话控制当前只公开一组聚焦的 Gateway 网关旋钮：
thought level、tool verbosity、reasoning、usage detail 和 elevated
actions。模型选择和 exec-host 控制尚未作为 ACP
配置选项公开。
- `session_info_update` 和 `usage_update` 来源于 Gateway 网关会话
快照，而不是实时 ACP 原生运行时统计。用量是近似值，
不包含成本数据，并且仅在 Gateway 网关将总 token
数据标记为最新时发出。
- 工具跟随数据是尽力而为的。桥接器可以公开已知工具参数/结果中
出现的文件路径，但它尚不会发出 ACP 终端或
结构化文件 Diffs。
## 用法
```bash
openclaw acp
# 远程 Gateway 网关
# 远程 Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>
# 远程 Gateway 网关（从文件读取 token）
# 远程 Gateway（从文件读取 token）
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# 附加到现有会话键
@ -80,19 +98,19 @@ openclaw acp --session agent:main:main
# 按标签附加（必须已存在）
openclaw acp --session-label "support inbox"
# 在第一条提示前重置会话键
# 在第一个提示之前重置会话键
openclaw acp --session agent:main:main --reset-session
```
## ACP 客户端（调试）
使用内置 ACP 客户端可在无需 IDE 的情况下对 bridge 做完整性检查。
它会启动 ACP bridge，并允许你以交互方式输入提示。
使用内置 ACP 客户端在没有 IDE 的情况下对桥接器进行安装完整性检查。
它会启动 ACP 桥接器，并允许你以交互方式输入提示。
```bash
openclaw acp client
# 让启动的 bridge 指向远程 Gateway 网关
# 让启动的桥接器指向远程 Gateway 网关
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# 覆盖服务器命令（默认：openclaw）
@ -101,19 +119,20 @@ openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://12
权限模型（客户端调试模式）：
- 自动批准基于允许列表，并且只适用于受信任的核心工具 ID。
- `read` 自动批准范围限制在当前工作目录（设置了 `--cwd` 时）。
- ACP 只会自动批准狭窄的只读类别：活动 cwd 下受限范围内的 `read` 调用，以及只读搜索工具（`search`、`web_search`、`memory_search`）。未知/非核心工具、超出范围的读取、具备执行能力的工具、控制平面工具、会修改状态的工具和交互式流程始终需要显式提示批准。
- 自动批准基于 allowlist，并且只适用于受信任的核心工具 ID。
- `read` 自动批准仅限当前工作目录（设置了 `--cwd` 时）。
- ACP 仅会自动批准范围很窄的只读类别：活动 cwd 下受限的 `read` 调用，以及只读搜索工具（`search`、`web_search`、`memory_search`）。未知/非核心工具、超范围读取、可执行工具、控制平面工具、变更型工具和交互式流程始终需要显式提示批准。
- 服务器提供的 `toolCall.kind` 被视为不受信任的元数据（不是授权来源）。
- 此 ACP bridge 策略与 ACPX harness 权限无关。如果你通过 `acpx` 后端运行 OpenClaw，`plugins.entries.acpx.config.permissionMode=approve-all` 是该 harness 会话的紧急放行 “yolo” 开关。
- 此 ACP 桥接器策略独立于 ACPX harness 权限。如果你通过 `acpx` 后端运行 OpenClaw，`plugins.entries.acpx.config.permissionMode=approve-all` 是该 harness 会话的紧急放开式 “yolo” 开关。
## 如何使用
当 IDE（或其他客户端）支持 Agent Client Protocol，并且你希望它驱动 OpenClaw Gateway 网关会话时，请使用 ACP。
当 IDE（或其他客户端）支持 Agent Client Protocol，并且你希望
它驱动一个 OpenClaw Gateway 网关会话时，请使用 ACP。
1. 确保 Gateway 网关正在运行（本地或远程）。
2. 配置 Gateway 网关目标（通过配置或命令行标志）。
3. 将你的 IDE 指向通过 stdio 运行 `openclaw acp`。
2. 配置 Gateway 网关目标（配置或标志）。
3. 让你的 IDE 通过 `stdio` 运行 `openclaw acp`。
示例配置（持久化）：
@ -126,15 +145,15 @@ openclaw config set gateway.remote.token <token>
```bash
openclaw acp --url wss://gateway-host:18789 --token <token>
# 本地进程安全的推荐方式
# 本地进程安全时优先推荐
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
```
## 选择智能体
ACP 不会直接选择智能体。它通过 Gateway 网关会话键进行路由。
ACP 不会直接选择智能体。它按 Gateway 网关会话键进行路由。
使用带智能体作用域的会话键来定位特定智能体：
使用带有智能体作用域的会话键来定位特定智能体：
```bash
openclaw acp --session agent:main:main
@ -142,35 +161,44 @@ openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
```
每个 ACP 会话都映射到单个 Gateway 网关会话键。一个智能体可以拥有多个会话；ACP 默认使用隔离的 `acp:<uuid>` 会话，除非你覆盖该键或标签。
每个 ACP 会话都映射到单个 Gateway 网关会话键。一个智能体可以拥有多个
会话；除非你覆盖该键或标签，否则 ACP 默认使用隔离的 `acp:<uuid>` 会话。
bridge 模式不支持每会话 `mcpServers`。如果 ACP 客户端在 `newSession` 或 `loadSession` 期间发送它们，bridge 会返回清晰的错误，而不是悄悄忽略。
桥接模式不支持每会话 `mcpServers`。如果 ACP 客户端
在 `newSession` 或 `loadSession` 期间发送它们，桥接器会返回清晰的
错误，而不是静默忽略。
如果你希望由 ACPX 支持的会话能够看到 OpenClaw 渠道插件工具或选定的内置工具（例如 `cron`），请启用 Gateway 网关侧的 ACPX MCP bridges，而不是尝试传递每会话 `mcpServers`。请参阅 [ACP Agents](/zh-CN/tools/acp-agents#plugin-tools-mcp-bridge) 和 [OpenClaw 工具 MCP bridge](/zh-CN/tools/acp-agents#openclaw-tools-mcp-bridge)。
如果你希望由 ACPX 支持的会话看到 OpenClaw 插件工具或选定的
内置工具，例如 `cron`，请启用 Gateway 网关侧的 ACPX MCP 桥接，
而不是尝试传递每会话 `mcpServers`。请参见
[ACP Agents](/zh-CN/tools/acp-agents-setup#plugin-tools-mcp-bridge) 和
[OpenClaw tools MCP bridge](/zh-CN/tools/acp-agents-setup#openclaw-tools-mcp-bridge)。
## 从 `acpx` 使用（Codex、Claude、其他 ACP 客户端）
如果你希望 Codex 或 Claude Code 这样的编码智能体通过 ACP 与你的 OpenClaw 机器人通信，请使用 `acpx` 及其内置的 `openclaw` 目标。
如果你希望 Codex 或 Claude Code 这类编码智能体
通过 ACP 与你的 OpenClaw bot 通信，请使用带有其内置 `openclaw` 目标的 `acpx`。
典型流程：
1. 运行 Gateway 网关，并确保 ACP bridge 可以连接到它。
2. 将 `acpx openclaw` 指向 `openclaw acp`。
3. 指定你希望该编码智能体使用的 OpenClaw 会话键。
1. 运行 Gateway 网关，并确保 ACP 桥接器可以访问它。
2. 让 `acpx openclaw` 指向 `openclaw acp`。
3. 定位你希望编码智能体使用的 OpenClaw 会话键。
示例：
```bash
# 向默认 OpenClaw ACP 会话发起一次性请求
# 向你的默认 OpenClaw ACP 会话发送一次性请求
acpx openclaw exec "Summarize the active OpenClaw session state."
# 用于后续轮次的持久化命名会话
# 用于后续轮次的持久命名会话
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
"Ask my OpenClaw work agent for recent context relevant to this repo."
```
如果你希望 `acpx openclaw` 每次都指向特定的 Gateway 网关和会话键，可在 `~/.acpx/config.json` 中覆盖 `openclaw` 智能体命令：
如果你希望 `acpx openclaw` 每次都定位特定的 Gateway 网关和会话键，
请在 `~/.acpx/config.json` 中覆盖 `openclaw` 智能体命令：
```json
{
@ -182,17 +210,19 @@ acpx openclaw -s codex-bridge --cwd /path/to/repo \
}
```
对于仓库本地的 OpenClaw 检出，请使用直接 CLI 入口点，而不是开发运行器，以保持 ACP 流干净。例如：
对于仓库本地的 OpenClaw 检出，请使用直接 CLI 入口点，而不是
dev runner，这样 ACP 流才能保持干净。例如：
```bash
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
```
这是让 Codex、Claude Code 或其他支持 ACP 的客户端从 OpenClaw 智能体中提取上下文信息、而无需抓取终端内容的最简单方式。
这是让 Codex、Claude Code 或其他支持 ACP 的客户端
从 OpenClaw 智能体提取上下文信息、而无需抓取终端内容的最简单方式。
## Zed 编辑器设置
在 `~/.config/zed/settings.json` 中添加自定义 ACP 智能体（或使用 Zed 的设置 UI）：
在 `~/.config/zed/settings.json` 中添加一个自定义 ACP 智能体（或使用 Zed 的设置 UI）：
```json
{
@ -207,7 +237,7 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
}
```
若要指定特定的 Gateway 网关或智能体：
若要定位特定 Gateway 网关或智能体：
```json
{
@ -230,18 +260,18 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
}
```
在 Zed 中，打开智能体面板并选择“OpenClaw ACP”以开始一个线程。
在 Zed 中，打开 Agent 面板并选择“OpenClaw ACP”以启动一个线程。
## 会话映射
默认情况下，ACP 会话会获得一个带有 `acp:` 前缀的隔离 Gateway 网关会话键。
若要复用已知会话，请传入会话键或标签：
- `--session <key>`：使用特定的 Gateway 网关会话键。
- `--session <key>`：使用特定 Gateway 网关会话键。
- `--session-label <label>`：按标签解析现有会话。
- `--reset-session`：为该键生成一个全新的会话 ID（相同键，不同新 transcript）。
- `--reset-session`：为该键生成一个新的会话 id（同一键，新 transcript）。
如果你的 ACP 客户端支持元数据，你可以按会话覆盖：
如果你的 ACP 客户端支持元数据，则可以按会话覆盖：
```json
{
@ -253,11 +283,11 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
}
```
有关会话键的更多信息，请参阅 [/concepts/session](/zh-CN/concepts/session)。
在 [/concepts/session](/zh-CN/concepts/session) 了解有关会话键的更多信息。
## 选项
- `--url <url>`：Gateway WebSocket URL（如果已配置，默认使用 `gateway.remote.url`）。
- `--url <url>`：Gateway WebSocket URL（若已配置，默认为 `gateway.remote.url`）。
- `--token <token>`：Gateway 网关认证 token。
- `--token-file <path>`：从文件读取 Gateway 网关认证 token。
- `--password <password>`：Gateway 网关认证密码。
@ -267,19 +297,19 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
- `--require-existing`：如果会话键/标签不存在则失败。
- `--reset-session`：在首次使用前重置会话键。
- `--no-prefix-cwd`：不要在提示前添加工作目录前缀。
- `--provenance <off|meta|meta+receipt>`：包含 ACP provenance 元数据或回执。
- `--verbose, -v`：向 stderr 输出详细日志。
- `--provenance <off|meta|meta+receipt>`：包含 ACP 来源元数据或回执。
- `--verbose, -v`：向 `stderr` 输出详细日志。
安全说明：
- 在某些系统上，`--token` 和 `--password` 可能会出现在本地进程列表中。
- 建议使用 `--token-file`/`--password-file` 或环境变量（`OPENCLAW_GATEWAY_TOKEN`、`OPENCLAW_GATEWAY_PASSWORD`）。
- Gateway 网关认证解析遵循与其他 Gateway 网关客户端共用的契约：
- 本地模式：环境变量（`OPENCLAW_GATEWAY_*`）-> `gateway.auth.*` -> 仅当 `gateway.auth.*` 未设置时才回退到 `gateway.remote.*`（已配置但未解析的本地 SecretRef 会以失败关闭方式处理）
- 远程模式：`gateway.remote.*`，并按远程优先级规则回退到环境变量/配置
- `--url` 是安全的覆盖项，不会复用隐式配置/环境凭证；请传入显式的 `--token`/`--password`（或其文件变体）
- ACP 运行时后端子进程会收到 `OPENCLAW_SHELL=acp`，可用于特定上下文的 shell/profile 规则。
- `openclaw acp client` 会在启动的 bridge 进程上设置 `OPENCLAW_SHELL=acp-client`。
- 优先使用 `--token-file`/`--password-file` 或环境变量（`OPENCLAW_GATEWAY_TOKEN`、`OPENCLAW_GATEWAY_PASSWORD`）。
- Gateway 网关认证解析遵循其他 Gateway 网关客户端使用的共享契约：
- 本地模式：环境变量（`OPENCLAW_GATEWAY_*`）-> `gateway.auth.*` -> 仅当 `gateway.auth.*` 未设置时才回退到 `gateway.remote.*`（已配置但未解析的本地 SecretRefs 将以失败关闭）
- 远程模式：`gateway.remote.*`，并按远程优先级规则进行环境变量/配置回退
- `--url` 可安全覆盖，不会复用隐式配置/环境变量凭证；请传入显式 `--token`/`--password`（或其文件变体）
- ACP 运行时后端子进程会接收 `OPENCLAW_SHELL=acp`，可用于上下文特定的 shell/profile 规则。
- `openclaw acp client` 会在其启动的桥接器进程上设置 `OPENCLAW_SHELL=acp-client`。
### `acp client` 选项
@ -287,4 +317,4 @@ env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
- `--server <command>`：ACP 服务器命令（默认：`openclaw`）。
- `--server-args <args...>`：传递给 ACP 服务器的额外参数。
- `--server-verbose`：在 ACP 服务器上启用详细日志。
- `--verbose, -v`：启用客户端详细日志。
- `--verbose, -v`：详细客户端日志。

281
docs/zh-CN/tools/acp-agents-setup.md Normal file
View File

@ -0,0 +1,281 @@
---
read_when:
- 为 Claude Code / Codex / Gemini CLI 安装或配置 `acpx` harness
- 启用 `plugin-tools` 或 OpenClaw-tools MCP 桥接器
- 配置 ACP 权限模式
summary: 设置 ACP 智能体：`acpx` harness 配置、插件设置、权限
title: ACP 智能体——设置
x-i18n:
generated_at: "2026-04-24T02:39:43Z"
model: gpt-5.4
provider: openai
source_hash: 7f1b34217b0709c85173ca13d952e996676b73b7ac7b9db91a5069e19ff76013
source_path: tools/acp-agents-setup.md
workflow: 15
---
关于概览、运维手册和核心概念，请参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
本页介绍 `acpx` harness 配置、MCP 桥接器的插件设置，以及权限配置。
## `acpx` harness 支持（当前）
当前 `acpx` 内置 harness 别名：
- `claude`
- `codex`
- `copilot`
- `cursor`（Cursor CLI：`cursor-agent acp`）
- `droid`
- `gemini`
- `iflow`
- `kilocode`
- `kimi`
- `kiro`
- `openclaw`
- `opencode`
- `pi`
- `qwen`
当 OpenClaw 使用 `acpx` 后端时，除非你的 `acpx` 配置定义了自定义智能体别名，否则建议为 `agentId` 优先使用这些值。
如果你本地安装的 Cursor 仍然将 ACP 暴露为 `agent acp`，请在你的 `acpx` 配置中覆盖 `cursor` 智能体命令，而不是修改内置默认值。
直接使用 `acpx` CLI 时，也可以通过 `--agent <command>` 指向任意适配器，但这个原始逃生口是 `acpx` CLI 的功能（不是 OpenClaw 常规的 `agentId` 路径）。
## 必需配置
核心 ACP 基线配置：
```json5
{
acp: {
enabled: true,
// 可选。默认值为 true；设为 false 可暂停 ACP 分发，同时保留 /acp 控制。
dispatch: { enabled: true },
backend: "acpx",
defaultAgent: "codex",
allowedAgents: [
"claude",
"codex",
"copilot",
"cursor",
"droid",
"gemini",
"iflow",
"kilocode",
"kimi",
"kiro",
"openclaw",
"opencode",
"pi",
"qwen",
],
maxConcurrentSessions: 8,
stream: {
coalesceIdleMs: 300,
maxChunkChars: 1200,
},
runtime: {
ttlMinutes: 120,
},
},
}
```
线程绑定配置与渠道适配器相关。以下是 Discord 的示例：
```json5
{
session: {
threadBindings: {
enabled: true,
idleHours: 24,
maxAgeHours: 0,
},
},
channels: {
discord: {
threadBindings: {
enabled: true,
spawnAcpSessions: true,
},
},
},
}
```
如果基于线程绑定的 ACP 派生不起作用，请先检查适配器功能开关：
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
当前会话绑定不需要创建子线程。它们需要一个活跃的会话上下文，以及一个暴露 ACP 会话绑定能力的渠道适配器。
参见 [Configuration Reference](/zh-CN/gateway/configuration-reference)。
## `acpx` 后端的插件设置
全新安装默认会启用内置的 `acpx` 运行时插件，因此 ACP 通常无需手动安装插件即可工作。
先运行：
```text
/acp doctor
```
如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想切换到本地开发检出版本，请使用显式插件路径：
```bash
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
```
开发期间安装本地工作区版本：
```bash
openclaw plugins install ./path/to/local/acpx-plugin
```
然后验证后端健康状态：
```text
/acp doctor
```
### `acpx` 命令与版本配置
默认情况下，内置的 `acpx` 插件使用其插件本地固定版本的二进制文件（插件包内的 `node_modules/.bin/acpx`）。启动时会先将后端注册为未就绪状态，并由后台任务验证 `acpx --version`；如果缺少该二进制文件或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@<pinned>`，然后再次验证。整个过程中，Gateway 网关始终保持非阻塞。
你可以在插件配置中覆盖命令或版本：
```json
{
"plugins": {
"entries": {
"acpx": {
"enabled": true,
"config": {
"command": "../acpx/dist/cli.js",
"expectedVersion": "any"
}
}
}
}
}
```
- `command` 接受绝对路径、相对路径（相对于 OpenClaw 工作区解析）或命令名。
- `expectedVersion: "any"` 会禁用严格版本匹配。
- 自定义 `command` 路径会禁用插件本地自动安装。
参见 [Plugins](/zh-CN/tools/plugin)。
### 自动安装依赖
当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，`acpx`
运行时依赖（平台相关二进制文件）会通过 `postinstall` 钩子自动安装。如果自动安装失败，Gateway 网关仍会正常启动，并通过 `openclaw acp doctor` 报告缺失的依赖。
### Plugin tools MCP 桥接器
默认情况下，ACPX 会话**不会**将 OpenClaw 插件注册的工具暴露给
ACP harness。
如果你希望 Codex 或 Claude Code 等 ACP 智能体调用已安装的
OpenClaw 插件工具，例如 memory recall/store，请启用专用桥接器：
```bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
```
这会带来以下效果：
- 在 ACPX 会话引导过程中注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。
- 暴露已安装并启用的 OpenClaw 插件已注册的插件工具。
- 使该功能保持显式启用，且默认关闭。
安全与信任说明：
- 这会扩大 ACP harness 的工具暴露面。
- ACP 智能体只能访问 Gateway 网关中已经激活的插件工具。
- 请将其视为与允许这些插件在 OpenClaw 自身中执行相同的信任边界。
- 启用前请检查已安装的插件。
自定义 `mcpServers` 仍然和以前一样可用。内置的 `plugin-tools` 桥接器只是额外的可选便利功能，不是通用 MCP 服务器配置的替代方案。
### OpenClaw tools MCP 桥接器
默认情况下，ACPX 会话也**不会**通过 MCP 暴露 OpenClaw 内置工具。当 ACP 智能体需要使用 `cron` 等选定的内置工具时，请启用单独的核心工具桥接器：
```bash
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
```
这会带来以下效果：
- 在 ACPX 会话引导过程中注入一个名为 `openclaw-tools` 的内置 MCP 服务器。
- 暴露选定的 OpenClaw 内置工具。初始服务器会暴露 `cron`。
- 使核心工具暴露保持显式启用，且默认关闭。
### 运行时超时配置
内置的 `acpx` 插件默认将嵌入式运行时轮次的超时时间设置为 120 秒。这让 Gemini CLI 等较慢的 harness 有足够时间完成 ACP 启动和初始化。如果你的主机需要不同的运行时限制，可以覆盖此值：
```bash
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
```
修改此值后，请重启 Gateway 网关。
### 健康探测智能体配置
内置的 `acpx` 插件在判断嵌入式运行时后端是否就绪时，会探测一个 harness 智能体。默认值为 `codex`。如果你的部署使用其他默认 ACP 智能体，请将探测智能体设置为相同的 id：
```bash
openclaw config set plugins.entries.acpx.config.probeAgent claude
```
修改此值后，请重启 Gateway 网关。
## 权限配置
ACP 会话以非交互方式运行——没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。`acpx` 插件提供了两个配置键，用于控制权限处理方式：
这些 ACPX harness 权限与 OpenClaw 的执行审批是分开的，也与 CLI 后端供应商的绕过标志分开，例如 Claude CLI 的 `--permission-mode bypassPermissions`。对于 ACP 会话，ACPX 的 `approve-all` 是 harness 层级的紧急放开开关。
### `permissionMode`
控制 harness 智能体无需提示即可执行哪些操作。
| 值 | 行为 |
| --------------- | ------------------------------------------- |
| `approve-all` | 自动批准所有文件写入和 shell 命令。 |
| `approve-reads` | 仅自动批准读取；写入和执行仍需要提示。 |
| `deny-all` | 拒绝所有权限提示。 |
### `nonInteractivePermissions`
控制当本应显示权限提示但没有可交互 TTY 时会发生什么（ACP 会话始终都是这种情况）。
| 值 | 行为 |
| ------ | ----------------------------------------------------------------- |
| `fail` | 使用 `AcpRuntimeError` 中止会话。**（默认）** |
| `deny` | 静默拒绝该权限并继续执行（优雅降级）。 |
### 配置方式
通过插件配置设置：
```bash
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
```
修改这些值后，请重启 Gateway 网关。
> **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或执行操作都可能因 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 而失败。
>
> 如果你需要限制权限，请将 `nonInteractivePermissions` 设为 `deny`，这样会话会优雅降级，而不是直接崩溃。
## 相关内容
- [ACP 智能体](/zh-CN/tools/acp-agents) —— 概览、运维手册、核心概念
- [Sub-agents](/zh-CN/tools/subagents)
- [Multi-agent routing](/zh-CN/concepts/multi-agent)

583
docs/zh-CN/tools/acp-agents.md
View File

@ -1,138 +1,140 @@
---
read_when:
- 通过 ACP 运行编码 harness
- 在消息渠道上设置绑定到对话的 ACP 会话
- 将消息渠道中的一个对话绑定到持久化 ACP 会话
- 在消息渠道上设置与对话绑定的 ACP 会话
- 将消息渠道中的对话绑定到持久化 ACP 会话
- 排查 ACP 后端和插件接线问题
- 调试 ACP 完成结果投递或智能体到智能体循环
- 从聊天中使用 /acp 命令进行操作
summary: 为 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 和其他 harness 智能体使用 ACP 运行时会话
- 调试 ACP 完成结果传递或智能体到智能体循环问题
- 从聊天中操作 `/acp` 命令
summary: 对 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 和其他 harness 智能体使用 ACP 运行时会话
title: ACP 智能体
x-i18n:
generated_at: "2026-04-23T23:04:20Z"
generated_at: "2026-04-24T02:39:43Z"
model: gpt-5.4
provider: openai
source_hash: cfbce828d3c74b340cedf86c2e771401a618524b4fc1a716a84d85c5d2cd106d
source_hash: d09d4142ad56d9782ed5d7e40f7eab4c89f22131d35f749fcb07700c4d354e30
source_path: tools/acp-agents.md
workflow: 15
---
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话允许 OpenClaw 通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
如果你用自然语言要求 OpenClaw “在 Codex 中运行这个”或“在线程中启动 Claude Code”，OpenClaw 应将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每个 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
如果你用自然语言让 OpenClaw “在 Codex 里运行这个”或“在线程里启动 Claude Code”，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。
如果你想让 Codex 或 Claude Code 作为外部 MCP 客户端直接连接
到现有的 OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp)
而不是 ACP。
## 我需要哪个页面？
## 我需要看哪个页面？
这里有三个相邻但很容易混淆的功能面：
这里有三个相近且容易混淆的功能面：
| 你想要…… | 使用这个 | 说明 |
| ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| 通过 OpenClaw 运行 Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 绑定聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
| 将一个 OpenClaw Gateway 网关会话暴露为一个 ACP 服务器，供编辑器或客户端使用 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 以 ACP 方式与 OpenClaw 通信 |
| 将本地 AI CLI 复用为纯文本回退模型 | [CLI Backends](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 |
| 通过 OpenClaw 运行 Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 与聊天绑定的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
| 将 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端 通过 stdio/WebSocket 使用 ACP 与 OpenClaw 通信 |
| 将本地 AI CLI 复用为仅文本的回退模型 | [CLI Backends](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 |
## 开箱即用吗？
通常可以。全新安装默认启用了内置的 `acpx` 运行时插件，并带有插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复。运行 `/acp doctor` 可进行就绪性检查。
通常可以。全新安装会默认启用内置的 `acpx` 运行时插件，并附带一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复它。运行 `/acp doctor` 可进行就绪性检查。
首次运行的常见问题：
首次运行的常见注意事项：
- 目标 harness 适配器（Codex、Claude 等）可能会在你首次使用时通过 `npx` 按需拉取。
- 该 harness 的供应商凭证仍然必须已存在于主机上。
- 如果主机没有 npm 或网络访问能力，首次适配器拉取将失败，直到缓存被预热或适配器通过其他方式安装。
- 目标 harness 适配器（Codex、Claude 等）可能会在你第一次使用时通过 `npx` 按需拉取。
- 该 harness 对应的供应商认证仍然必须已存在于宿主机上。
- 如果宿主机没有 npm 或网络访问能力，首次运行时的适配器拉取会失败，直到缓存被预热或以其他方式安装该适配器。
## 操作手册
在聊天中快速使用 `/acp` 的流程：
1. **启动** —— `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto`
2. 在已绑定的对话或线程中**工作**（或者显式指定该会话键）。
3. **检查状态** —— `/acp status`
4. **调优** —— `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
5. 在不替换上下文的情况下进行**引导** —— `/acp steer tighten logging and continue`
6. **停止** —— `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定）
1. **启动** — `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto`
2. 在绑定的对话或线程中**处理工作**（或者显式指定会话键）。
3. **检查状态** — `/acp status`
4. **调优** — `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
5. **引导**而不替换上下文 — `/acp steer tighten logging and continue`
6. **停止** — `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定）
应当路由到 ACP 运行时的自然语言触发示例：
- “把这个 Discord 频道绑定到 Codex。”
- “在这里的一个线程中启动一个持久的 Codex 会话。”
- “把这个作为一次性 Claude Code ACP 会话运行，并总结结果。”
- “这个任务使用 Gemini CLI 在线程中运行，然后后续继续在同一个线程中处理。”
- “在这里的线程里启动一个持久的 Codex 会话。”
- “把这个作为一次性的 Claude Code ACP 会话来运行，并总结结果。”
- “这个任务使用 Gemini CLI 在线程中处理，然后后续继续在同一个线程里进行。”
OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑定到当前对话或线程，并将后续消息路由到该会话，直到关闭或过期。
OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持的情况下绑定到当前对话或线程，并将后续消息路由到该会话，直到关闭或过期。
## ACP 与子智能体
## ACP 与子智能体的区别
当你想使用外部 harness 运行时时，请使用 ACP。当你想使用 OpenClaw 原生委派运行时，请使用子智能体。
如果你想使用外部 harness 运行时，请使用 ACP。如果你想使用 OpenClaw 原生委派运行，请使用子智能体。
| 领域 | ACP 会话 | 子智能体运行 |
| 区域 | ACP 会话 | 子智能体运行 |
| ------------- | ------------------------------------- | ---------------------------------- |
| 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 |
| 会话键 | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| 主命令 | `/acp ...` | `/subagents ...` |
| 启动工具 | 带 `runtime:"acp"` 的 `sessions_spawn` | `sessions_spawn`（默认运行时） |
| 主要命令 | `/acp ...` | `/subagents ...` |
| 启动工具 | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn`（默认运行时） |
另请参见 [Sub-agents](/zh-CN/tools/subagents)。
另见 [Sub-agents](/zh-CN/tools/subagents)。
## ACP 如何运行 Claude Code
对于通过 ACP 运行的 Claude Code，其栈结构是：
对于通过 ACP 运行的 Claude Code，其栈如下：
1. OpenClaw ACP 会话控制平面
2. 内置 `acpx` 运行时插件
2. 内置的 `acpx` 运行时插件
3. Claude ACP 适配器
4. Claude 侧运行时/会话机制
4. Claude 侧的运行时/会话机制
重要区别：
一个重要区别：
- ACP Claude 是一种 harness 会话，具备 ACP 控制、会话恢复、后台任务跟踪，以及可选的对话/线程绑定。
- CLI backends 是独立的纯文本本地回退运行时。参见 [CLI Backends](/zh-CN/gateway/cli-backends)。
- ACP Claude 是一种 harness 会话，具有 ACP 控制、会话恢复、后台任务跟踪，以及可选的对话/线程绑定能力。
- CLI 后端则是独立的、仅文本的本地回退运行时。参见 [CLI Backends](/zh-CN/gateway/cli-backends)。
对于操作员来说，实用规则是：
对操作人员来说，实用规则是：
- 想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作：使用 ACP
- 想要通过原始 CLI 进行简单的本地文本回退：使用 CLI backends
- 想要 `/acp spawn`、可绑定的会话、运行时控制或持久化 harness 工作：使用 ACP
- 想要通过原始 CLI 获得简单的本地文本回退：使用 CLI 后端
## 绑定会话
## 绑定的会话
### 绑定到当前对话
`/acp spawn <harness> --bind here` 会将当前对话固定到新启动的 ACP 会话——不会创建子线程，仍使用同一聊天界面。OpenClaw 继续负责传输、凭证、安全和投递；该对话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原地重置该会话；`/acp close` 会移除该绑定。
`/acp spawn <harness> --bind here` 会将当前对话固定绑定到新启动的 ACP 会话 —— 不创建子线程，仍在同一个聊天界面中。OpenClaw 继续负责传输、认证、安全和消息投递；该对话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原位重置该会话；`/acp close` 会移除该绑定。
心智模型：
理解模型：
- **聊天界面** —— 人们持续交流的地方（Discord 频道、Telegram 主题、iMessage 聊天）。
- **ACP 会话** —— OpenClaw 路由到的持久化 Codex/Claude/Gemini 运行时状态。
- **子线程/主题** —— 仅在使用 `--thread ...` 时才会创建的可选额外消息界面。
- **运行时工作区** —— harness 实际运行的文件系统位置（`cwd`、代码仓库检出目录、后端工作区）。它独立于聊天界面。
- **聊天界面** — 人们持续对话的地方（Discord 频道、Telegram 话题、iMessage 聊天）。
- **ACP 会话** — OpenClaw 路由到的持久化 Codex/Claude/Gemini 运行时状态。
- **子线程/话题** — 一个可选的额外消息界面，仅在使用 `--thread ...` 时创建。
- **运行时工作区** — harness 运行所在的文件系统位置（`cwd`、仓库检出目录、后端工作区）。它独立于聊天界面。
示例：
- `/acp spawn codex --bind here` —— 保持当前聊天，启动或附加 Codex，并将未来消息路由到这里。
- `/acp spawn codex --thread auto` —— OpenClaw 可能会创建一个子线程/主题并绑定到那里。
- `/acp spawn codex --bind here --cwd /workspace/repo` —— 仍绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。
- `/acp spawn codex --bind here` — 保持当前聊天，启动或附加 Codex，并将未来消息路由到这里。
- `/acp spawn codex --thread auto` — OpenClaw 可能会创建一个子线程/话题并绑定到那里。
- `/acp spawn codex --bind here --cwd /workspace/repo` — 仍绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。
说明：
- `--bind here` 和 `--thread ...` 互斥。
- `--bind here` 与 `--thread ...` 互斥。
- `--bind here` 仅适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回清晰的不支持提示。绑定会在 Gateway 网关重启后继续保留。
- 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions` —— 对于 `--bind here` 则不需要。
- 如果你在没有 `--cwd` 的情况下启动到另一个 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误暴露。
- 如果你启动到另一个 ACP 智能体且未指定 `--cwd`，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接暴露。
### 绑定到线程的会话
当某个渠道适配器启用了线程绑定时，ACP 会话可以绑定到线程：
- OpenClaw 将一个线程绑定到目标 ACP 会话。
- 该线程中的后续消息会路由到已绑定的 ACP 会话。
- ACP 输出会投递回同一个线程。
- 失焦/关闭/归档/空闲超时或最大存活时间到期后，会移除该绑定。
- OpenClaw 将线程绑定到目标 ACP 会话。
- 该线程中的后续消息会路由到绑定的 ACP 会话。
- ACP 输出会回传到同一个线程。
- 失焦/关闭/归档/空闲超时或最大存活时间到期都会移除该绑定。
线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回清晰的不支持/不可用提示。
线程绑定 ACP 所需功能标志：
线程绑定 ACP 所需的功能标志：
- `acp.enabled=true`
- `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发）
@ -145,25 +147,25 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑
- 任何暴露会话/线程绑定能力的渠道适配器。
- 当前内置支持：
- Discord 线程/频道
- Telegram topics（群组/超级群组中的 forum topics 和私信 topics）
- 插件渠道也可以通过同一绑定接口添加支持。
- Telegram 话题（群组/超级群组中的论坛话题，以及私信话题）
- 渠道插件也可以通过同一绑定接口添加支持。
## 渠道特定设置
对于非临时性工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
对于非临时工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
### 绑定模型
- `bindings[].type="acp"` 表示一个持久的 ACP 对话绑定。
- `bindings[].match` 标识目标对话：
- `bindings[].type="acp"` 表示一个持久化 ACP 对话绑定。
- `bindings[].match` 用于标识目标对话：
- Discord 频道或线程：`match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- Telegram forum topic：`match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- BlueBubbles 私聊/群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
- Telegram 论坛话题：`match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- BlueBubbles 私信/群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。
- iMessage 私聊/群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
- iMessage 私信/群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
对于稳定的群组绑定，优先使用 `chat_id:*`。
- `bindings[].agentId` 是拥有该绑定的 OpenClaw 智能体 id。
- 可选的 ACP 覆盖位于 `bindings[].acp` 下：
- `bindings[].agentId` 是所属的 OpenClaw 智能体 id。
- 可选的 ACP 覆盖项位于 `bindings[].acp` 下：
- `mode`（`persistent` 或 `oneshot`）
- `label`
- `cwd`
@ -267,22 +269,22 @@ ACP 绑定会话的覆盖优先级：
行为：
- OpenClaw 会在使用前确保已配置的 ACP 会话存在。
- 该频道或主题中的消息会路由到已配置的 ACP 会话。
- 在已绑定对话中，`/new` 和 `/reset` 会在原地重置同一个 ACP 会话键。
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。
- OpenClaw 会在使用前确保已存在配置好的 ACP 会话。
- 该频道或话题中的消息会路由到配置好的 ACP 会话。
- 在绑定的对话中，`/new` 和 `/reset` 会在原位重置同一个 ACP 会话键。
- 临时运行时绑定（例如通过线程聚焦流程创建的绑定）在存在时仍会生效。
- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置中继承目标智能体工作区。
- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失访问失败会作为启动错误暴露。
- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败会作为启动错误直接暴露。
## 启动 ACP 会话（接口）
### 从 `sessions_spawn`
### 从 `sessions_spawn` 启动
使用 `runtime: "acp"` 可以从智能体轮次或工具调用中启动一个 ACP 会话。
使用 `runtime: "acp"` 可从智能体轮次或工具调用中启动 ACP 会话。
```json
{
"task": "Open the repo and summarize failing tests",
"task": "打开仓库并总结失败的测试",
"runtime": "acp",
"agentId": "codex",
"thread": true,
@ -292,9 +294,9 @@ ACP 绑定会话的覆盖优先级：
说明：
- `runtime` 默认值是 `subagent`，因此对于 ACP 会话请显式设置 `runtime: "acp"`。
- `runtime` 默认为 `subagent`，因此 ACP 会话必须显式设置 `runtime: "acp"`。
- 如果省略 `agentId`，OpenClaw 会在已配置时使用 `acp.defaultAgent`。
- `mode: "session"` 需要 `thread: true`，以保持持久的绑定对话。
- `mode: "session"` 需要 `thread: true` 才能保持一个持久化的绑定对话。
接口详情：
@ -303,110 +305,110 @@ ACP 绑定会话的覆盖优先级：
- `agentId`（可选）：ACP 目标 harness id。如果已设置，则回退到 `acp.defaultAgent`。
- `thread`（可选，默认 `false`）：在支持时请求线程绑定流程。
- `mode`（可选）：`run`（一次性）或 `session`（持久化）。
- 默认值为 `run`
- 如果 `thread: true` 且未指定 mode，OpenClaw 可能会根据运行时路径默认采用持久化行为
- 默认为 `run`
- 如果 `thread: true` 且省略 `mode`，OpenClaw 可能会根据运行时路径默认采用持久化行为
- `mode: "session"` 需要 `thread: true`
- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP 启动会在已配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会直接返回。
- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略校验）。如果省略，ACP 启动会在已配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会被直接返回。
- `label`（可选）：用于会话/横幅文本中的面向操作员标签。
- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。
- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式回传给请求方会话。
- 在可用时，接受的响应中会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以对其执行 tail 以查看完整中继历史。
- `model`（可选）：对子 ACP 会话显式覆盖模型。对于 `runtime: "acp"` 会生效，因此子会话会使用所请求的模型，而不是静默回退到目标智能体默认值。
- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行的进度摘要作为系统事件流式回传给请求方会话。
- 可用时，接受的响应会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以 tail 它来查看完整的中继历史。
- `model`（可选）：为 ACP 子会话显式覆盖模型。对 `runtime: "acp"` 生效，因此子会话会使用所请求的模型，而不是静默回退到目标智能体默认模型。
## 投递模型
## 交付模型
ACP 会话既可以是交互式工作区，也可以是由父会话拥有的后台工作。投递路径取决于其形态。
ACP 会话既可以是交互式工作区，也可以是由父级拥有的后台工作。交付路径取决于它的形态。
### 交互式 ACP 会话
交互式会话旨在继续在可见的聊天界面中对话：
交互式会话旨在让你持续在可见的聊天界面中交流：
- `/acp spawn ... --bind here` 会将当前对话绑定到 ACP 会话。
- `/acp spawn ... --thread ...` 会将一个渠道线程/主题绑定到 ACP 会话。
- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。
- `/acp spawn ... --thread ...` 将某个渠道线程/话题绑定到 ACP 会话。
- 持久化配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。
在绑定对话中的后续消息会直接路由到 ACP 会话，而 ACP 输出会投递回同一个渠道/线程/主题。
绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会回传到同一个频道/线程/话题。
### 由父会话拥有的一次性 ACP 会话
### 由父级拥有的一次性 ACP 会话
由另一智能体运行启动的一次性 ACP 会话属于后台子会话，类似于子智能体：
由另一个智能体运行启动的一次性 ACP 会话是后台子级，类似子智能体：
- 父会话通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
- 子会话在自己的 ACP harness 会话中运行。
- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
- 子级在自己的 ACP harness 会话中运行。
- 完成结果通过内部任务完成通知路径回报。
- 当需要面向用户的回复时，父会话会用正常助手口吻重写子会话结果。
- 当需要面向用户的回复时，父级会用普通助手口吻重写子级结果。
不要将此路径视为父子之间的点对点聊天。子会话已经有一条回到父会话的完成结果通道。
不要把这一路径视为父子之间的点对点聊天。子级已经有一条回传完成结果给父级的通道。
### `sessions_send` 和 A2A 投递
### `sessions_send` 与 A2A 交付
`sessions_send` 可在启动后指向另一个会话。对于普通对等会话，OpenClaw 在注入消息后会使用一条智能体到智能体（A2A）的后续路径：
`sessions_send` 可以在启动后将消息发送到另一个会话。对于普通对等会话，OpenClaw 在注入消息后会使用智能体到智能体（A2A）的后续跟进路径：
- 等待目标会话回复
- 可选地允许请求方和目标方交换有限数量的后续轮次
- 请求目标方生成一条通知消息
- 将该通知投递到可见渠道或线程
- 等待目标会话的回复
- 可选地让请求方与目标交换有限轮数的后续消息
- 要求目标生成一条通知消息
- 将该通知投递到可见的频道或线程
这条 A2A 路径是用于对等发送的一种回退方案，适用于发送方需要一个可见后续结果的情况。当某个无关会话能够看到并给 ACP 目标发消息时，它仍保持启用，例如在较宽松的 `tools.sessions.visibility` 设置下。
这条 A2A 路径是对等发送时的一种回退机制，用于发送方需要可见跟进结果的场景。当一个无关会话能够看到并向 ACP 目标发送消息时，它仍然保持启用，例如在较宽松的 `tools.sessions.visibility` 设置下。
仅当请求方是其自己所拥有的、由父会话拥有的一次性 ACP 子会话的父会话时，OpenClaw 才会跳过 A2A 后续流程。在这种情况下，如果在任务完成之上再运行 A2A，可能会用子会话结果唤醒父会话，再把父会话的回复回送进子会话，从而形成父/子回声循环。对于这种已拥有的子会话场景，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责该结果。
只有当请求方是其自有的一次性 ACP 子会话的父级时，OpenClaw 才会跳过 A2A 跟进。在这种情况下，如果在任务完成之上再运行 A2A，就可能用子级结果唤醒父级，再将父级回复转发回子级，从而形成父子回声循环。对于这种自有子级场景，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责处理结果。
### 恢复现有会话
使用 `resumeSessionId` 可以继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此它能够带着完整上下文继续之前的工作。
使用 `resumeSessionId` 可继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此它会带着之前的完整上下文继续工作。
```json
{
"task": "Continue where we left off — fix the remaining test failures",
"task": "从我们上次停下的地方继续——修复剩余的测试失败",
"runtime": "acp",
"agentId": "codex",
"resumeSessionId": "<previous-session-id>"
}
```
常见使用场景：
常见用例：
- 将一个 Codex 会话从你的笔记本电脑交接到手机——告诉你的智能体继续你之前的工作
- 继续一个你最初在 CLI 中交互式启动、现在希望通过智能体无头继续的编码会话
- 将一个 Codex 会话从你的笔记本电脑交接到手机 —— 告诉你的智能体从你上次停下的地方继续
- 继续一个你此前在 CLI 中交互式启动、现在要通过智能体以无头方式继续的编码会话
- 继续处理因 Gateway 网关重启或空闲超时而中断的工作
说明：
- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用会返回错误。
- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然要求 `thread: true`。
- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。
- 如果找不到该会话 ID，启动会以清晰错误失败——不会静默回退为新会话。
- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用，会返回错误。
- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍然会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然要求 `thread: true`。
- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 都支持）。
- 如果找不到该会话 id，启动会以清晰错误失败 —— 不会静默回退到新会话。
<Accordion title="部署后冒烟测试">
Gateway 网关部署后，请运行一次实时端到端检查，而不要只信任单元测试：
Gateway 网关部署后，请运行一次真实的端到端检查，而不要只依赖单元测试：
1. 验证目标主机上的已部署 Gateway 网关版本和提交。
2. 打开一个指向实时智能体的临时 ACPX 桥接会话。
3. 要求该智能体调用 `sessions_spawn`，参数为 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。
4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，并且没有验证器错误。
1. 在目标主机上验证已部署的 Gateway 网关版本和提交。
2. 打开一个临时的 ACPX 桥接会话连接到在线智能体。
3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。
4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，并且没有校验器错误。
5. 清理该临时桥接会话。
请将门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"` —— 绑定线程的 `mode: "session"` 和流式中继路径属于单独、更丰富的集成测试阶段。
请将门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"` —— 绑定线程的 `mode: "session"` 和流中继路径属于另外更丰富的集成验证阶段。
</Accordion>
## 沙箱兼容性
ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运行。
ACP 会话当前运行在宿主运行时上，而不是 OpenClaw 沙箱内部。
当前限制：
- 如果请求方会话处于沙箱中，那么对于 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn`，ACP 启动都会被阻止。
- 如果请求方会话处于沙箱中，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 启动都会被阻止。
- 错误：`Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
- 带 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
- 带有 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
- 错误：`sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
当你需要由沙箱强制执行时，请使用 `runtime: "subagent"`。
当你需要由沙箱强制执行的运行时，请使用 `runtime: "subagent"`。
### 从 `/acp` 命令启动
在聊天中需要显式操作员控制时，请使用 `/acp spawn`。
在需要时，使用 `/acp spawn` 从聊天中进行显式的操作员控制。
```text
/acp spawn codex --mode persistent --thread auto
@ -427,15 +429,15 @@ ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运
## 会话目标解析
大多数 `/acp` 操作都接受一个可选会话目标（`session-key`、`session-id` 或 `session-label`）。
大多数 `/acp` 操作都接受一个可选的会话目标（`session-key`、`session-id` 或 `session-label`）。
解析顺序：
1. 显式目标参数（或 `/acp steer` 的 `--session`）
- 先尝试 key
- 再尝试 UUID 形状的 session id
- 然后尝试 label
2. 当前线程绑定（如果这个对话/线程绑定到了某个 ACP 会话）
- 然后尝试 UUID 形状的 session id
- 再尝试 label
2. 当前线程绑定（如果此对话/线程已绑定到 ACP 会话）
3. 当前请求方会话回退
当前对话绑定和线程绑定都会参与第 2 步。
@ -448,15 +450,15 @@ ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运
| 模式 | 行为 |
| ------ | ---------------------------------------------------------------------- |
| `here` | 原地绑定当前活动对话；如果当前没有活动对话则失败。 |
| `here` | 将当前活动对话原位绑定；如果当前没有活动对话则失败。 |
| `off` | 不创建当前对话绑定。 |
说明：
- `--bind here` 是操作员实现“让这个频道或聊天由 Codex 驱动”的最简单路径。
- `--bind here` 是“让这个频道或聊天由 Codex 支持”的最简单操作路径。
- `--bind here` 不会创建子线程。
- `--bind here` 仅在暴露当前对话绑定支持的渠道中可用。
- `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。
- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中同时使用。
## 启动线程模式
@ -466,328 +468,77 @@ ACP 会话当前运行在主机运行时中，而不是在 OpenClaw 沙箱内运
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | 在活动线程中：绑定该线程。在线程外：在支持时创建/绑定一个子线程。 |
| `here` | 要求当前处于活动线程中；如果不在线程中则失败。 |
| `off` | 不绑定。会话以未绑定状态启动。 |
| `off` | 不进行绑定。会话以未绑定状态启动。 |
说明：
- 在不支持线程绑定的界面上，默认行为实际上等同于 `off`。
- 绑定到线程的启动需要渠道策略支持：
- 绑定线程的启动需要渠道策略支持：
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
- 如果你希望固定当前对话而不创建子线程，请使用 `--bind here`。
- 当你想固定当前对话且不创建子线程时，请使用 `--bind here`。
## ACP 控制
| 命令 | 作用 | 示例 |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
| `/acp spawn` | 创建 ACP 会话；可选择当前对话绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | 取消目标会话的进行中轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | 向运行中的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | 关闭会话并解绑线程目标。 | `/acp close` |
| `/acp close` | 关闭会话并解除线程目标绑定。 | `/acp close` |
| `/acp status` | 显示后端、模式、状态、运行时选项和能力。 | `/acp status` |
| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` |
| `/acp set` | 通用运行时配置项写入。 | `/acp set model openai/gpt-5.4` |
| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` |
| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | 设置运行时工作目录覆盖。 | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` |
| `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` |
| `/acp model` | 设置运行时模型覆盖。 | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | 移除会话运行时选项覆盖。 | `/acp reset-options` |
| `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
| `/acp doctor` | 后端健康、能力、可执行修复建议。 | `/acp doctor` |
| `/acp sessions` | 列出存储中的最近 ACP 会话。 | `/acp sessions` |
| `/acp doctor` | 后端健康状态、能力和可执行修复建议。 | `/acp doctor` |
| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` |
`/acp status` 会显示生效的运行时选项，以及运行时级别和后端级别的会话标识符。当某个后端缺少某项能力时，不支持的控制错误会被清晰显示。`/acp sessions` 会为当前已绑定或请求方会话读取存储；目标令牌（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括按智能体自定义的 `session.store` 根路径。
`/acp status` 会显示生效的运行时选项，以及运行时级别和后端级别的会话标识符。当后端缺少某项能力时，不支持控制的错误会被清晰地呈现出来。`/acp sessions` 会读取当前绑定会话或请求方会话的存储；目标标记（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根路径。
## 运行时选项映射
`/acp` 同时提供便捷命令和一个通用设置器。
`/acp` 提供了便捷命令和一个通用设置器。
等价操作：
等效操作：
- `/acp model <id>` 映射到运行时配置键 `model`。
- `/acp permissions <profile>` 映射到运行时配置键 `approval_policy`。
- `/acp timeout <seconds>` 映射到运行时配置键 `timeout`。
- `/acp cwd <path>` 直接更新运行时 cwd 覆盖。
- `/acp cwd <path>` 直接更新运行时 `cwd` 覆盖。
- `/acp set <key> <value>` 是通用路径。
- 特殊情况：`key=cwd` 使用 cwd 覆盖路径。
- 特殊情况：`key=cwd` 使用 `cwd` 覆盖路径。
- `/acp reset-options` 会清除目标会话的所有运行时覆盖。
## acpx harness 支持（当前）
## acpx harness、插件设置和权限
当前 acpx 内置 harness 别名：
- `claude`
- `codex`
- `copilot`
- `cursor`（Cursor CLI：`cursor-agent acp`）
- `droid`
- `gemini`
- `iflow`
- `kilocode`
- `kimi`
- `kiro`
- `openclaw`
- `opencode`
- `pi`
- `qwen`
当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则 `agentId` 应优先使用这些值。
如果你本地安装的 Cursor 仍将 ACP 暴露为 `agent acp`，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。
直接使用 acpx CLI 也可以通过 `--agent <command>` 指向任意适配器，但这个原始逃生舱口属于 acpx CLI 功能（不是正常的 OpenClaw `agentId` 路径）。
## 必需配置
核心 ACP 基线配置：
```json5
{
acp: {
enabled: true,
// Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
dispatch: { enabled: true },
backend: "acpx",
defaultAgent: "codex",
allowedAgents: [
"claude",
"codex",
"copilot",
"cursor",
"droid",
"gemini",
"iflow",
"kilocode",
"kimi",
"kiro",
"openclaw",
"opencode",
"pi",
"qwen",
],
maxConcurrentSessions: 8,
stream: {
coalesceIdleMs: 300,
maxChunkChars: 1200,
},
runtime: {
ttlMinutes: 120,
},
},
}
```
线程绑定配置取决于具体的渠道适配器。Discord 示例：
```json5
{
session: {
threadBindings: {
enabled: true,
idleHours: 24,
maxAgeHours: 0,
},
},
channels: {
discord: {
threadBindings: {
enabled: true,
spawnAcpSessions: true,
},
},
},
}
```
如果绑定到线程的 ACP 启动不起作用，请先验证适配器功能标志：
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
当前对话绑定不需要创建子线程。它们需要一个活动对话上下文，以及一个暴露 ACP 对话绑定能力的渠道适配器。
参见 [配置参考](/zh-CN/gateway/configuration-reference)。
## acpx 后端的插件设置
全新安装默认启用了内置的 `acpx` 运行时插件，因此 ACP 通常无需手动安装插件即可工作。
先从以下命令开始：
```text
/acp doctor
```
如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者你想切换到本地开发检出版本，请使用显式插件路径：
```bash
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
```
开发期间的本地工作区安装：
```bash
openclaw plugins install ./path/to/local/acpx-plugin
```
然后验证后端健康状态：
```text
/acp doctor
```
### acpx 命令和版本配置
默认情况下，内置的 `acpx` 插件使用其插件本地固定版本的二进制文件（插件包内的 `node_modules/.bin/acpx`）。启动时会先将后端注册为未就绪，并由后台任务验证 `acpx --version`；如果二进制缺失或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@<pinned>` 后再重新验证。整个过程中 Gateway 网关始终保持非阻塞。
在插件配置中覆盖命令或版本：
```json
{
"plugins": {
"entries": {
"acpx": {
"enabled": true,
"config": {
"command": "../acpx/dist/cli.js",
"expectedVersion": "any"
}
}
}
}
}
```
- `command` 接受绝对路径、相对路径（相对于 OpenClaw 工作区解析）或命令名。
- `expectedVersion: "any"` 会禁用严格版本匹配。
- 自定义 `command` 路径会禁用插件本地自动安装。
参见 [Plugins](/zh-CN/tools/plugin)。
### 自动依赖安装
当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，acpx
运行时依赖（平台特定二进制文件）会通过 postinstall hook 自动安装。如果自动安装失败，Gateway 网关仍会正常启动，并通过 `openclaw acp doctor` 报告缺失的依赖。
### 插件工具 MCP 桥接
默认情况下，ACPX 会话**不会**将 OpenClaw 插件注册的工具暴露给 ACP harness。
如果你希望 Codex 或 Claude Code 这样的 ACP 智能体能够调用已安装的
OpenClaw 插件工具，例如记忆 recall/store，请启用专用桥接：
```bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
```
其作用如下：
- 在 ACPX 会话引导中注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。
- 暴露已安装且已启用的 OpenClaw 插件已注册的插件工具。
- 让该功能保持显式开启，并默认关闭。
安全和信任说明：
- 这会扩大 ACP harness 的工具接口范围。
- ACP 智能体只能访问 Gateway 网关中已激活的插件工具。
- 请将其视为与允许这些插件在 OpenClaw 自身中执行相同的信任边界。
- 启用前请审查已安装的插件。
自定义 `mcpServers` 仍可照常使用。内置的插件工具桥接只是一个额外的选择启用便利功能，并不是对通用 MCP 服务器配置的替代。
### OpenClaw 工具 MCP 桥接
默认情况下，ACPX 会话同样**不会**通过 MCP 暴露内置 OpenClaw 工具。当 ACP 智能体需要访问选定的内置工具（例如 `cron`）时，请启用单独的核心工具桥接：
```bash
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
```
其作用如下：
- 在 ACPX 会话引导中注入一个名为 `openclaw-tools` 的内置 MCP 服务器。
- 暴露选定的内置 OpenClaw 工具。初始服务器暴露的是 `cron`。
- 让核心工具暴露保持显式开启，并默认关闭。
### 运行时超时配置
内置的 `acpx` 插件默认将嵌入式运行时轮次超时设为 120 秒。这为 Gemini CLI 等较慢的 harness 预留了足够时间来完成 ACP 启动和初始化。如果你的主机需要不同的运行时限制，请进行覆盖：
```bash
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
```
更改该值后请重启 Gateway 网关。
### 健康探针智能体配置
内置的 `acpx` 插件在判定嵌入式运行时后端是否就绪时，会探测一个 harness 智能体。默认是 `codex`。如果你的部署使用了不同的默认 ACP 智能体，请将探针智能体设置为同样的 id：
```bash
openclaw config set plugins.entries.acpx.config.probeAgent claude
```
更改该值后请重启 Gateway 网关。
## 权限配置
ACP 会话以非交互方式运行——没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。acpx 插件提供了两个配置键来控制权限处理方式：
这些 ACPX harness 权限独立于 OpenClaw exec 审批，也独立于 CLI-backend 的供应商绕过标志，例如 Claude CLI 的 `--permission-mode bypassPermissions`。ACPX 的 `approve-all` 是 ACP 会话在 harness 级别的破玻璃开关。
### `permissionMode`
控制 harness 智能体在不提示的情况下可执行哪些操作。
| 值 | 行为 |
| --------------- | --------------------------------------------------------- |
| `approve-all` | 自动批准所有文件写入和 shell 命令。 |
| `approve-reads` | 仅自动批准读取；写入和 exec 需要提示。 |
| `deny-all` | 拒绝所有权限提示。 |
### `nonInteractivePermissions`
控制当本应显示权限提示、但没有可交互 TTY 可用时（ACP 会话始终如此）的行为。
| 值 | 行为 |
| ------ | ----------------------------------------------------------------- |
| `fail` | 使用 `AcpRuntimeError` 中止会话。**（默认）** |
| `deny` | 静默拒绝该权限并继续执行（优雅降级）。 |
### 配置
通过插件配置进行设置：
```bash
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
```
更改这些值后请重启 Gateway 网关。
> **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何会触发权限提示的写入或 exec 操作都可能以 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 失败。
>
> 如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，这样会话会优雅降级，而不是直接崩溃。
关于 acpx harness 配置（Claude Code / Codex / Gemini CLI 别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参见
[ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。
## 故障排除
| 症状 | 可能原因 | 修复 |
| 症状 | 可能原因 | 修复方法 |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACP runtime backend is not configured` | 后端插件缺失或已禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 |
| `ACP is disabled by policy (acp.enabled=false)` | ACP 已被全局禁用。 | 设置 `acp.enabled=true`。 |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已被禁用。 | 设置 `acp.dispatch.enabled=true`。 |
| `ACP agent "<id>" is not allowed by policy` | 智能体不在允许名单中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
| `Unable to resolve session target: ...` | 错误的 key/id/label 令牌。 | 运行 `/acp sessions`，复制精确的 key/label 后重试。 |
| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动且可绑定对话的情况下使用了 `--bind here`。 | 移动到目标聊天/频道后重试，或使用无绑定启动。 |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已禁用。 | 设置 `acp.dispatch.enabled=true`。 |
| `ACP agent "<id>" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
| `Unable to resolve session target: ...` | key/id/label 标记错误。 | 运行 `/acp sessions`，复制准确的 key/label 后重试。 |
| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定对话的情况下使用了 `--bind here`。 | 切换到目标聊天/频道后重试，或使用不绑定的启动。 |
| `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 当前活动绑定目标归另一位用户所有。 | 由所有者重新绑定，或使用不同的对话或线程。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 切换到目标线程，或使用 `--thread auto`/`off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有当前活动绑定目标。 | 由拥有者重新绑定，或使用其他对话或线程。 |
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或切换到受支持的适配器/渠道。 |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话处于沙箱中。 | 在沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话启动 ACP。 |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 如需强制沙箱，请使用 `runtime="subagent"`，或者在非沙箱会话中以 `sandbox="inherit"` 使用 ACP。 |
| 已绑定会话缺少 ACP 元数据 | ACP 会话元数据已陈旧/被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 阻止了非交互式 ACP 会话中的写入/exec。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](#permission-configuration)。 |
| ACP 会话很早失败且输出很少 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，请设置 `permissionMode=approve-all`；如需优雅降级，请设置 `nonInteractivePermissions=deny`。 |
| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话没有报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于宿主侧；请求方会话处于沙箱中。 | 在沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话运行 ACP 启动。 |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对需要强制沙箱隔离的场景使用 `runtime="subagent"`，或从非沙箱会话中配合 `sandbox="inherit"` 使用 ACP。 |
| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已过期/被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见 [权限配置](#permission-configuration)。 |
| ACP 会话在很少输出的情况下提前失败 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。若需完整权限，设置 `permissionMode=approve-all`；若需优雅降级，设置 `nonInteractivePermissions=deny`。 |
| ACP 会话在完成工作后无限期卡住 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止陈旧进程。 |
## 相关内容

349
docs/zh-CN/tools/browser-control.md Normal file
View File

@ -0,0 +1,349 @@
---
read_when:
- 通过本地控制 API 编写脚本或调试智能体浏览器
- 正在查找 `openclaw browser` CLI 参考文档
- 添加带有快照和 refs 的自定义浏览器自动化
summary: OpenClaw 浏览器控制 API、CLI 参考和脚本操作
title: 浏览器控制 API
x-i18n:
generated_at: "2026-04-24T02:39:52Z"
model: gpt-5.4
provider: openai
source_hash: e29ad295085e2c36a6c2ce01366a4186e45a7ecfe1d3c3072353c55794b05b5f
source_path: tools/browser-control.md
workflow: 15
---
有关设置、配置和故障排除，请参阅 [Browser](/zh-CN/tools/browser)。
本页是本地控制 HTTP API、`openclaw browser`
CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档。
## 控制 API（可选）
仅用于本地集成时，Gateway 网关会暴露一个小型的 loopback HTTP API：
- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
- 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
- 快照/截图：`GET /snapshot`、`POST /screenshot`
- 操作：`POST /navigate`、`POST /act`
- Hooks：`POST /hooks/file-chooser`、`POST /hooks/dialog`
- 下载：`POST /download`、`POST /wait/download`
- 调试：`GET /console`、`POST /pdf`
- 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight`
- 网络：`POST /response/body`
- 状态：`GET /cookies`、`POST /cookies/set`、`POST /cookies/clear`
- 状态：`GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear`
- 设置：`POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device`
所有端点都接受 `?profile=<name>`。
如果配置了共享密钥 Gateway 网关认证，浏览器 HTTP 路由也需要认证：
- `Authorization: Bearer <gateway token>`
- `x-openclaw-password: <gateway password>`，或使用该密码的 HTTP Basic auth
注意：
- 这个独立的 loopback 浏览器 API **不会** 使用受信任代理或
Tailscale Serve 身份标头。
- 如果 `gateway.auth.mode` 为 `none` 或 `trusted-proxy`，这些 loopback 浏览器
路由不会继承这些携带身份信息的模式；请将它们保持为仅 loopback 可用。
### `/act` 错误约定
`POST /act` 对路由级验证和策略失败使用结构化错误响应：
```json
{ "error": "<message>", "code": "ACT_*" }
```
当前的 `code` 值：
- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或无法识别。
- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载标准化或验证失败。
- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不受支持的操作类型中使用了 `selector`。
- `ACT_EVALUATE_DISABLED`（HTTP 403）：配置中禁用了 `evaluate`（或 `wait --fn`）。
- `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批处理中的 `targetId` 与请求目标冲突。
- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：现有会话 profile 不支持此操作。
其他运行时失败仍可能返回不带
`code` 字段的 `{ "error": "<message>" }`。
### Playwright 要求
某些功能（navigate/act/AI 快照/role 快照、元素截图、
PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回
明确的 501 错误。
未安装 Playwright 时仍可使用的功能：
- ARIA 快照
- 当每个标签页的 CDP
WebSocket 可用时，受管 `openclaw` 浏览器的页面截图
- `existing-session` / Chrome MCP profiles 的页面截图
- 来自快照输出的 `existing-session` 基于 ref 的截图（`--ref`）
仍然需要 Playwright 的功能：
- `navigate`
- `act`
- AI 快照 / role 快照
- CSS 选择器元素截图（`--element`）
- 完整浏览器 PDF 导出
元素截图也会拒绝 `--full-page`；该路由会返回 `fullPage is
not supported for element screenshots`。
如果你看到 `Playwright is not available in this gateway build`，请修复
内置浏览器插件运行时依赖，确保已安装 `playwright-core`，
然后重启 Gateway 网关。对于打包安装，请运行 `openclaw doctor --fix`。
对于 Docker，还需要安装下面所示的 Chromium 浏览器二进制文件。
#### Docker Playwright 安装
如果你的 Gateway 网关运行在 Docker 中，请避免使用 `npx playwright`（npm 覆盖冲突）。
请改用内置 CLI：
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
要持久化浏览器下载，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如
`/home/node/.cache/ms-playwright`），并确保通过
`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化 `/home/node`。请参阅 [Docker](/zh-CN/install/docker)。
## 工作原理（内部）
一个小型 loopback 控制服务器接收 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（点击/输入/快照/PDF）通过 CDP 之上的 Playwright 执行；当缺少 Playwright 时，只有不依赖 Playwright 的操作可用。智能体看到的是一个稳定的接口，而底层的本地/远程浏览器和 profiles 可以自由切换。
## CLI 快速参考
所有命令都接受 `--browser-profile <name>` 以定位到特定 profile，并接受 `--json` 以输出机器可读格式。
<AccordionGroup>
<Accordion title="基础：状态、标签页、打开/聚焦/关闭">
```bash
openclaw browser status
openclaw browser start
openclaw browser stop # 也会清除仅附加/远程 CDP 上的仿真
openclaw browser tabs
openclaw browser tab # 当前标签页的快捷方式
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://example.com
openclaw browser focus abcd1234
openclaw browser close abcd1234
```
</Accordion>
<Accordion title="检查：截图、快照、控制台、错误、请求">
```bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12 # 或 --ref e12
openclaw browser snapshot
openclaw browser snapshot --format aria --limit 200
openclaw browser snapshot --interactive --compact --depth 6
openclaw browser snapshot --efficient
openclaw browser snapshot --labels
openclaw browser snapshot --selector "#main" --interactive
openclaw browser snapshot --frame "iframe#main" --interactive
openclaw browser console --level error
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser pdf
openclaw browser responsebody "**/api" --max-chars 5000
```
</Accordion>
<Accordion title="操作：navigate、click、type、drag、wait、evaluate">
```bash
openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double # 或对 role refs 使用 e12
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser hover 44
openclaw browser scrollintoview e12
openclaw browser drag 10 11
openclaw browser select 9 OptionA OptionB
openclaw browser download e12 report.pdf
openclaw browser waitfordownload report.pdf
openclaw browser upload /tmp/openclaw/uploads/file.pdf
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
openclaw browser wait --text "Done"
openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
openclaw browser highlight e12
openclaw browser trace start
openclaw browser trace stop
```
</Accordion>
<Accordion title="状态：cookies、storage、offline、headers、geo、device">
```bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear
openclaw browser set offline on
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
openclaw browser set credentials user pass # 使用 --clear 移除
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"
```
</Accordion>
</AccordionGroup>
注意：
- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的点击或按键之前运行它们。
- `click`/`type`/等操作需要来自 `snapshot` 的 `ref`（数字 `12` 或 role ref `e12`）。操作有意不支持 CSS 选择器。
- 下载、trace 和上传路径被限制在 OpenClaw 临时根目录下：`/tmp/openclaw{,/downloads,/uploads}`（回退为：`${os.tmpdir()}/openclaw/...`）。
- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入框。
快照标志一览：
- `--format ai`（安装了 Playwright 时为默认）：带数字 refs 的 AI 快照（`aria-ref="<n>"`）。
- `--format aria`：无障碍树，不含 refs；仅用于检查。
- `--efficient`（或 `--mode efficient`）：紧凑型 role 快照预设。设置 `browser.snapshotDefaults.mode: "efficient"` 可将其设为默认值（参见 [Gateway 配置](/zh-CN/gateway/configuration-reference#browser)）。
- `--interactive`、`--compact`、`--depth`、`--selector` 会强制使用 role 快照，并生成 `ref=e12` refs。`--frame "<iframe>"` 会将 role 快照限定在某个 iframe 中。
- `--labels` 会添加一张仅视口的截图，并叠加 ref 标签（输出 `MEDIA:<path>`）。
## 快照和 refs
OpenClaw 支持两种“快照”样式：
- **AI 快照（数字 refs）**：`openclaw browser snapshot`（默认；`--format ai`）
- 输出：包含数字 refs 的文本快照。
- 操作：`openclaw browser click 12`、`openclaw browser type 23 "hello"`。
- 在内部，ref 通过 Playwright 的 `aria-ref` 解析。
- **Role 快照（如 `e12` 的 role refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
- 输出：基于 role 的列表/树，带有 `[ref=e12]`（以及可选的 `[nth=1]`）。
- 操作：`openclaw browser click e12`、`openclaw browser highlight e12`。
- 在内部，ref 通过 `getByRole(...)` 解析（重复项会额外使用 `nth()`）。
- 添加 `--labels` 可附带一张叠加 `e12` 标签的视口截图。
Ref 行为：
- Refs **不会在导航之间保持稳定**；如果操作失败，请重新运行 `snapshot` 并使用新的 ref。
- 如果 role 快照是在 `--frame` 下获取的，role refs 会限定在该 iframe 中，直到下一次 role 快照。
## Wait 增强功能
你可以等待的不只是时间或文本：
- 等待 URL（支持 Playwright 的 glob）：
- `openclaw browser wait --url "**/dash"`
- 等待加载状态：
- `openclaw browser wait --load networkidle`
- 等待 JS 谓词：
- `openclaw browser wait --fn "window.ready===true"`
- 等待选择器变为可见：
- `openclaw browser wait "#main"`
这些条件可以组合使用：
```bash
openclaw browser wait "#main" \
--url "**/dash" \
--load networkidle \
--fn "window.ready===true" \
--timeout-ms 15000
```
## 调试工作流
当某个操作失败时（例如“不可见”“严格模式违规”“被遮挡”）：
1. `openclaw browser snapshot --interactive`
2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用 role refs）
3. 如果仍然失败：运行 `openclaw browser highlight <ref>`，查看 Playwright 实际定位的目标
4. 如果页面行为异常：
- `openclaw browser errors --clear`
- `openclaw browser requests --filter api --clear`
5. 如需深入调试：记录 trace：
- `openclaw browser trace start`
- 复现问题
- `openclaw browser trace stop`（输出 `TRACE:<path>`）
## JSON 输出
`--json` 用于脚本编写和结构化工具。
示例：
```bash
openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json
```
JSON 格式的 role 快照包含 `refs`，以及一个小型 `stats` 块（lines/chars/refs/interactive），便于工具推断负载大小和密度。
## 状态和环境调节项
这些选项对于“让网站表现得像 X 一样”的工作流非常有用：
- Cookies：`cookies`、`cookies set`、`cookies clear`
- Storage：`storage local|session get|set|clear`
- Offline：`set offline on|off`
- Headers：`set headers --headers-json '{"X-Debug":"1"}'`（旧版 `set headers --json '{"X-Debug":"1"}'` 仍然受支持）
- HTTP Basic auth：`set credentials user pass`（或 `--clear`）
- 地理位置：`set geo <lat> <lon> --origin "https://example.com"`（或 `--clear`）
- 媒体：`set media dark|light|no-preference|none`
- 时区 / 区域设置：`set timezone ...`、`set locale ...`
- 设备 / 视口：
- `set device "iPhone 14"`（Playwright 设备预设）
- `set viewport 1280 720`
## 安全与隐私
- openclaw 浏览器 profile 可能包含已登录的会话；请将其视为敏感信息。
- `browser act kind=evaluate` / `openclaw browser evaluate` 和 `wait --fn`
会在页面上下文中执行任意 JavaScript。提示注入可能会引导
这一行为。如果你不需要它，请使用 `browser.evaluateEnabled=false` 将其禁用。
- 关于登录和反机器人说明（X/Twitter 等），请参阅 [Browser login + X/Twitter posting](/zh-CN/tools/browser-login)。
- 请将 Gateway 网关/节点主机保持为私有（仅 loopback 或仅 tailnet）。
- 远程 CDP 端点权限很高；请通过隧道并加以保护。
严格模式示例（默认阻止私有/内部目标）：
```json5
{
browser: {
ssrfPolicy: {
dangerouslyAllowPrivateNetwork: false,
hostnameAllowlist: ["*.example.com", "example.com"],
allowedHostnames: ["localhost"], // 可选精确允许
},
},
}
```
## 相关内容
- [Browser](/zh-CN/tools/browser) — 概览、配置、profiles、安全
- [Browser login](/zh-CN/tools/browser-login) — 登录网站
- [Browser Linux troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
- [Browser WSL2 troubleshooting](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)

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

@ -1,41 +1,39 @@
---
read_when:
- 添加由智能体控制的浏览器自动化
- |-
调试为什么 openclaw 会干扰你自己的 Chrome♀♀♀♀♀♀analysis to=functions.read code 】!【json
{"path":"/home/runner/work/docs/docs/source/scripts/docs-i18n/","offset":1,"limit":1}
- 调试为什么 openclaw 会干扰你自己的 Chrome
- 在 macOS 应用中实现浏览器设置 + 生命周期
summary: 集成式浏览器控制服务 + 动作命令
summary: 集成浏览器控制服务 + 操作命令
title: 浏览器（由 OpenClaw 管理）
x-i18n:
generated_at: "2026-04-23T21:07:01Z"
generated_at: "2026-04-24T02:39:44Z"
model: gpt-5.4
provider: openai
source_hash: 3232ec0627004aabd8fe7c73efa237949e4148a9648de7a12951c2af54608d4b
source_hash: 2fb0fc0b6235fa8a0324b754e247e015d5ca19d114d324d565ed4a19f9313f7e
source_path: tools/browser.md
workflow: 15
---
OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium profile**，由智能体控制。
它与您的个人浏览器隔离，并通过 Gateway 网关中的一个小型本地
控制服务进行管理（仅限 loopback）。
OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。
它与你的个人浏览器隔离，并通过 Gateway 网关内部一个小型本地控制服务进行管理
（仅限 loopback）。
新手视角：
初学者视角：
- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。
- `openclaw` profile **不会**触碰你的个人浏览器 profile。
- `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。
- 智能体可以在一个安全通道中**打开标签页、读取页面、点击和输入**。
- 内置的 `user` profile 会通过 Chrome MCP 连接到你真实的、已登录的 Chrome 会话。
- 内置的 `user` 配置文件会通过 Chrome MCP 连接到你真实的、已登录的 Chrome 会话。
## 你将获得什么
## 你会获得什么
- 一个名为 **openclaw** 的独立浏览器 profile（默认使用橙色强调色）。
- 一个名为 **openclaw** 的独立浏览器配置文件（默认橙色强调色）。
- 可预测的标签页控制（列出/打开/聚焦/关闭）。
- 智能体动作（点击/输入/拖拽/选择）、快照、截图、PDF。
- 可选的多 profile 支持（`openclaw`、`work`、`remote`，等等）。
- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。
- 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。
这个浏览器**不是**你的日常主浏览器。它是一个安全、隔离的表面，
用于智能体自动化和验证。
这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的界面，用于
智能体自动化与验证。
## 快速开始
@ -46,15 +44,14 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
如果你看到 “Browser disabled”，请在配置中启用它（见下文），然后重启
如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启
Gateway 网关。
如果 `openclaw browser` 整体都不存在，或者智能体提示浏览器工具
不可用，请直接跳转到 [缺少 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
{
@ -68,13 +65,13 @@ Gateway 网关。
}
```
默认情况下需要同时满足 `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 网关，以便插件重新注册其服务。
## 缺少 browser 命令或工具
## 缺少浏览器命令或工具
如果升级后 `openclaw browser` 变成未知命令，`browser.request` 缺失，或智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中未包含 `browser`。请将它加上：
如果升级后 `openclaw browser` 未知、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。请添加它：
```json5
{
@ -84,19 +81,18 @@ Gateway 网关。
}
```
`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代 allowlist 成员资格——allowlist 负责门控插件加载，而工具策略只会在加载之后才生效。完全移除 `plugins.allow` 也会恢复默认行为。
`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代允许列表成员资格——允许列表控制插件加载，而工具策略只有在加载之后才会运行。完全移除 `plugins.allow` 也会恢复默认行为。
## Profiles：`openclaw` vs `user`
## 配置文件：`openclaw` 与 `user`
- `openclaw`：受管理、隔离的浏览器（不需要扩展）。
- `user`：内置的 Chrome MCP 附加 profile，用于连接你**真实的已登录 Chrome**
会话。
- `openclaw`：受管理的隔离浏览器（无需扩展）。
- `user`：内置的 Chrome MCP 连接配置文件，用于连接你**真实的已登录 Chrome** 会话。
对于智能体浏览器工具调用：
- 默认：使用隔离的 `openclaw` 浏览器。
- 当已登录会话很重要，并且用户本人在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。
- 当你想指定某种浏览器模式时，`profile` 是显式覆盖项。
- 当现有登录会话很重要，且用户就在电脑前可以点击/批准任何连接提示时，优先使用 `profile="user"`。
- 当你想要指定浏览器模式时，`profile` 是显式覆盖项。
如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。
@ -107,16 +103,16 @@ Gateway 网关。
```json5
{
browser: {
enabled: true, // default: true
enabled: true, // 默认：true
ssrfPolicy: {
// dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
// allowPrivateNetwork: true, // legacy alias
// dangerouslyAllowPrivateNetwork: true, // 仅在可信的私有网络访问场景下启用
// allowPrivateNetwork: true, // 旧别名
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
// cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
// cdpUrl: "http://127.0.0.1:18792", // 旧的单配置文件覆盖项
remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒）
remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒）
defaultProfile: "openclaw",
color: "#FF4500",
headless: false,
@ -147,29 +143,29 @@ Gateway 网关。
<Accordion title="端口与可达性">
- 控制服务会绑定到 loopback，其端口由 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让同一族派生端口一起偏移。
- 本地 `openclaw` profiles 会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 场景下才需要手动设置这些值。未设置时，`cdpUrl` 默认指向受管理的本地 CDP 端口。
- 控制服务绑定到 loopback，端口基于 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会同步移动同一组派生端口。
- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 场景下才需要设置它们。未设置时，`cdpUrl` 默认指向受管理的本地 CDP 端口。
- `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP HTTP 可达性检查；`remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 握手。
</Accordion>
<Accordion title="SSRF 策略">
- 浏览器导航与 open-tab 会在导航前执行 SSRF 防护，并在导航后对最终 `http(s)` URL 做尽力复检。
- 在严格 SSRF 模式下，远程 CDP 端点发现与 `/json/version` 探测（`cdpUrl`）也会被检查。
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你明确且信任私有网络浏览器访问时才启用。
- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。
- 浏览器导航与打开标签页会在导航前进行 SSRF 防护，并在最终 `http(s)` URL 上尽力再次检查。
- 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你明确可信任私有网络浏览器访问时才启用。
- `browser.ssrfPolicy.allowPrivateNetwork` 作为旧别名仍然受支持。
</Accordion>
<Accordion title="Profile 行为">
<Accordion title="配置文件行为">
- `attachOnly: true` 表示绝不启动本地浏览器；只有在浏览器已运行时才进行附加。
- `color`（顶层和按 profile）会给浏览器 UI 着色，以便你看出当前激活的是哪个 profile。
- 默认 profile 是 `openclaw`（受管理的独立实例）。使用 `defaultProfile: "user"` 可切换为已登录的用户浏览器。
- 自动检测顺序：若系统默认浏览器是基于 Chromium，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。
- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。对该驱动不要设置 `cdpUrl`。
- 当某个 existing-session profile 应附加到非默认 Chromium 用户 profile（Brave、Edge 等）时，请设置 `browser.profiles.<name>.userDataDir`。
- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已经运行时连接。
- `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`。
</Accordion>
@ -177,15 +173,15 @@ Gateway 网关。
## 使用 Brave（或其他基于 Chromium 的浏览器）
如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），
OpenClaw 会自动使用它。你也可以通过设置 `browser.executablePath` 来覆盖
如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），
OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖
自动检测：
```bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"
```
或者在配置中按平台设置：
或者按平台在配置中设置：
<Tabs>
<Tab title="macOS">
@ -219,50 +215,47 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
## 本地控制 vs 远程控制
- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并可启动本地浏览器。
- **远程控制（node host）：** 在有浏览器的机器上运行 node host；Gateway 网关会将浏览器动作代理到它。
- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`），
以附加到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
- **本地控制（默认）：** Gateway 网关会启动 loopback 控制服务，并可启动本地浏览器。
- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理过去。
- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以连接到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
不同 profile 模式的停止行为不同：
停止行为会因配置文件模式而不同：
- 本地受管理 profiles：`openclaw browser stop` 会停止由
- 本地受管理配置文件：`openclaw browser stop` 会停止
OpenClaw 启动的浏览器进程
- attach-only 和远程 CDP profiles：`openclaw browser stop` 会关闭当前活动的
控制会话，并释放 Playwright/CDP 仿真覆盖（viewport、
color scheme、locale、timezone、offline mode 以及类似状态），即使
该浏览器进程并不是由 OpenClaw 启动的
- 仅连接和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前活动的
控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、
配色方案、区域设置、时区、离线模式及类似状态），即使
OpenClaw 并未启动任何浏览器进程
远程 CDP URL 可以包含认证信息：
- Query token（例如 `https://provider.example?token=<token>`）
- HTTP Basic auth（例如 `https://user:pass@provider.example`）
- 查询参数令牌（例如 `https://provider.example?token=<token>`）
- HTTP Basic 认证（例如 `https://user:pass@provider.example`）
OpenClaw 在调用 `/json/*` 端点以及连接
CDP WebSocket 时都会保留这些认证信息。对于 token，建议优先使用环境变量或 secrets 管理器，
而不是将其提交到配置文件中。
OpenClaw 在调用 `/json/*` 端点以及连接
CDP WebSocket 时会保留这些认证信息。对于令牌，建议优先使用环境变量或秘密管理器，而不是将其提交到配置文件中。
## 节点浏览器代理（零配置默认）
如果你在拥有浏览器的机器上运行了**node host**，OpenClaw 可以
自动将浏览器工具调用路由到该节点，而无需额外的浏览器配置。
这是远程 gateway 的默认路径。
如果你在拥有浏览器的机器上运行了一个**节点主机**，OpenClaw 可以
在无需任何额外浏览器配置的情况下，自动将浏览器工具调用路由到该节点。
这是远程 Gateway 网关的默认路径。
说明：
- node host 会通过一个**代理命令**暴露其本地浏览器控制服务器。
- Profiles 来自该节点自身的 `browser.profiles` 配置（与本地相同）。
- `nodeHost.browserProxy.allowProfiles` 是可选的。保持为空即可获得旧版/默认行为：所有已配置的 profiles 都可以通过代理访问，包括 profile 创建/删除路由。
- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有加入 allowlist 的 profiles 才能被访问，且持久化 profile 创建/删除路由会在代理表面被阻止。
- 如果你不想使用它，可以禁用：
- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。
- 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。
- `nodeHost.browserProxy.allowProfiles` 是可选项。保持为空即可使用旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。
- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可以被访问，而且持久化配置文件创建/删除路由会在代理层被阻止。
- 如果你不想启用它，可以关闭：
- 在节点上：`nodeHost.browserProxy.enabled=false`
- 在 gateway 上：`gateway.nodes.browser.mode="off"`
- 在 Gateway 网关上：`gateway.nodes.browser.mode="off"`
## Browserless（托管远程 CDP）
[Browserless](https://browserless.io) 是一项托管 Chromium 服务，通过 HTTPS 和 WebSocket 暴露
CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器 profile，
最简单的方案是直接使用 Browserless 连接文档中给出的 WebSocket URL。
[Browserless](https://browserless.io) 是一项托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露
CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器配置文件，最简单的选择通常是 Browserless 连接文档中提供的直接 WebSocket URL。
示例：
@ -285,38 +278,38 @@ CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器 profi
说明：
- 请将 `<BROWSERLESS_API_KEY>` 替换为你的真实 Browserless token。
- 将 `<BROWSERLESS_API_KEY>` 替换为你真实的 Browserless 令牌。
- 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。
- 如果 Browserless 给你的是 HTTPS 基础 URL，你可以将其转换为
`wss://` 用于直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw
通过 `/json/version` 自动发现。
- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你既可以将其转换为
`wss://` 以建立直接 CDP 连接，也可以保留 HTTPS URL，让 OpenClaw
去发现 `/json/version`。
## 直接 WebSocket CDP providers
## 直接 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 debugger URL，然后
进行连接。没有 WebSocket 回退。
- **直接 WebSocket 端点** —— `ws://host[:port]/devtools/<kind>/<id>` 或
`wss://...`，其中路径为 `/devtools/browser|page|worker|shared_worker|service_worker/<id>`。
OpenClaw 会直接通过 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` 发现（并将 scheme 标准化为 `http`/`https`）；
如果发现结果返回了 `webSocketDebuggerUrl`，就使用它；否则 OpenClaw
会回退为对裸根地址直接执行 WebSocket 握手。这让一个指向本地 Chrome 的
裸 `ws://` 也能工作，因为 Chrome 只会在来自
`/json/version` 的特定按目标路径上接受 WebSocket 升级。
- **裸 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 握手。这样一来，指向本地 Chrome 的
裸 `ws://` 仍然可以连接，因为 Chrome 只接受针对
`/json/version` 返回的特定目标路径的 WebSocket 升级。
### Browserbase
[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行
无头浏览器，内置 CAPTCHA 求解、隐身模式和住宅代理。
[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行
无头浏览器，并内置 CAPTCHA 求解、隐身模式以及住宅代理。
```json5
{
@ -337,76 +330,75 @@ CDP URL 形态，并会自动选择正确的连接策略：
说明：
- 前往 [注册](https://www.browserbase.com/sign-up)，并从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。
- 请将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此
- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview 控制台](https://www.browserbase.com/overview) 复制你的**API Key**。
- 将 `<BROWSERBASE_API_KEY>` 替换为你真实的 Browserbase API key。
- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此
不需要手动创建会话。
- 免费套餐每月允许一个并发会话和一个浏览器小时。
付费套餐限制请参见 [定价](https://www.browserbase.com/pricing)。
- 完整 API
参考、SDK 指南和集成示例请参见 [Browserbase 文档](https://docs.browserbase.com)。
- 免费套餐每月允许一个并发会话和一个浏览器小时。
付费方案限制请参见 [pricing](https://www.browserbase.com/pricing)。
- 完整 API 参考、SDK 指南和集成示例，请参见 [Browserbase docs](https://docs.browserbase.com)。
## 安全性
关键概念：
- 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行。
- 独立的 loopback 浏览器 HTTP API 仅使用**共享 secret 认证**：
gateway token bearer 认证、`x-openclaw-password`，或带有
已配置 gateway 密码的 HTTP Basic auth。
- Tailscale Serve 身份 headers 和 `gateway.auth.mode: "trusted-proxy"`
- 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**：
Gateway 网关 token Bearer 认证、`x-openclaw-password`，或使用已配置 Gateway 网关密码的 HTTP Basic 认证。
- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"`
**不能**为这个独立的 loopback 浏览器 API 提供认证。
- 如果启用了浏览器控制但未配置共享 secret 认证，OpenClaw
会在启动时自动生成 `gateway.auth.token`，并将其持久化到配置中。
- 当 `gateway.auth.mode` 已经是
`password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。
- 请将 Gateway 网关和任何节点宿主机保持在私有网络中（如 Tailscale）；避免公开暴露。
- 请将远程 CDP URL/token 视为 secrets；优先使用环境变量或 secrets 管理器。
- 如果启用了浏览器控制且未配置共享密钥认证，OpenClaw
会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。
- 如果 `gateway.auth.mode` 已经是
`password`、`none` 或 `trusted-proxy`，OpenClaw **不会**自动生成该 token。
- 请将 Gateway 网关和任何节点主机保持在私有网络上（Tailscale）；避免公开暴露。
- 将远程 CDP URL/token 视为敏感信息；优先使用环境变量或秘密管理器。
远程 CDP 提示：
- 尽可能优先使用加密端点（HTTPS 或 WSS）和短期 token。
- 避免将长期有效 token 直接嵌入到配置文件中。
- 避免将长期 token 直接嵌入配置文件。
## Profiles（多浏览器）
## 配置文件（多浏览器）
OpenClaw 支持多个命名 profile（路由配置）。Profiles 可以是：
OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是：
- **由 OpenClaw 管理**：一个专用的、基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口
- **远程**：一个显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器）
- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome profile
- **openclaw-managed**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口
- **remote**：显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器）
- **existing session**：通过 Chrome DevTools MCP 自动连接你现有的 Chrome 配置文件
默认值：
- 如果缺失，会自动创建 `openclaw` profile。
- `user` profile 是内置的，用于 Chrome MCP existing-session 附加。
- 除 `user` 外，existing-session profiles 都是显式启用的；请使用 `--driver existing-session` 创建它们。
- 如果缺少 `openclaw` 配置文件，会自动创建。
- `user` 配置文件是内置的，用于 Chrome MCP existing-session 连接。
- 除 `user` 外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建。
- 本地 CDP 端口默认从 **18800–18899** 分配。
- 删除一个 profile 时，会将其本地数据目录移到废纸篓。
- 删除配置文件时，会将其本地数据目录移到废纸篓。
所有控制端点都接受 `?profile=<name>`；CLI 使用 `--browser-profile`。
## 通过 Chrome DevTools MCP 使用 existing-session
OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器，附加到正在运行的基于 Chromium 的浏览器 profile。这样可以复用该浏览器 profile 中已经打开的标签页和登录状态。
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 for Developers：在你的浏览器会话中使用 Chrome DevTools MCP](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
内置 profile：
内置配置文件：
- `user`
可选：如果你想使用不同的名称、颜色或浏览器数据目录，也可以创建自己的自定义 existing-session profile。
可选：如果你想使用不同的名称、颜色或浏览器数据目录，可以创建你自己的自定义 existing-session 配置文件。
默认行为：
- 内置的 `user` profile 使用 Chrome MCP 自动连接，目标是
默认本地 Google Chrome profile。
- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是
默认的本地 Google Chrome 配置文件。
对于 Brave、Edge、Chromium 或非默认 Chrome profile，请使用 `userDataDir`：
对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`：
```json5
{
@ -427,7 +419,7 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器，附加到正在
1. 打开该浏览器用于远程调试的 inspect 页面。
2. 启用远程调试。
3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。
3. 保持浏览器运行，并在 OpenClaw 连接时批准连接提示。
常见 inspect 页面：
@ -435,7 +427,7 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器，附加到正在
- Brave：`brave://inspect/#remote-debugging`
- Edge：`edge://inspect/#remote-debugging`
实时附加冒烟测试：
实时连接冒烟测试：
```bash
openclaw browser --browser-profile user start
@ -452,53 +444,52 @@ openclaw browser --browser-profile user snapshot --format ai
- `tabs` 列出你已经打开的浏览器标签页
- `snapshot` 返回所选实时标签页中的 refs
如果附加无效，请检查：
如果连接无效，请检查：
- 目标的基于 Chromium 的浏览器版本是否为 `144+`
- 是否已在该浏览器的 inspect 页面中启用远程调试
- 浏览器是否弹出了附加同意提示，并且你已接受
- `openclaw doctor` 可以迁移旧的基于扩展的浏览器配置，并检查
默认自动连接 profile 所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器侧的远程调试
- 目标的基于 Chromium 的浏览器版本为 `144+`
- 已在该浏览器的 inspect 页面中启用远程调试
- 浏览器已显示连接同意提示，并且你已接受
- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查
默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它不能
替你启用浏览器端的远程调试
智能体使用：
智能体使用方式：
- 当你需要使用用户已登录浏览器状态时，请使用 `profile="user"`。
- 如果你使用的是自定义 existing-session profile，请传入那个显式 profile 名称。
- 只有当用户本人在电脑前、可以批准附加
提示时，才应选择此模式。
- Gateway 网关或节点宿主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect`
- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。
- 如果你使用自定义 existing-session 配置文件，请传入其明确的配置文件名称。
- 仅当用户就在电脑前、可以批准连接提示时才选择此模式。
- Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect`
说明：
- 相比隔离的 `openclaw` profile，这条路径风险更高，因为它可以
在你已登录的浏览器会话中执行操作。
- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。
- OpenClaw 在这里使用官方 Chrome DevTools MCP `--autoConnect` 流程。如果
设置了 `userDataDir`，它会被透传，以定位到对应的用户数据目录。
- Existing-session 可以在所选宿主机上附加，也可以通过已连接的
浏览器节点附加。如果 Chrome 位于其他位置且没有连接浏览器节点，请改用
远程 CDP 或 node host。
- 由于它可以在你已登录的浏览器会话中执行操作，因此这一路径比隔离的 `openclaw` 配置文件风险更高。
- 对于该驱动，OpenClaw 不会启动浏览器；它只会连接。
- OpenClaw 在此处使用官方 Chrome DevTools MCP `--autoConnect` 流程。如果
设置了 `userDataDir`，则会一并传递，用于定位该用户数据目录。
- existing-session 可以连接到所选主机，或通过已连接的
浏览器节点进行连接。如果 Chrome 位于其他位置且未连接浏览器节点，请改用
远程 CDP 或节点主机。
<Accordion title="Existing-session 功能限制">
<Accordion title="existing-session 功能限制">
与受管理的 `openclaw` profile 相比，existing-session 驱动的能力会更受限：
与受管理的 `openclaw` 配置文件相比，existing-session 驱动限制更多：
- **截图** —— 页面截图和 `--ref` 元素截图可用；CSS `--element` 选择器不可用。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面或基于 ref 的元素截图不需要 Playwright。
- **动作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click` 仅支持左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按次调用的超时。`select` 只接受单个值。
- **等待 / 上传 / 对话框** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传 hooks 需要 `ref` 或 `inputRef`，一次仅支持一个文件，不支持 CSS `element`。对话框 hooks 不支持超时覆盖。
- **仅受管理模式支持的功能** —— 批量动作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管理浏览器路径。
- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。
- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要使用快照 ref（不支持 CSS 选择器）。`click` 仅支持鼠标左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用单独设置超时。`select` 接受单个值。
- **Wait / upload / dialog** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子要求使用 `ref` 或 `inputRef`，每次一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。
- **仅限 managed 的功能** —— 批量操作、PDF 导出、下载拦截以及 `responsebody` 仍然需要受管理浏览器路径。
</Accordion>
## 隔离保证
- **专用用户数据目录**：绝不触碰你的个人浏览器 profile。
- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。
- **专用端口**：避免使用 `9222`，以防与开发工作流冲突。
- **确定性的标签页控制**：通过 `targetId` 定位标签页，而不是依赖“最后一个标签页”。
- **可预测的标签页控制**：通过 `targetId` 定位标签页，而不是“最后一个标签页”。
## 浏览器选择
在本地启动时，OpenClaw 会选择第一个可用项：
在本地启动时，OpenClaw 会选择第一个可用的浏览器：
1. Chrome
2. Brave
@ -506,9 +497,9 @@ openclaw browser --browser-profile user snapshot --format ai
4. Chromium
5. Chrome Canary
你可以通过 `browser.executablePath` 覆盖。
你可以通过 `browser.executablePath` 覆盖它。
平台差异：
平台说明：
- macOS：检查 `/Applications` 和 `~/Applications`。
- Linux：查找 `google-chrome`、`brave`、`microsoft-edge`、`chromium` 等。
@ -516,352 +507,33 @@ openclaw browser --browser-profile user snapshot --format ai
## 控制 API（可选）
对于仅限本地的集成，Gateway 网关暴露了一个小型 loopback HTTP API：
- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
- 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
- Snapshot/截图：`GET /snapshot`、`POST /screenshot`
- 动作：`POST /navigate`、`POST /act`
- Hooks：`POST /hooks/file-chooser`、`POST /hooks/dialog`
- 下载：`POST /download`、`POST /wait/download`
- 调试：`GET /console`、`POST /pdf`
- 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight`
- 网络：`POST /response/body`
- 状态：`GET /cookies`、`POST /cookies/set`、`POST /cookies/clear`
- 状态：`GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear`
- 设置：`POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device`
所有端点都接受 `?profile=<name>`。
如果配置了共享 secret Gateway 网关认证，则浏览器 HTTP 路由也需要认证：
- `Authorization: Bearer <gateway token>`
- `x-openclaw-password: <gateway password>` 或带该密码的 HTTP Basic auth
说明：
- 这个独立的 loopback 浏览器 API **不会**消费 trusted-proxy 或
Tailscale Serve 身份 headers。
- 如果 `gateway.auth.mode` 是 `none` 或 `trusted-proxy`，这些 loopback 浏览器
路由也不会继承这些基于身份的模式；请保持它们仅限 loopback。
### `/act` 错误契约
`POST /act` 对于路由级校验和
策略失败使用结构化错误响应：
```json
{ "error": "<message>", "code": "ACT_*" }
```
当前 `code` 值：
- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或无法识别。
- `ACT_INVALID_REQUEST`（HTTP 400）：动作负载标准化或校验失败。
- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不支持的动作类型中使用了 `selector`。
- `ACT_EVALUATE_DISABLED`（HTTP 403）：`evaluate`（或 `wait --fn`）已被配置禁用。
- `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批量 `targetId` 与请求目标冲突。
- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：该动作不支持 existing-session profiles。
其他运行时故障仍可能只返回 `{ "error": "<message>" }`，
而不包含 `code` 字段。
### Playwright 要求
部分功能（navigate/act/AI snapshot/role snapshot、元素截图、
PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回
明确的 501 错误。
在没有 Playwright 的情况下仍可工作的内容：
- ARIA snapshots
- 当存在按标签页划分的 CDP
WebSocket 时，针对受管理 `openclaw` 浏览器的页面截图
- 针对 `existing-session` / Chrome MCP profiles 的页面截图
- 来自 snapshot 输出的 `existing-session` 基于 ref 的截图（`--ref`）
仍然需要 Playwright 的内容：
- `navigate`
- `act`
- AI snapshots / role snapshots
- 基于 CSS 选择器的元素截图（`--element`）
- 完整浏览器 PDF 导出
元素截图也会拒绝 `--full-page`；该路由会返回 `fullPage is
not supported for element screenshots`。
如果你看到 `Playwright is not available in this gateway build`，请修复
内置浏览器插件的运行时依赖，确保已安装 `playwright-core`，
然后重启 gateway。对于打包安装，请运行 `openclaw doctor --fix`。
对于 Docker，还需按下文所示安装 Chromium 浏览器二进制文件。
#### Docker Playwright 安装
如果你的 Gateway 网关运行在 Docker 中，请避免使用 `npx playwright`（会与 npm 覆盖产生冲突）。
请改用内置 CLI：
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
要持久化浏览器下载内容，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如
`/home/node/.cache/ms-playwright`），并确保 `/home/node` 通过
`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化。参见 [Docker](/zh-CN/install/docker)。
## 工作原理（内部）
一个小型的 loopback 控制服务器接收 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级动作（click/type/snapshot/PDF）通过建立在 CDP 之上的 Playwright 完成；当 Playwright 缺失时，只能使用非 Playwright 操作。对智能体来说，始终看到的是一个稳定接口，而本地/远程浏览器和 profile 可以在底层自由切换。
## CLI 快速参考
所有命令都接受 `--browser-profile <name>` 用于指定某个 profile，并接受 `--json` 用于机器可读输出。
<AccordionGroup>
<Accordion title="基础：status、tabs、open/focus/close">
```bash
openclaw browser status
openclaw browser start
openclaw browser stop # also clears emulation on attach-only/remote CDP
openclaw browser tabs
openclaw browser tab # shortcut for current tab
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://example.com
openclaw browser focus abcd1234
openclaw browser close abcd1234
```
</Accordion>
<Accordion title="检查：screenshot、snapshot、console、errors、requests">
```bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12 # or --ref e12
openclaw browser snapshot
openclaw browser snapshot --format aria --limit 200
openclaw browser snapshot --interactive --compact --depth 6
openclaw browser snapshot --efficient
openclaw browser snapshot --labels
openclaw browser snapshot --selector "#main" --interactive
openclaw browser snapshot --frame "iframe#main" --interactive
openclaw browser console --level error
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser pdf
openclaw browser responsebody "**/api" --max-chars 5000
```
</Accordion>
<Accordion title="动作：navigate、click、type、drag、wait、evaluate">
```bash
openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double # or e12 for role refs
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser hover 44
openclaw browser scrollintoview e12
openclaw browser drag 10 11
openclaw browser select 9 OptionA OptionB
openclaw browser download e12 report.pdf
openclaw browser waitfordownload report.pdf
openclaw browser upload /tmp/openclaw/uploads/file.pdf
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
openclaw browser wait --text "Done"
openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
openclaw browser highlight e12
openclaw browser trace start
openclaw browser trace stop
```
</Accordion>
<Accordion title="状态：cookies、storage、offline、headers、geo、device">
```bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear
openclaw browser set offline on
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
openclaw browser set credentials user pass # --clear to remove
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"
```
</Accordion>
</AccordionGroup>
说明：
- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的 click/press 之前先执行它们。
- `click`/`type`/等动作需要来自 `snapshot` 的 `ref`（数字 `12` 或角色引用 `e12`）。动作故意不支持 CSS 选择器。
- 下载、trace 和 upload 路径被限制在 OpenClaw 临时根目录内：`/tmp/openclaw{,/downloads,/uploads}`（回退路径：`${os.tmpdir()}/openclaw/...`）。
- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。
Snapshot 标志速览：
- `--format ai`（装有 Playwright 时的默认值）：带数字引用的 AI snapshot（`aria-ref="<n>"`）。
- `--format aria`：无障碍树，不含引用；仅用于检查。
- `--efficient`（或 `--mode efficient`）：紧凑角色 snapshot 预设。将 `browser.snapshotDefaults.mode: "efficient"` 设为默认值（参见 [Gateway 网关配置](/zh-CN/gateway/configuration-reference#browser)）。
- `--interactive`、`--compact`、`--depth`、`--selector` 会强制使用角色 snapshot，并生成 `ref=e12` 形式的引用。`--frame "<iframe>"` 可将角色 snapshot 限定在某个 iframe 内。
- `--labels` 会附加一张仅限 viewport 的截图，并叠加 `e12` 标签（打印 `MEDIA:<path>`）。
## Snapshots 与 refs
OpenClaw 支持两种 “snapshot” 风格：
- **AI snapshot（数字 refs）**：`openclaw browser snapshot`（默认；`--format ai`）
- 输出：包含数字 refs 的文本 snapshot。
- 动作：`openclaw browser click 12`、`openclaw browser type 23 "hello"`。
- 内部通过 Playwright 的 `aria-ref` 解析 ref。
- **角色 snapshot（如 `e12` 这样的角色 refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
- 输出：带 `[ref=e12]`（以及可选 `[nth=1]`）的基于角色的列表/树。
- 动作：`openclaw browser click e12`、`openclaw browser highlight e12`。
- 内部通过 `getByRole(...)`（以及在重复场景下使用 `nth()`）解析 ref。
- 添加 `--labels` 可附带一张带有叠加 `e12` 标签的 viewport 截图。
Ref 行为：
- Refs **在导航之间并不稳定**；如果动作失败，请重新运行 `snapshot` 并使用新的 ref。
- 如果角色 snapshot 是通过 `--frame` 获取的，则角色 refs 会被限定在该 iframe 中，直到下一次角色 snapshot 生成。
## Wait 增强功能
你可以等待的不只是时间/文本：
- 等待 URL（支持 Playwright 风格 glob）：
- `openclaw browser wait --url "**/dash"`
- 等待加载状态：
- `openclaw browser wait --load networkidle`
- 等待 JS 谓词：
- `openclaw browser wait --fn "window.ready===true"`
- 等待某个选择器变为可见：
- `openclaw browser wait "#main"`
这些条件可以组合：
```bash
openclaw browser wait "#main" \
--url "**/dash" \
--load networkidle \
--fn "window.ready===true" \
--timeout-ms 15000
```
## 调试工作流
当动作失败时（例如 “not visible”、“strict mode violation”、“covered”）：
1. `openclaw browser snapshot --interactive`
2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用角色 refs）
3. 如果仍然失败：运行 `openclaw browser highlight <ref>`，查看 Playwright 实际定位到的目标
4. 如果页面行为异常：
- `openclaw browser errors --clear`
- `openclaw browser requests --filter api --clear`
5. 对于深入调试：录制 trace：
- `openclaw browser trace start`
- 复现问题
- `openclaw browser trace stop`（会打印 `TRACE:<path>`）
## JSON 输出
`--json` 用于脚本和结构化工具链。
示例：
```bash
openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json
```
JSON 中的角色 snapshot 会包含 `refs` 以及一个小型 `stats` 块（lines/chars/refs/interactive），以便工具能够推断负载大小和密度。
## 状态与环境调节项
对于“让网站表现得像 X”之类的工作流，这些选项很有用：
- Cookies：`cookies`、`cookies set`、`cookies clear`
- Storage：`storage local|session get|set|clear`
- Offline：`set offline on|off`
- Headers：`set headers --headers-json '{"X-Debug":"1"}'`（旧版 `set headers --json '{"X-Debug":"1"}'` 仍受支持）
- HTTP Basic auth：`set credentials user pass`（或 `--clear`）
- Geolocation：`set geo <lat> <lon> --origin "https://example.com"`（或 `--clear`）
- Media：`set media dark|light|no-preference|none`
- Timezone / locale：`set timezone ...`、`set locale ...`
- Device / viewport：
- `set device "iPhone 14"`（Playwright 设备预设）
- `set viewport 1280 720`
## 安全与隐私
- `openclaw` 浏览器 profile 可能包含已登录会话；请将其视为敏感对象。
- `browser act kind=evaluate` / `openclaw browser evaluate` 以及 `wait --fn`
会在页面上下文中执行任意 JavaScript。提示注入可能会引导
这一行为。如果你不需要，请通过 `browser.evaluateEnabled=false` 禁用它。
- 关于登录和反机器人注意事项（X/Twitter 等），请参见 [浏览器登录 + X/Twitter 发帖](/zh-CN/tools/browser-login)。
- 请将 Gateway 网关/节点宿主机保持私有（仅限 loopback 或 tailnet）。
- 远程 CDP 端点权限很高；请通过隧道并做好保护。
严格模式示例（默认阻止私有/内部目标）：
```json5
{
browser: {
ssrfPolicy: {
dangerouslyAllowPrivateNetwork: false,
hostnameAllowlist: ["*.example.com", "example.com"],
allowedHostnames: ["localhost"], // optional exact allow
},
},
}
```
为了便于脚本化和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，并提供匹配的 `openclaw browser` CLI（快照、refs、wait 增强功能、JSON 输出、调试工作流）。完整参考请参见
[浏览器控制 API](/zh-CN/tools/browser-control)。
## 故障排除
对于 Linux 特有问题（尤其是 snap Chromium），请参见
有关 Linux 特有问题（尤其是 snap Chromium），请参见
[浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。
对于 WSL2 Gateway 网关 + Windows Chrome 的分离宿主机场景，请参见
[WSL2 + Windows + remote 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 启动失败 vs 导航 SSRF 阻止
### CDP 启动失败 vs 导航 SSRF 拦截
这是两类不同的故障，它们指向不同的代码路径。
这是两类不同的失败，它们指向不同的代码路径。
- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面是健康的。
- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标被策略拒绝了。
- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
- **导航 SSRF 拦截** 表示浏览器控制平面是健康的，但页面导航目标因策略而被拒绝。
常见示例：
- CDP 启动或就绪失败：
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
- 导航 SSRF 阻止：
- `open`、`navigate`、snapshot 或 tab-opening 流程因浏览器/网络策略错误而失败，而 `start` 和 `tabs` 仍然可以工作
- 导航 SSRF 拦截：
- 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败
使用下面这组最小命令来区分两者：
使用以下最小序列来区分两者：
```bash
openclaw browser --browser-profile openclaw start
@ -869,47 +541,47 @@ 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` 以 `not reachable after start` 失败，先排查 CDP 就绪性。
- 如果 `start` 成功但 `tabs` 失败，则控制平面仍不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。
- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则浏览器控制平面已正常运行，失败出在导航策略或目标页面。
- 如果 `start`、`tabs` 和 `open` 全部成功，则基本的受管理浏览器控制路径是健康的。
重要行为细节：
- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会带有一个失败关闭的 SSRF 策略对象。
- 对于本地 loopback 的受管理 `openclaw` profile，CDP 健康检查会有意跳过针对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。
- 导航保护是独立的。`start` 或 `tabs` 的成功结果并不意味着后续的 `open` 或 `navigate` 目标一定被允许。
- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用失败即关闭的 SSRF 策略对象。
- 对于本地 loopback 的受管理 `openclaw` 配置文件，CDP 健康检查会刻意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。
- 导航保护是独立的。`start` 或 `tabs` 成功并不意味着后续的 `open` 或 `navigate` 目标一定被允许。
安全建议：
安全指导：
- **不要** 默认放宽浏览器 SSRF 策略。
- 优先使用像 `hostnameAllowlist` 或 `allowedHostnames` 这样的精细主机例外，而不是开放广泛的私有网络访问。
- 只有在明确受信任、且确实需要访问私有网络浏览器目标并已完成审查的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
- 默认情况下**不要**放宽浏览器 SSRF 策略。
- 优先使用狭义的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛的私有网络访问。
- 仅在明确受信任且已审查、确实需要私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。
## 智能体工具 + 控制方式
## 智能体工具 + 控制工作方式
智能体会获得**一个工具**用于浏览器自动化：
智能体获得**一个工具**用于浏览器自动化：
- `browser` — 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` 会捕获像素（整页或元素）。
- `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。
- `browser act` 使用快照中的 `ref` ID 执行点击/输入/拖动/选择。
- `browser screenshot` 捕获像素（整页或元素）。
- `browser` 接受：
- `profile`，用于选择命名浏览器 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="host"` 或 `target="node"`。
这样可以让智能体保持确定性，并避免脆弱的选择器。
这样可以让智能体保持可预测性，并避免脆弱的选择器。
## 相关内容
- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱环境中的浏览器控制
- [安全](/zh-CN/gateway/security) — 浏览器控制风险与加固
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制
- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固