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-26 00:31:45 +00:00
parent c1137e5140
commit 62ee4e9111
9 changed files with 1100 additions and 1103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
docs/zh-CN/automation/hooks.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 你希望为 `/new`、`/reset`、`/stop` 和智能体生命周期事件提供事件驱动自动化功能
- 你希望为 `/new`、`/reset`、`/stop` 以及智能体生命周期事件提供事件驱动自动化
- 你想要构建、安装或调试钩子
summary: 钩子：用于命令和生命周期事件的事件驱动自动化
title: 钩子
x-i18n:
generated_at: "2026-04-24T17:31:10Z"
generated_at: "2026-04-26T00:28:47Z"
model: gpt-5.4
provider: openai
source_hash: 437b8b8dc37e9ec9c10bbdddc4d63184ccc46e89bc532aea0c5bd176404186f6
source_hash: cf40a64449347ef750b4b0e0a83b80e2e8fdef87d92daa71f028d2bf6a3d3d22
source_path: automation/hooks.md
workflow: 15
---
钩子是在 Gateway 网关内部发生某些事件时运行的小型脚本。你可以从目录中发现它们，并使用 `openclaw hooks` 查看。只有在你启用钩子，或至少配置了一个钩子条目、hook pack、旧版处理器或额外钩子目录后，Gateway 网关才会加载内部钩子。
钩子是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中发现，并可通过 `openclaw hooks` 进行检查。只有在你启用钩子，或至少配置了一个 hook 条目、hook pack、旧版处理器或额外钩子目录后，Gateway 网关才会加载内部钩子。
OpenClaw 中有两种钩子：
- **内部钩子**（本页）：在 Gateway 网关内部运行，当智能体事件触发时执行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。
- **Webhooks**：外部 HTTP 端点，可让其他系统在 OpenClaw 中触发工作。请参阅 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。
- **内部钩子**（本页）：当智能体事件触发时，在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。
- **Webhooks**：外部 HTTP 端点，让其他系统在 OpenClaw 中触发工作。请参阅 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。
钩子也可以内置在插件中。`openclaw hooks list` 会同时显示独立钩子和由插件管理的钩子。
钩子也可以打包在插件中。`openclaw hooks list` 会同时显示独立钩子和由插件管理的钩子。
## 快速开始
@ -42,19 +42,19 @@ openclaw hooks info session-memory
| 事件 | 触发时机 |
| ------------------------ | ------------------------------------------------ |
| `command:new` | 发出 `/new` 命令时 |
| `command:reset` | 发出 `/reset` 命令时 |
| `command:stop` | 发出 `/stop` 命令时 |
| `command` | 任意命令事件（通用监听器） |
| `session:compact:before` | 压缩在汇总历史记录之前 |
| `session:compact:after` | 压缩完成之后 |
| `session:patch` | 修改会话属性时 |
| `agent:bootstrap` | 注入工作区引导文件之前 |
| `gateway:startup` | 渠道启动且钩子已加载之后 |
| `message:received` | 来自任意渠道的入站消息 |
| `message:transcribed` | 音频转录完成之后 |
| `message:preprocessed` | 所有媒体和链接理解完成之后 |
| `message:sent` | 出站消息已送达 |
| `command:new` | 发出 `/new` 命令时 |
| `command:reset` | 发出 `/reset` 命令时 |
| `command:stop` | 发出 `/stop` 命令时 |
| `command` | 任意命令事件（通用监听器） |
| `session:compact:before` | 压缩总结历史记录之前 |
| `session:compact:after` | 压缩完成之后 |
| `session:patch` | 修改会话属性时 |
| `agent:bootstrap` | 注入工作区引导文件之前 |
| `gateway:startup` | 渠道启动并加载钩子之后 |
| `message:received` | 从任意渠道收到入站消息 |
| `message:transcribed` | 音频转录完成之后 |
| `message:preprocessed` | 所有媒体和链接理解完成之后 |
| `message:sent` | 出站消息已送达 |
## 编写钩子
@ -62,23 +62,23 @@ openclaw hooks info session-memory
每个钩子都是一个包含两个文件的目录：
```
```text
my-hook/
├── HOOK.md # 元数据 + 文档
└── handler.ts # 处理器实现
```
### HOOK.md 格式
### `HOOK.md` 格式
```markdown
---
name: my-hook
description: "这个钩子的功能简要说明"
description: "此钩子的功能简短描述"
metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# 我的钩子
# My Hook
详细文档写在这里。
```
@ -87,13 +87,13 @@ metadata:
| 字段 | 说明 |
| ---------- | ---------------------------------------------------- |
| `emoji` | 用于 CLI 显示的表情符号 |
| `events` | 要监听的事件数组 |
| `export` | 要使用的具名导出（默认是 `"default"`） |
| `os` | 所需平台（例如 `["darwin", "linux"]`） |
| `emoji` | CLI 中显示的 emoji |
| `events` | 要监听的事件数组 |
| `export` | 要使用的命名导出（默认为 `"default"`） |
| `os` | 所需平台（例如 `["darwin", "linux"]`） |
| `requires` | 所需的 `bins`、`anyBins`、`env` 或 `config` 路径 |
| `always` | 绕过资格检查（布尔值） |
| `install` | 安装方法 |
| `always` | 绕过资格检查（布尔值） |
| `install` | 安装方式 |
### 处理器实现
@ -113,7 +113,7 @@ const handler = async (event) => {
export default handler;
```
每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 push 以向用户发送消息）以及 `context`（特定于事件的数据）。智能体和工具插件钩子的上下文还可能包含 `trace`，这是一个只读且兼容 W3C 的诊断追踪上下文，插件可将其传递到结构化日志中，以便进行 OTEL 关联。
每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 `push` 以向用户发送消息）以及 `context`（特定于事件的数据）。智能体和工具插件的钩子上下文还可能包含 `trace`，这是一个只读的、兼容 W3C 的诊断追踪上下文，插件可以将其传入结构化日志中，以进行 OTEL 关联。
### 事件上下文要点
@ -129,22 +129,24 @@ export default handler;
**引导事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可变数组）、`context.agentId`。
**会话补丁事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端才能触发补丁事件。
**会话补丁事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端才能触发 patch 事件。
**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 还会增加 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。
**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 会额外包含 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。
`command:stop` 观察的是用户发出 `/stop`；它属于取消/命令生命周期，而不是智能体最终完成的关卡。需要检查自然结束答案并要求智能体再执行一轮的插件，应改用类型化插件钩子 `before_agent_finalize`。请参阅 [Plugin hooks](/zh-CN/plugins/hooks)。
## 钩子发现
系统会按以下目录发现钩子，并按覆盖优先级从低到高排序：
钩子会从以下目录中发现，优先级依次升高：
1. **内置钩子**：随 OpenClaw 一起提供
2. **插件钩子**：内置在已安装插件中的钩子
3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区之间共享）。`hooks.internal.load.extraDirs` 中的额外目录具有相同优先级。
4. **工作区钩子**：`<workspace>/hooks/`（每个智能体独有，默认禁用，需显式启用）
1. **内置钩子**：随 OpenClaw 一起发布
2. **插件钩子**：打包在已安装插件中的钩子
3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区之间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录与其具有相同优先级。
4. **工作区钩子**：`<workspace>/hooks/`（按智能体区分，默认禁用，需显式启用）
工作区钩子可以添加新的钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。
在内部钩子配置完成之前，Gateway 网关会在启动时跳过内部钩子发现。你可以使用 `openclaw hooks enable <name>` 启用一个内置或托管钩子、安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个具名钩子时，Gateway 网关只会加载该钩子的处理器；而 `hooks.internal.enabled=true`、额外钩子目录和旧版处理器则会启用广泛发现。
在内部钩子完成配置之前，Gateway 网关启动时会跳过内部钩子发现。可通过 `openclaw hooks enable <name>` 启用一个内置或托管钩子、安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个命名钩子时，Gateway 网关只会加载该钩子的处理器；而 `hooks.internal.enabled=true`、额外钩子目录和旧版处理器会启用广泛发现。
### Hook packs
@ -154,16 +156,16 @@ Hook pack 是通过 `package.json` 中的 `openclaw.hooks` 导出钩子的 npm
openclaw plugins install <path-or-spec>
```
npm 规格仅支持注册表来源（包名 + 可选的精确版本或 dist-tag）。Git/URL/file 规格和 semver 范围会被拒绝。
npm 规格仅支持 registry（包名 + 可选精确版本或 dist-tag）。Git/URL/file 规格和 semver 范围会被拒绝。
## 内置钩子
| 钩子 | 事件 | 功能 |
| --------------------- | ------------------------------ | ----------------------------------------------------- |
| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的引导文件 |
| command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | 在 gateway 启动时运行 `BOOT.md` |
| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的引导文件 |
| command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | 在网关启动时运行 `BOOT.md` |
启用任意内置钩子：
@ -173,13 +175,13 @@ openclaw hooks enable <hook-name>
<a id="session-memory"></a>
### session-memory 详情
### `session-memory` 详情
提取最近 15 条用户/助手消息，通过 LLM 生成描述性文件名 slug，并保存到 `<workspace>/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。
<a id="bootstrap-extra-files"></a>
### bootstrap-extra-files 配置
### `bootstrap-extra-files` 配置
```json
{
@ -196,28 +198,27 @@ openclaw hooks enable <hook-name>
}
```
路径相对于工作区解析。仅会加载已识别的引导基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。
路径相对于工作区解析。只会加载已识别的引导 basename（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。
<a id="command-logger"></a>
### command-logger 详情
### `command-logger` 详情
将每个斜杠命令记录到 `~/.openclaw/logs/commands.log`。
<a id="boot-md"></a>
### boot-md 详情
### `boot-md` 详情
在 gateway 启动时，从当前活动工作区运行 `BOOT.md`。
在 Gateway 网关启动时，从当前活动工作区运行 `BOOT.md`。
## 插件钩子
插件可以通过 插件 SDK 注册类型化钩子，以实现更深层的集成：
拦截工具调用、修改提示词、控制消息流等。
当你需要 `before_tool_call`、`before_agent_reply`、
`before_install` 或其他进程内生命周期钩子时，请使用插件钩子。
当你需要 `before_tool_call`、`before_agent_reply`、`before_install` 或其他进程内生命周期钩子时，请使用插件钩子。
完整的插件钩子参考，请参阅 [插件钩子](/zh-CN/plugins/hooks)。
完整的插件钩子参考请参阅 [Plugin hooks](/zh-CN/plugins/hooks)。
## 配置
@ -267,7 +268,7 @@ openclaw hooks enable <hook-name>
```
<Note>
旧版 `hooks.internal.handlers` 数组配置格式仍然支持，以保持向后兼容，但新钩子应使用基于发现的系统。
旧版的 `hooks.internal.handlers` 数组配置格式仍受支持，以保持向后兼容，但新钩子应使用基于发现的系统。
</Note>
## CLI 参考
@ -289,9 +290,9 @@ openclaw hooks disable <hook-name>
## 最佳实践
- **保持处理器快速。** 钩子会在命令处理期间运行。对于耗时任务，请使用 `void processInBackground(event)` 以即发即弃方式处理。
- **优雅地处理错误。** 将有风险的操作包裹在 try/catch 中；不要抛出异常，以便其他处理器仍可运行。
- **尽早过滤事件。** 如果事件类型/操作无关，请立即返回。
- **保持处理器快速。** 钩子会在命令处理期间运行。对重型工作使用 `void processInBackground(event)` 方式即发即忘。
- **优雅地处理错误。** 用 try/catch 包裹有风险的操作；不要抛出异常，以便其他处理器继续运行。
- **尽早过滤事件。** 如果事件类型/动作无关，立即返回。
- **使用具体事件键。** 优先使用 `"events": ["command:new"]`，而不是 `"events": ["command"]`，以减少开销。
## 故障排除
@ -307,7 +308,7 @@ ls -la ~/.openclaw/hooks/my-hook/
openclaw hooks list
```
### 钩子不符合条件
### 钩子不符合资格
```bash
openclaw hooks info my-hook
@ -317,13 +318,13 @@ openclaw hooks info my-hook
### 钩子未执行
1. 验证钩子已启用：`openclaw hooks list`
2. 重启你的 gateway 进程，以便重新加载钩子。
3. 检查 gateway 日志：`./scripts/clawlog.sh | grep hook`
1. 确认钩子已启用：`openclaw hooks list`
2. 重启你的网关进程以重新加载钩子。
3. 检查网关日志：`./scripts/clawlog.sh | grep hook`
## 相关内容
- [CLI 参考：hooks](/zh-CN/cli/hooks)
- [Webhooks](/zh-CN/automation/cron-jobs#webhooks)
- [插件钩子](/zh-CN/plugins/hooks) — 进程内插件生命周期钩子
- [Plugin hooks](/zh-CN/plugins/hooks) — 进程内插件生命周期钩子
- [配置](/zh-CN/gateway/configuration-reference#hooks)

83
docs/zh-CN/cli/browser.md
View File

@ -1,22 +1,22 @@
---
read_when:
- 你使用 `openclaw browser`，并希望查看常见任务的示例
- 你想通过节点主机控制在另一台机器上运行的浏览器
- 你想通过节点主机控制另一台机器上运行的浏览器
- 你想通过 Chrome MCP 连接到你本地已登录的 Chrome
summary: '`openclaw browser` 的 CLI 参考（生命周期、配置档案、标签页、操作、状态和调试）'
summary: '`openclaw browser` 的 CLI 参考（生命周期、配置文件、标签页、操作、状态和调试）'
title: 浏览器
x-i18n:
generated_at: "2026-04-25T10:48:39Z"
generated_at: "2026-04-26T00:28:48Z"
model: gpt-5.4
provider: openai
source_hash: 9a2157146e54c77fecafcc5e89dd65244bd7ebecc37f86b45921ccea025188a8
source_hash: 327fea6dc23c58c94dcf67b4ce53a6afbf204fbf64523c3d0bcb7c727594e659
source_path: cli/browser.md
workflow: 15
---
# `openclaw browser`
管理 OpenClaw 的浏览器控制界面，并运行浏览器操作（生命周期、配置档案、标签页、快照、截图、导航、输入、状态模拟和调试）。
管理 OpenClaw 的浏览器控制界面并运行浏览器操作（生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试）。
相关内容：
@ -24,12 +24,12 @@ x-i18n:
## 常用标志
- `--url <gatewayWsUrl>`：Gateway 网关 WebSocket URL（默认来自配置）。
- `--url <gatewayWsUrl>`：Gateway 网关 WebSocket URL（默认为配置中的值）。
- `--token <token>`：Gateway 网关令牌（如果需要）。
- `--timeout <ms>`：请求超时时间（毫秒）。
- `--expect-final`：等待最终的 Gateway 网关响应。
- `--browser-profile <name>`：选择浏览器配置档案（默认来自配置）。
- `--json`：机器可读输出（在支持的情况下）。
- `--browser-profile <name>`：选择浏览器配置文件（默认为配置中的值）。
- `--json`：机器可读输出（在支持的地方）。
## 快速开始（本地）
@ -40,13 +40,13 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
智能体也可以使用同样的就绪检查：`browser({ action: "doctor" })`。
智能体也可以使用 `browser({ action: "doctor" })` 运行相同的就绪检查。
## 快速故障排除
如果 `start` 因 `not reachable after start` 失败，先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面是健康的，失败通常是导航 SSRF 策略导致的。
最小排查步骤：
最小操作序列：
```bash
openclaw browser --browser-profile openclaw doctor
@ -70,10 +70,10 @@ openclaw browser --browser-profile openclaw reset-profile
说明：
- 对于 `attachOnly` 和远程 CDP 配置档案，即使 OpenClaw 并未亲自启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话，并清除临时模拟覆盖项。
- 对于本地托管配置档案，`openclaw browser stop` 会停止已启动的浏览器进程。
- `openclaw browser start --headless` 仅对那一次启动请求生效，并且只在 OpenClaw 启动本地托管浏览器时有效。它不会重写 `browser.headless` 或配置档案配置；如果浏览器已经在运行，它也不会产生任何效果。
- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，本地托管配置档案会自动以无头模式运行，除非 `OPENCLAW_BROWSER_HEADLESS=0`、`browser.headless=false` 或 `browser.profiles.<name>.headless=false` 明确要求显示浏览器界面。
- 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身没有启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖项。
- 对于本地受管配置文件，`openclaw browser stop` 会停止已启动的浏览器进程。
- `openclaw browser start --headless` 仅适用于该次启动请求，且仅在 OpenClaw 启动本地受管浏览器时生效。它不会重写 `browser.headless` 或配置文件配置，并且对于已经运行的浏览器不会产生任何效果。
- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，本地受管配置文件会自动以无头模式运行，除非 `OPENCLAW_BROWSER_HEADLESS=0`、`browser.headless=false` 或 `browser.profiles.<name>.headless=false` 明确请求显示浏览器界面。
## 如果命令不存在
@ -93,13 +93,13 @@ openclaw browser --browser-profile openclaw reset-profile
相关内容：[浏览器工具](/zh-CN/tools/browser#missing-browser-command-or-tool)
## 配置档案
## 配置文件
配置档案是带名称的浏览器路由配置。实际使用中：
配置文件是具名的浏览器路由配置。实际使用中：
- `openclaw`：启动或连接到一个专用的、由 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。
- `user`：通过 Chrome DevTools MCP 控制你当前已登录的 Chrome 会话。
- 自定义 CDP 配置档案：指向本地或远程 CDP 端点。
- `openclaw`：启动或连接到专用的 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。
- `user`：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。
- 自定义 CDP 配置文件：指向本地或远程 CDP 端点。
```bash
openclaw browser profiles
@ -109,7 +109,7 @@ openclaw browser create-profile --name remote --cdp-url https://browser-host.exa
openclaw browser delete-profile --name work
```
使用指定配置档案：
使用指定配置文件：
```bash
openclaw browser --browser-profile work tabs
@ -128,7 +128,8 @@ openclaw browser focus docs
openclaw browser close t1
```
`tabs` 会先返回 `suggestedTargetId`，然后返回稳定的 `tabId`（如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回给 `focus`、`close`、快照和操作命令。你可以通过 `open --label`、`tab new --label` 或 `tab label` 指定标签；标签、标签页 ID、原始目标 ID，以及唯一的目标 ID 前缀都可以接受。
`tabs` 会优先返回 `suggestedTargetId`，然后是稳定的 `tabId`（如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回 `focus`、`close`、快照和操作命令中。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 ID、原始目标 ID，以及唯一的目标 ID 前缀都可被接受。
当 Chromium 在导航或表单提交期间替换底层原始目标时，只要 OpenClaw 能够确认匹配关系，就会将稳定的 `tabId`/标签保留并附加到替换后的标签页。原始目标 ID 仍然是易变的；优先使用 `suggestedTargetId`。
## 快照 / 截图 / 操作
@ -150,12 +151,12 @@ openclaw browser screenshot --labels
说明：
- `--full-page` 仅用于整页截图；不能与 `--ref` 或 `--element` 一起使用。
- `existing-session` / `user` 配置档案支持页面截图，以及使用快照输出中的 `--ref` 进行截图，但不支持基于 CSS `--element` 的截图。
- `--full-page` 仅用于页面截图；不能与 `--ref` 或 `--element` 一起使用。
- `existing-session` / `user` 配置文件支持页面截图和使用快照输出中的 `--ref` 进行截图，但不支持 CSS `--element` 截图。
- `--labels` 会在截图上叠加当前快照引用标记。
- `snapshot --urls` 会将发现的链接目标地址附加到 AI 快照中，以便智能体选择直接导航目标，而不是仅根据链接文本猜测。
- `snapshot --urls` 会将发现的链接目标地址附加到 AI 快照中，以便智能体直接选择导航目标，而不是仅根据链接文本猜测。
导航 / 点击 / 输入（基于 ref 的 UI 自动化）：
导航/点击/输入（基于 ref 的 UI 自动化）：
```bash
openclaw browser navigate https://example.com
@ -172,7 +173,9 @@ openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
```
文件和对话框辅助命令：
当 OpenClaw 能够确认替换后的标签页时，操作响应会在由操作触发的页面替换之后返回当前原始 `targetId`。但脚本仍应在长期工作流中存储并传递 `suggestedTargetId`/标签。
文件 + 对话框辅助命令：
```bash
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
@ -181,11 +184,11 @@ openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
```
托管的 Chrome 配置档案会将普通点击触发的下载保存到 OpenClaw 下载目录（默认是 `/tmp/openclaw/downloads`，或已配置的临时根目录）。当智能体需要等待某个特定文件并返回其路径时，请使用 `waitfordownload` 或 `download`；这些显式等待器会接管下一次下载。
受管 Chrome 配置文件会将普通点击触发的下载保存到 OpenClaw 下载目录（默认是 `/tmp/openclaw/downloads`，或配置的临时根目录）。当智能体需要等待特定文件并返回其路径时，请使用 `waitfordownload` 或 `download`；这些显式等待器会接管下一次下载。
## 状态和存储
视口和模拟：
视口 + 模拟：
```bash
openclaw browser resize 1280 720
@ -200,7 +203,7 @@ openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
```
Cookies 和存储：
Cookies + 存储：
```bash
openclaw browser cookies
@ -224,9 +227,9 @@ openclaw browser trace start
openclaw browser trace stop --out trace.zip
```
## 通过 MCP 连接现有 Chrome
## 通过 MCP 使用现有 Chrome
使用内置的 `user` 配置档案，或创建你自己的 `existing-session` 配置档案：
使用内置的 `user` 配置文件，或创建你自己的 `existing-session` 配置文件：
```bash
openclaw browser --browser-profile user tabs
@ -235,30 +238,30 @@ openclaw browser create-profile --name brave-live --driver existing-session --us
openclaw browser --browser-profile chrome-live tabs
```
这条路径仅适用于主机本机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置档案。
此路径仅限主机本地使用。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。
当前 `existing-session` 的限制：
当前 existing-session 的限制：
- 基于快照的操作使用 ref，而不是 CSS 选择器
- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的 `act` 请求默认设置为 60000 毫秒；但每次调用单独传入的 `timeoutMs` 仍然优先。
- 快照驱动的操作使用 refs，而不是 CSS 选择器
- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的 `act` 请求默认设置为 60000 毫秒；但每次调用的 `timeoutMs` 仍然优先生效。
- `click` 仅支持左键点击
- `type` 不支持 `slowly=true`
- `press` 不支持 `delayMs`
- `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 会拒绝每次调用的超时覆盖
- `select` 仅支持一个值
- 不支持 `wait --load networkidle`
- 文件上传需要 `--ref` / `--input-ref`，不支持 CSS `--element`，并且当前一次只能上传一个文件
- 文件上传需要 `--ref` / `--input-ref`，不支持 CSS `--element`，且当前一次只支持一个文件
- 对话框钩子不支持 `--timeout`
- 截图支持页面截图和 `--ref`，但不支持 CSS `--element`
- `responsebody`、下载拦截、PDF 导出和批量操作仍然需要托管浏览器或原始 CDP 配置档案
- `responsebody`、下载拦截、PDF 导出和批量操作仍然需要受管浏览器或原始 CDP 配置文件
## 远程浏览器控制（节点主机代理）
如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome / Brave / Edge / Chromium 的那台机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。
如果 Gateway 网关运行在与浏览器不同的机器上，请在安装有 Chrome/Brave/Edge/Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。
使用 `gateway.nodes.browser.mode` 控制自动路由，并使用 `gateway.nodes.browser.node` 在连接了多个节点时固定到某个特定节点。
使用 `gateway.nodes.browser.mode` 控制自动路由，并在连接了多个节点时使用 `gateway.nodes.browser.node` 固定到特定节点。
安全和远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全](/zh-CN/gateway/security)
安全性 + 远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全性](/zh-CN/gateway/security)
## 相关内容

130
docs/zh-CN/cli/plugins.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 你想要安装或管理 Gateway 网关插件或兼容的软件包合集
- 你想要调试插件加载失败问题
- 你想要安装或管理 Gateway 网关插件或兼容的捆绑包。
- 你想要调试插件加载失败问题。
summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）'
title: 插件
x-i18n:
generated_at: "2026-04-26T00:16:05Z"
generated_at: "2026-04-26T00:28:48Z"
model: gpt-5.4
provider: openai
source_hash: da98084eb695f0180f928475e31c649a6fc45431b59067688d37417b3727f587
source_hash: 52183e4465154afd32d321c7a7a040c0a3c246e334cb81cded5745abebc78e1b
source_path: cli/plugins.md
workflow: 15
---
# `openclaw plugins`
管理 Gateway 网关插件、hook 软件包，以及兼容的软件包合集。
管理 Gateway 网关插件、hook 包和兼容的捆绑包。
相关内容：
- 插件系统：[插件](/zh-CN/tools/plugin)
- 软件包兼容性：[插件软件包](/zh-CN/plugins/bundles)
- 捆绑包兼容性：[插件捆绑包](/zh-CN/plugins/bundles)
- 插件清单 + schema：[插件清单](/zh-CN/plugins/manifest)
- 安全加固：[安全](/zh-CN/gateway/security)
@ -48,16 +48,16 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
内置插件会随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）；另一些则需要使用 `plugins enable`。
内置插件随 OpenClaw 一起发布。其中一些默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）；另一些则需要运行 `plugins enable`。
原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也需要）。兼容的软件包合集则改用它们自己的 bundle 清单。
原生 OpenClaw 插件必须提供 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也必须提供）。兼容捆绑包则使用它们自己的 bundle manifest。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`），以及检测到的 bundle 能力。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细的 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。
### 安装
```bash
openclaw plugins install <package> # 先查找 ClawHub，然后再查找 npm
openclaw plugins install <package> # 先查 ClawHub，再查 npm
openclaw plugins install clawhub:<package> # 仅使用 ClawHub
openclaw plugins install <package> --force # 覆盖现有安装
openclaw plugins install <package> --pin # 固定版本
@ -68,29 +68,29 @@ openclaw plugins install <plugin> --marketplace <name> # marketplace（显式
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
裸包名会先在 ClawHub 中查找，然后再查找 npm。安全提示：安装插件相当于运行代码。建议优先使用固定版本。
裸包名会先在 ClawHub 中检查，然后再查 npm。安全提示：请将插件安装视为运行代码。优先选择固定版本。
如果你的 `plugins` 配置段由单文件 `$include` 提供支持，`plugins install/update/enable/disable/uninstall` 会将更改写入该被包含文件，并保持 `openclaw.json` 不变。根级 includes、include 数组，以及带有同级 override 的 include 都会以安全关闭方式失败，而不会被扁平化处理。支持的形式请参见 [配置 includes](/zh-CN/gateway/configuration)。
如果你的 `plugins` 部分由单文件 `$include` 提供支持，那么 `plugins install/update/enable/disable/uninstall` 会直接写入该被包含文件，并保持 `openclaw.json` 不变。根级 include、include 数组，以及带同级覆盖项的 include 都会以失败关闭的方式处理，而不会被展平。支持的形状请参见 [配置 include](/zh-CN/gateway/configuration)。
如果配置无效，`plugins install` 通常会以安全关闭方式失败，并提示你先运行 `openclaw doctor --fix`。唯一记录在文档中的例外，是一个较窄的内置插件恢复路径，适用于明确启用了 `openclaw.install.allowInvalidConfigRecovery` 的插件。
如果配置无效，`plugins install` 通常会以失败关闭的方式终止，并提示你先运行 `openclaw doctor --fix`。唯一有文档说明的例外是一个受限的内置插件恢复路径，仅适用于明确选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
`--force` 会复用现有安装目标，并原地覆盖一个已安装的插件或 hook 软件包。当你有意从新的本地路径、归档文件、ClawHub 包或 npm 制品重新安装相同 id 时，请使用它。对于已跟踪 npm 插件的常规升级，建议优先使用 `openclaw plugins update <id-or-npm-spec>`。
`--force` 会复用现有安装目标，并原地覆盖已安装的插件或 hook 包。当你有意从新的本地路径、归档、ClawHub 包或 npm 制品重新安装同一 id 时，请使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
如果你对一个已安装的插件 id 运行 `plugins install`，OpenClaw 会停止并引导你：正常升级请使用 `plugins update <id-or-npm-spec>`，如果你确实想从不同来源覆盖当前安装，则使用 `plugins install <package> --force`。
如果你对一个已经安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并引导你在正常升级时使用 `plugins update <id-or-npm-spec>`，或者在你确实想从不同来源覆盖当前安装时使用 `plugins install <package> --force`。
`--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久保存 marketplace 来源元数据，而不是 npm spec。
`--pin` 仅适用于 npm 安装。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
`--dangerously-force-unsafe-install` 是内置危险代码扫描器出现误报时的紧急开关选项。即使内置扫描器报告 `critical` 级发现，它也允许安装继续进行，但它**不会**绕过插件 `before_install` hook 策略拦截，也**不会**绕过扫描失败。
`--dangerously-force-unsafe-install` 是一个紧急破窗选项，用于处理内置危险代码扫描器的误报。即使内置扫描器报告了 `critical` 级别发现，它也允许安装继续进行，但它**不会**绕过插件 `before_install` hook 策略拦截，也**不会**绕过扫描失败。
这个 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。
`plugins install` 也是暴露 `openclaw.hooks` 于 `package.json` 中的 hook 软件包的安装入口。请使用 `openclaw hooks` 来查看经过筛选的 hook 可见性以及按 hook 启用，而不是用于安装软件包。
`plugins install` 也是暴露 `openclaw.hooks` 于 `package.json` 中的 hook 包的安装入口。请使用 `openclaw hooks` 来查看经过过滤的 hook 可见性和按 hook 启用设置，而不是用于包安装。
Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围都会被拒绝。为安全起见，依赖安装会在项目本地使用 `--ignore-scripts` 运行，即使你的 shell 配置了全局 npm 安装设置也是如此。
npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为了安全，依赖安装会在项目本地以 `--ignore-scripts` 运行，即使你的 shell 配置了全局 npm 安装设置也是如此。
裸 spec 和 `@latest` 会保持在稳定通道上。如果 npm 将它们中的任意一种解析为预发布版本，OpenClaw 会停止，并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或像 `@1.2.3-beta.4` 这样的精确预发布版本。
裸 spec 和 `@latest` 会保持在稳定轨道上。如果 npm 将其中任一项解析为预发布版本，OpenClaw 会停止，并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或像 `@1.2.3-beta.4` 这样的精确预发布版本。
如果一个裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。要安装同名的 npm 包，请使用显式作用域 spec（例如 `@scope/diffs`）。
如果裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名的 npm 包，请使用显式的带作用域 spec（例如 `@scope/diffs`）。
支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。
@ -103,13 +103,13 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClaw 现在也会优先为裸 npm-safe 插件 spec 使用 ClawHub。只有在 ClawHub 没有该包或该版本时，才会回退到 npm：
现在，对于符合 npm 安全规范的裸插件 spec，OpenClaw 也会优先使用 ClawHub。只有当 ClawHub 没有该包或版本时，它才会回退到 npm：
```bash
openclaw plugins install openclaw-codex-app-server
```
OpenClaw 会从 ClawHub 下载软件包归档，检查所声明的插件 API / 最低 Gateway 网关兼容性，然后通过常规归档路径安装它。已记录的安装会保留其 ClawHub 来源元数据，以便后续更新。
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低网关兼容性，然后通过常规归档路径完成安装。记录下来的安装会保留其 ClawHub 来源元数据，以便后续更新。
当 marketplace 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，可使用 `plugin@marketplace` 简写：
@ -118,7 +118,7 @@ openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
如果你想显式传递 marketplace 来源，请使用 `--marketplace`：
当你想显式传递 marketplace 来源时，请使用 `--marketplace`：
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -129,22 +129,22 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
Marketplace 来源可以是：
- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称
- `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称
- 本地 marketplace 根目录或 `marketplace.json` 路径
- GitHub 仓库简写，例如 `owner/repo`
- GitHub 仓库 URL，例如 `https://github.com/owner/repo`
- 例如 `owner/repo` 这样的 GitHub 仓库简写
- 例如 `https://github.com/owner/repo` 这样的 GitHub 仓库 URL
- git URL
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保持在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件来源。
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆后的 marketplace 仓库内部。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程 manifest 中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径类插件来源。
对于本地路径和归档文件，OpenClaw 会自动检测：
对于本地路径和归档，OpenClaw 会自动检测：
- 原生 OpenClaw 插件（`openclaw.plugin.json`）
- Codex 兼容的软件包合集（`.codex-plugin/plugin.json`）
- Claude 兼容的软件包合集（`.claude-plugin/plugin.json` 或默认 Claude 组件布局）
- Cursor 兼容的软件包合集（`.cursor-plugin/plugin.json`）
- Codex 兼容捆绑包（`.codex-plugin/plugin.json`）
- Claude 兼容捆绑包（`.claude-plugin/plugin.json` 或默认的 Claude 组件布局）
- Cursor 兼容捆绑包（`.cursor-plugin/plugin.json`）
兼容的软件包合集会安装到常规插件根目录中，并参与相同的 list/info/enable/disable 流程。目前，已支持 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 由清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的 bundle 能力会在诊断/info 中显示，但尚未接入运行时执行。
兼容捆绑包会安装到常规插件根目录中，并参与同样的 list/info/enable/disable 流程。当前已支持 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的 bundle 能力会显示在诊断/info 中，但尚未接入运行时执行。
### 列表
@ -155,15 +155,15 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
使用 `--enabled` 仅显示已启用插件。使用 `--verbose` 可从表格视图切换为按插件显示的详细行，其中包含 source/origin/version/activation 元数据。使用 `--json` 可获取适合机器读取的清单以及注册表诊断信息。
使用 `--enabled` 仅显示已启用插件。使用 `--verbose` 可从表格视图切换到按插件显示详情行，其中包含 source/origin/version/activation 元数据。使用 `--json` 可获取适用于机器读取的清单以及注册表诊断信息。
`plugins list` 会先读取持久化的本地插件注册表；如果注册表缺失或无效，则回退为仅基于清单推导出的结果。它适用于检查插件是否已安装、已启用，以及对冷启动规划是否可见，但它并不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，请重启为该渠道提供服务的 Gateway 网关，然后再期待新的 `register(api)` 代码或 hook 开始运行。对于远程/容器部署，请确认你重启的是真正的 `openclaw gateway run` 子进程，而不只是某个包装进程。
`plugins list` 会先读取持久化的本地插件注册表；如果注册表缺失或无效，则回退为仅基于 manifest 推导的结果。它适合用于检查某个插件是否已安装、已启用，以及在冷启动规划中是否可见，但它不是针对已运行 Gateway 网关进程的实时运行时探针。修改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，在期待新的 `register(api)` 代码或 hook 生效之前，请重启为该渠道提供服务的 Gateway 网关。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅仅是包装进程。
对于运行时 hook 调试：
- `openclaw plugins inspect <id> --json` 会显示已注册的 hook 以及来自模块加载检查过程的诊断信息
- `openclaw gateway status --deep --require-rpc` 会确认可达的 Gateway 网关、服务/进程提示、配置路径以及 RPC 健康状态
- 非内置的会话 hook（`llm_input`、`llm_output`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`
- `openclaw plugins inspect <id> --json` 会显示已注册的 hook，以及来自模块加载检查过程的诊断信息
- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态
- 非内置的对话 hook（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）要求设置 `plugins.entries.<id>.hooks.allowConversationAccess=true`
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
@ -171,13 +171,13 @@ openclaw plugins list --json
openclaw plugins install -l ./my-plugin
```
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制覆盖一个受管安装目标。
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到受管安装目标。
在 npm 安装中使用 `--pin`，可以把解析后的精确 spec（`name@version`）保存到受管插件索引中，同时保持默认行为不固定版本。
在 npm 安装时使用 `--pin`，可以将解析后的精确 spec（`name@version`）保存到受管插件索引中，同时保持默认行为为未固定版本。
### 插件索引
插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其中顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组则是基于清单派生的冷注册表缓存。该文件包含“请勿手动编辑”的警告，并被 `openclaw plugins update`、卸载、诊断以及冷插件注册表使用。
插件安装元数据是机器管理状态，不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其中顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件 manifest 的记录。`plugins` 数组是基于 manifest 推导的冷注册表缓存。该文件包含“请勿手动编辑”警告，并被 `openclaw plugins update`、卸载、诊断以及冷插件注册表使用。
### 卸载
@ -187,10 +187,11 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件 allowlist，以及关联的 `plugins.load.paths` 条目中移除插件记录（如适用）。
对于活跃的内存插件，memory 插槽会重置为 `memory-core`。
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件 allowlist，以及在适用情况下的已链接 `plugins.load.paths` 条目中移除插件记录。
对于活动的内存插件，memory 槽位会重置为 `memory-core`。
默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 `--keep-files` 可保留磁盘上的文件。
默认情况下，卸载还会移除活动 state-dir 插件根目录下的插件安装目录。使用
`--keep-files` 可保留磁盘上的文件。
`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。
@ -204,19 +205,19 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
更新会应用于受管插件索引中已跟踪的插件安装，以及 `hooks.internal.installs` 中已跟踪的 hook 软件包安装。
更新适用于受管插件索引中已跟踪的插件安装，以及 `hooks.internal.installs` 中已跟踪的 hook 包安装。
当你传入一个插件 id 时，OpenClaw 会复用该插件已记录的安装 spec。这意味着此前存储的 dist-tag（如 `@beta`）和精确固定版本，会在后续运行 `update <id>` 时继续使用。
当你传入插件 id 时，OpenClaw 会复用该插件记录下来的安装 spec。这意味着之前保存的 dist-tag（例如 `@beta`）和精确固定版本，在之后运行 `update <id>` 时会继续使用。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新该已安装插件，并记录新的 npm spec，以供后续基于 id 的更新使用。
对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新该已安装插件，并为今后基于 id 的更新记录新的 npm spec。
不带版本或标签地传入 npm 包名，也会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你想让它回到 registry 的默认发布线时，请使用这种方式。
仅传入 npm 包名而不带版本或标签，也会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你希望将它切回 registry 的默认发布线时，可使用这种方式。
在执行实际的 npm 更新前，OpenClaw 会将已安装的软件包版本与 npm registry 元数据进行比较。如果已安装版本和已记录制品标识已经与解析后的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。
在执行实时 npm 更新之前，OpenClaw 会将已安装的包版本与 npm registry 元数据进行比对。如果已安装版本和已记录的制品身份已经与解析出的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。
当存在已存储的完整性哈希，而获取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式的 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会以安全关闭方式失败，除非调用方提供显式的继续策略。
当存在已存储的完整性哈希，而获取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续之前请求确认。非交互式更新辅助工具会以失败关闭的方式终止，除非调用方提供显式的继续策略。
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新过程中内置危险代码扫描误报时的紧急覆盖选项。它仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截，并且它只适用于插件更新，不适用于 hook 软件包更新。
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为在插件更新期间应对内置危险代码扫描误报的紧急破窗覆盖项。它仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截，而且它仅适用于插件更新，不适用于 hook 包更新。
### 检查
@ -225,20 +226,20 @@ openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
针对单个插件的深度自省。显示身份信息、加载状态、来源、已注册能力、hook、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。
针对单个插件的深度检查。会显示身份、加载状态、来源、已注册能力、hook、工具、命令、服务、网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。
每个插件都会根据它在运行时实际注册的内容进行分类：
每个插件都会根据其在运行时实际注册的内容进行分类：
- **plain-capability** — 单一能力类型（例如仅 provider 的插件）
- **plain-capability** — 单一能力类型（例如仅提供商插件）
- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像）
- **hook-only** — 仅有 hook，没有能力或其他表面
- **hook-only** — 只有 hook，没有能力或表面
- **non-capability** — 有工具/命令/服务，但没有能力
关于能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
有关能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
`--json` 标志会输出适合脚本和审计使用的机器可读报告。
`inspect --all` 会渲染一个面向整组插件的表格，其中包含 shape、capability kinds、兼容性提示、bundle 能力，以及 hook 摘要列。
`inspect --all` 会渲染整个插件集范围的表格，其中包含形态、能力种类、兼容性提示、bundle 能力和 hook 摘要列。
`info` 是 `inspect` 的别名。
@ -248,9 +249,9 @@ openclaw plugins inspect <id> --json
openclaw plugins doctor
```
`doctor` 会报告插件加载错误、清单/发现诊断信息，以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。
`doctor` 会报告插件加载错误、manifest/设备发现 诊断信息以及兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`。
对于缺少 `register`/`activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
对于缺少 `register`/`activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。
### 注册表
@ -260,11 +261,12 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
本地插件注册表是 OpenClaw 针对已安装插件身份、启用状态、来源元数据和贡献归属所持久化的冷读模型。正常启动、provider 归属查询、渠道设置分类，以及插件清单，都可以在不导入插件运行时模块的情况下读取它。
本地插件注册表是 OpenClaw 持久化的冷读模型，用于存储已安装插件的身份、启用状态、来源元数据和贡献归属关系。
正常启动、提供商所有者查找、渠道设置分类以及插件清单都可以在不导入插件运行时模块的情况下读取它。
使用 `plugins registry` 可检查持久化注册表是否存在、是否最新、是否已过期。使用 `--refresh` 可基于持久化插件索引、配置策略以及清单/软件包元数据重建它。这是修复路径，不是运行时激活路径。
使用 `plugins registry` 可检查持久化注册表是否存在、是否为最新或是否已过时。使用 `--refresh` 可根据持久化插件索引、配置策略以及 manifest/package 元数据重建它。这是一条修复路径，而不是运行时激活路径。
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急兼容开关，用于应对注册表读取失败。更推荐使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；这个环境变量回退仅用于迁移发布期间的紧急启动恢复。
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急破窗兼容开关，用于处理注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退仅用于迁移推出期间的紧急启动恢复。
### Marketplace
@ -273,9 +275,9 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace 清单和插件条目。
Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、如 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及已解析的 marketplace manifest 和插件条目。
## 相关
## 相关内容
- [CLI 参考](/zh-CN/cli)
- [构建插件](/zh-CN/plugins/building-plugins)

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

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

416
docs/zh-CN/plugins/codex-harness.md
View File

@ -1,105 +1,115 @@
---
read_when:
- 你想使用内置的 Codex 应用服务器编排器
- 你想使用内置的 Codex app-server harness
- 你需要 Codex harness 配置示例
- 你希望仅使用 Codex 的部署在无法使用时直接失败，而不是回退到 Pi
summary: 通过内置的 Codex 应用服务器编排器运行 OpenClaw 嵌入式智能体回合
- 你希望仅使用 Codex 的部署在无法使用时直接失败，而不是回退到 PI
summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次
title: Codex harness
x-i18n:
generated_at: "2026-04-26T00:04:57Z"
generated_at: "2026-04-26T00:28:51Z"
model: gpt-5.4
provider: openai
source_hash: ccd3616a944f83eda679e030a65f9febbe8c4f69100675ead8fa5d2c72142ce3
source_hash: 8d7bf0c337d5e2a9a5af43e7487859205b5f1ed297f78143d937c530bbbbb71a
source_path: plugins/codex-harness.md
workflow: 15
---
内置的 `codex` 插件让 OpenClaw 通过 Codex 应用服务器而不是内置的 Pi 编排器运行嵌入式智能体回合。
内置的 `codex` 插件让 OpenClaw 能够通过 Codex app-server，而不是内置的 PI harness，来运行嵌入式智能体轮次。
当你希望由 Codex 接管底层智能体会话时，请使用它：模型发现、原生线程恢复、原生压缩，以及应用服务器执行。
OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传输，以及可见的转录镜像。
当你希望 Codex 接管底层智能体会话时，请使用此方式：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。
OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。
如果你正在了解整体结构，请先从 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简短版本是：
如果你正在了解整体结构，请先阅读
[Agent Runtimes](/zh-CN/concepts/agent-runtimes)。简要来说：
`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、
Discord、Slack 或其他渠道仍然是通信界面。
同一个插件还负责原生 `/codex` 聊天控制命令界面。如果
插件已启用，并且用户要求从聊天中绑定、恢复、引导、停止或检查
Codex 线程，智能体应优先使用 `/codex ...` 而不是 ACP。当用户明确要求 ACP/acpx，或正在测试 ACP 的 Codex 适配器时，ACP 仍然是显式回退方案。
同一个插件也负责原生 `/codex` 聊天控制命令界面。如果
插件已启用，并且用户要求在聊天中绑定、恢复、引导、停止或检查
Codex 线程，智能体应优先使用 `/codex ...`，而不是 ACP。当用户明确要求使用 ACP/acpx，或正在测试 ACP
Codex 适配器时，ACP 仍然是显式的回退方案。
原生 Codex 回合将 OpenClaw 插件钩子保留为公共兼容层。
这些是进程内的 OpenClaw 钩子，而不是 Codex `hooks.json` 命令钩子：
原生 Codex 轮次会将 OpenClaw 插件钩子作为公共兼容层保留。
这些是进程内的 OpenClaw 钩子，不是 Codex `hooks.json` 命令钩子：
- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `before_tool_call`, `after_tool_call`
- `before_message_write`，用于镜像转录记录
- `before_agent_finalize`，通过 Codex `Stop` 中继
- `agent_end`
插件还可以注册与运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、结果返回给 Codex 之前，重写 OpenClaw 的动态工具结果。这与公共
`tool_result_persist` 插件钩子不同，后者用于转换由 OpenClaw 管理的转录工具结果写入。
插件还可以注册与运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、并在结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公共
`tool_result_persist` 插件钩子不同，后者用于转换由 OpenClaw 持有的转录工具结果写入。
关于插件钩子语义本身，请参见 [Plugin hooks](/zh-CN/plugins/hooks)
有关插件钩子语义本身，请参见 [Plugin hooks](/zh-CN/plugins/hooks)
和 [Plugin guard behavior](/zh-CN/tools/plugin)。
该编排器默认关闭。新配置应保持 OpenAI 模型引用的规范形式为 `openai/gpt-*`，并在需要原生应用服务器执行时，显式强制指定
该 harness 默认关闭。新配置应保持 OpenAI 模型引用的规范形式为
`openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置
`embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
旧版 `codex/*` 模型引用仍会自动选择该编排器以保持兼容性，但由运行时支持的旧版提供商前缀不会显示为普通模型/提供商选项。
旧版 `codex/*` 模型引用仍会为兼容性自动选择该 harness，但由运行时支持的旧版 provider 前缀不会显示为普通的模型/提供商选项。
## 选择正确的模型前缀
OpenAI 系列路由依赖特定前缀。当你希望通过 Pi 使用
Codex OAuth 时，使用 `openai-codex/*`；当你希望直接访问 OpenAI API，或在强制使用原生 Codex 应用服务器编排器时，使用 `openai/*`：
OpenAI 系列路由对前缀非常敏感。当你希望通过 PI 使用
Codex OAuth 时，请使用 `openai-codex/*`；当你希望直接使用 OpenAI API，或在强制使用原生 Codex app-server harness 时，请使用 `openai/*`：
| 模型引用 | 运行时路径 | 使用场景 |
| ----------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | 通过 OpenClaw/Pi 管线的 OpenAI provider | 你希望通过 `OPENAI_API_KEY` 使用当前直接 OpenAI Platform API 访问。 |
| `openai-codex/gpt-5.5` | 通过 OpenClaw/Pi 的 OpenAI Codex OAuth | 你希望使用默认 Pi 运行器进行 ChatGPT/Codex 订阅认证。 |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex 应用服务器编排器 | 你希望嵌入式智能体回合使用原生 Codex 应用服务器执行。 |
| Model ref | Runtime path | Use when |
| ----------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | 通过 OpenClaw/PI 管线的 OpenAI provider | 你希望使用带有 `OPENAI_API_KEY` 的当前直接 OpenAI Platform API 访问。 |
| `openai-codex/gpt-5.5` | 通过 OpenClaw/PI 的 OpenAI Codex OAuth | 你希望在默认 PI 运行器中使用 ChatGPT/Codex 订阅认证。 |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。 |
GPT-5.5 目前在 OpenClaw 中仅支持订阅/OAuth。对于 Pi OAuth，请使用
`openai-codex/gpt-5.5`；对于 Codex 应用服务器编排器，请使用 `openai/gpt-5.5` 搭配 Codex
应用服务器编排器。对于 `openai/gpt-5.5` 的直接 API key 访问，将在
OpenAI 在公共 API 中启用 GPT-5.5 后获得支持。
在 OpenClaw 中，GPT-5.5 当前仅支持订阅/OAuth。
对于 PI OAuth，请使用 `openai-codex/gpt-5.5`；对于 Codex
app-server harness，请使用 `openai/gpt-5.5`。一旦 OpenAI 在公开 API 上启用 GPT-5.5，
就会支持通过 API key 直接访问 `openai/gpt-5.5`。
旧版 `codex/gpt-*` 引用仍然接受，作为兼容别名。Doctor
兼容性迁移会将旧版主运行时引用重写为规范模型引用，并将运行时策略单独记录；而仅作为回退使用的旧版引用则保持不变，因为运行时是为整个智能体容器配置的。
新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生
应用服务器编排器配置应使用 `openai/gpt-*`，并配合
旧版 `codex/gpt-*` 引用仍然被接受为兼容别名。Doctor
兼容性迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅用于回退的旧版引用则保持不变，因为运行时是为整个智能体容器配置的。
新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生
app-server harness 配置应使用 `openai/gpt-*`，再加上
`embeddedHarness.runtime: "codex"`。
`agents.defaults.imageModel` 遵循相同的前缀拆分。如果图像理解应通过 OpenAI
Codex OAuth 提供商路径运行，请使用 `openai-codex/gpt-*`。如果图像理解应通过受限的 Codex 应用服务器回合运行，请使用 `codex/gpt-*`。Codex 应用服务器模型必须声明支持图像输入；仅文本的 Codex 模型会在媒体回合开始前失败。
`agents.defaults.imageModel` 也遵循相同的前缀划分。当图像理解应通过
OpenAI Codex OAuth provider 路径运行时，请使用
`openai-codex/gpt-*`。当图像理解应通过受限的 Codex app-server 轮次运行时，请使用
`codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；仅文本的 Codex 模型会在媒体轮次开始前失败。
使用 `/status` 来确认当前会话的实际编排器。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含所选编排器 id、选择原因、运行时/回退策略，以及在 `auto` 模式下，每个插件候选项的支持结果。
使用 `/status` 来确认当前会话的实际 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 gateway 的结构化 `agent harness selected` 记录。它包含已选择的 harness id、选择原因、运行时/回退策略，以及在
`auto` 模式下每个插件候选项的支持结果。
编排器选择不是实时会话控制。当嵌入式回合运行时，
OpenClaw 会在该会话上记录所选编排器 id，并在同一会话 id 的后续回合中继续使用它。当你希望未来的会话改用其他编排器时，请修改 `embeddedHarness` 配置或
`OPENCLAW_AGENT_RUNTIME`；在将现有对话从 Pi 切换到 Codex 之前，请使用 `/new` 或 `/reset` 启动新会话。这样可以避免通过两个不兼容的原生会话系统重放同一份转录。
Harness 选择不是实时会话控制。当嵌入式轮次运行时，
OpenClaw 会在该会话上记录所选的 harness id，并在同一个会话 id 的后续轮次中继续使用它。当你希望未来的会话使用其他 harness 时，请更改 `embeddedHarness` 配置或
`OPENCLAW_AGENT_RUNTIME`；在将现有对话在 PI 和 Codex 之间切换之前，请使用 `/new` 或 `/reset` 启动一个新的会话。
这样可以避免将同一份转录回放到两个互不兼容的原生会话系统中。
在引入编排器固定之前创建的旧会话，一旦拥有转录历史，就会被视为固定到 Pi。更改配置后，请使用 `/new` 或 `/reset` 将该对话切换到 Codex。
在 harness 固定机制引入之前创建的旧会话，只要已有转录历史，就会被视为固定到 PI。更改配置后，如需让该对话切换到
Codex，请使用 `/new` 或 `/reset`。
`/status` 会显示实际模型运行时。默认的 Pi 编排器显示为
`Runtime: OpenClaw Pi Default`，而 Codex 应用服务器编排器显示为
`/status` 会显示实际的模型运行时。默认的 PI harness 会显示为
`Runtime: OpenClaw Pi Default`，而 Codex app-server harness 会显示为
`Runtime: OpenAI Codex`。
## 要求
- OpenClaw，并且可使用内置的 `codex` 插件。
- Codex 应用服务器 `0.125.0` 或更高版本。内置插件默认会管理一个兼容的
Codex 应用服务器二进制文件，因此 `PATH` 上本地的 `codex` 命令不会影响正常的编排器启动。
- 应用服务器进程可用的 Codex 认证信息。
- OpenClaw，且内置的 `codex` 插件可用。
- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理一个兼容的
Codex app-server 二进制文件，因此本地 `PATH` 中的 `codex` 命令不会影响正常的 harness 启动。
- app-server 进程可用的 Codex 认证。
该插件会阻止较旧或未带版本信息的应用服务器握手。
这样可确保 OpenClaw 仅运行在它已测试过的协议接口上。
该插件会阻止较旧或未带版本信息的 app-server 握手。
这样可以确保 OpenClaw 始终运行在它已测试过的协议接口上。
对于 live 和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，再加上可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和
`~/.codex/config.toml`。请使用与你本地 Codex 应用服务器相同的认证材料。
对于 live 和 Docker smoke 测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和
`~/.codex/config.toml`。请使用与你本地 Codex app-server
相同的认证材料。
## 最小配置
使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` 编排器：
使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` harness：
```json5
{
@ -121,7 +131,7 @@ OpenClaw 会在该会话上记录所选编排器 id，并在同一会话 id 的
}
```
如果你的配置使用 `plugins.allow`，也要在其中包含 `codex`：
如果你的配置使用了 `plugins.allow`，也请将 `codex` 包含进去：
```json5
{
@ -137,23 +147,24 @@ OpenClaw 会在该会话上记录所选编排器 id，并在同一会话 id 的
```
将 `agents.defaults.model` 或某个智能体模型设置为
`codex/<model>` 的旧配置，仍会自动启用内置 `codex` 插件。新配置应优先使用
`openai/<model>`，并配合上面显式的 `embeddedHarness` 条目。
`codex/<model>` 的旧配置，仍会自动启用内置的 `codex` 插件。新配置应优先使用
`openai/<model>`，并加上上面的显式 `embeddedHarness` 条目。
## 在其他模型旁边添加 Codex
## 将 Codex 与其他模型一起使用
如果同一个智能体需要在 Codex 和非 Codex 提供商模型之间自由切换，就不要全局设置 `runtime: "codex"`。
强制运行时会应用于该智能体或会话的每一个嵌入式回合。如果你在强制该运行时时选择了 Anthropic 模型，OpenClaw 仍会尝试 Codex 编排器，并以失败结束，而不会悄悄通过 Pi 路由该回合。
如果同一个智能体需要在 Codex 和非 Codex provider 模型之间自由切换，请不要全局设置
`runtime: "codex"`。
强制运行时会应用到该智能体或会话的每一次嵌入式轮次。如果你在强制该运行时的情况下选择了 Anthropic 模型，
OpenClaw 仍会尝试使用 Codex harness，并以关闭式失败，而不是悄悄通过 PI 路由该轮次。
请改用以下结构之一：
请改用以下任一种方式：
- 将 Codex 放到专用智能体上，并设置 `embeddedHarness.runtime: "codex"`。
- 将默认智能体保持在 `runtime: "auto"` 和 Pi 回退，以用于正常的混合提供商用法。
- 仅为兼容性使用旧版 `codex/*` 引用。新配置应优先使用
`openai/*`，并配合显式的 Codex 运行时策略。
- 将 Codex 放到一个专用智能体上，并设置 `embeddedHarness.runtime: "codex"`。
- 将默认智能体保持在 `runtime: "auto"`，并为常规混合 provider 使用保留 PI 回退。
- 仅将旧版 `codex/*` 引用用于兼容性。新配置应优先使用
`openai/*`，并显式设置 Codex 运行时策略。
例如，下面的配置会让默认智能体保持正常自动选择，
并添加一个单独的 Codex 智能体：
例如，下面的配置会让默认智能体保持普通的自动选择，同时新增一个独立的 Codex 智能体：
```json5
{
@ -190,18 +201,18 @@ OpenClaw 会在该会话上记录所选编排器 id，并在同一会话 id 的
}
```
在这种结构下：
在这种配置下：
- 默认的 `main` 智能体使用正常的提供商路径和 Pi 兼容性回退。
- `codex` 智能体使用 Codex 应用服务器编排器。
- 如果 `codex` 智能体缺少 Codex 或不受支持，该回合会失败，
而不是悄悄使用 Pi。
- 默认的 `main` 智能体使用普通 provider 路径和 PI 兼容性回退。
- `codex` 智能体使用 Codex app-server harness。
- 如果 `codex` 智能体缺少 Codex 或 Codex 不受支持，该轮次会失败，
而不是悄悄改用 PI。
## 仅使用 Codex 的部署
当你需要证明每个嵌入式智能体回合
都使用 Codex 时，请强制使用 Codex 编排器。显式插件运行时默认不使用 Pi 回退，因此
`fallback: "none"` 是可选的，但通常可作为文档说明使用：
当你需要证明每一个嵌入式智能体轮次都使用 Codex 时，请强制使用
Codex harness。显式插件运行时默认不使用 PI 回退，因此
`fallback: "none"` 是可选的，但通常作为文档说明很有用：
```json5
{
@ -217,19 +228,20 @@ OpenClaw 会在该会话上记录所选编排器 id，并在同一会话 id 的
}
```
环境覆盖：
环境变量覆盖：
```bash
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```
在强制使用 Codex 的情况下，如果 Codex 插件被禁用、
应用服务器版本过旧，或者应用服务器无法启动，OpenClaw 会提前失败。仅当你确实希望由 Pi 处理缺失的编排器选择时，才设置
在强制使用 Codex 时，如果 Codex 插件被禁用、app-server 版本过旧，或
app-server 无法启动，OpenClaw 会提前失败。只有当你明确希望在缺少 harness 选择时由 PI 处理时，才设置
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
## 按智能体使用 Codex
## 按智能体启用 Codex
你可以让一个智能体仅使用 Codex，同时让默认智能体保持正常的自动选择：
你可以让某一个智能体仅使用 Codex，而默认智能体保持正常的
自动选择：
```json5
{
@ -260,13 +272,14 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
}
```
使用普通会话命令切换智能体和模型。`/new` 会创建一个新的
OpenClaw 会话，而 Codex 编排器会根据需要创建或恢复其侧车应用服务器线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一回合再次根据当前配置解析编排器。
使用正常的会话命令来切换智能体和模型。`/new` 会创建一个新的
OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar app-server
线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮再次根据当前配置解析 harness。
## 模型发现
默认情况下，Codex 插件会向应用服务器查询可用模型。如果
发现失败或超时，它会使用内置的回退目录，包含：
默认情况下，Codex 插件会向 app-server 查询可用模型。如果
发现失败或超时，它会使用内置的回退目录，其中包括：
- GPT-5.5
- GPT-5.4 mini
@ -292,8 +305,7 @@ OpenClaw 会话，而 Codex 编排器会根据需要创建或恢复其侧车应
}
```
如果你希望启动时避免探测 Codex 并固定使用回退目录，
请禁用发现：
如果你希望启动时避免探测 Codex，并固定使用回退目录，请禁用发现：
```json5
{
@ -312,22 +324,21 @@ OpenClaw 会话，而 Codex 编排器会根据需要创建或恢复其侧车应
}
```
## 应用服务器连接和策略
## App-server 连接与策略
默认情况下，插件会在本地启动由 OpenClaw 管理的 Codex 二进制文件，命令为：
默认情况下，插件会在本地启动由 OpenClaw 管理的 Codex 二进制文件，命令如下：
```bash
codex app-server --listen stdio://
```
该受管二进制文件被声明为内置插件运行时依赖，并与其余
`codex` 插件依赖一起分阶段提供。这样可以让应用服务器版本与内置插件保持绑定，而不是依赖本地碰巧安装的某个独立 Codex CLI。
只有在你明确希望运行其他可执行文件时，才设置 `appServer.command`。
该受管二进制文件被声明为内置插件运行时依赖，并与 `codex` 插件的其他依赖一起进行准备。
这样可以让 app-server 版本与内置插件绑定，而不是取决于本地单独安装的是哪个 Codex CLI。
只有当你明确希望运行不同的可执行文件时，才设置 `appServer.command`。
默认情况下，OpenClaw 以 YOLO 模式启动本地 Codex 编排器会话：
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：
`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及
`sandbox: "danger-full-access"`。这是用于自治心跳的受信任本地操作员姿态：
Codex 可以使用 shell 和网络工具，而不会停在无人响应的原生审批提示上。
`sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在原生审批提示上等待无人响应。
若要启用由 Codex guardian 审核的审批，请设置 `appServer.mode:
"guardian"`：
@ -350,15 +361,14 @@ Codex 可以使用 shell 和网络工具，而不会停在无人响应的原生
}
```
Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求离开
沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给原生审核器，而不是人工提示。审核器会应用 Codex 的风险框架，并批准或拒绝该特定请求。当你希望比 YOLO 模式有更多护栏，但仍需要无人值守的智能体继续推进时，请使用 Guardian。
Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求离开沙箱、写入工作区之外，或添加网络访问等权限时，Codex 会将该审批请求路由给原生审核器，而不是提示人工处理。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你希望比 YOLO 模式有更多防护栏，同时仍需要无人值守的智能体持续推进时，请使用 Guardian。
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、
`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。
各个策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。较旧的 `guardian_subagent` 审核器值仍被接受，作为兼容别名，但新配置应使用
`approvalsReviewer: "auto_review"`，以及 `sandbox: "workspace-write"`。
各个策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。较旧的 `guardian_subagent` 审核器取值仍作为兼容别名被接受，但新配置应使用
`auto_review`。
对于已在运行的应用服务器，请使用 WebSocket 传输：
对于已在运行的 app-server，请使用 WebSocket 传输：
```json5
{
@ -382,22 +392,22 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
支持的 `appServer` 字段：
| 字段 | 默认值 | 含义 |
| Field | Default | Meaning |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 |
| `command` | 由 OpenClaw 管理的 Codex 二进制文件 | 用于 stdio 传输的可执行文件。保持未设置以使用受管二进制文件；仅在明确覆盖时设置。 |
| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 |
| `url` | 未设置 | WebSocket 应用服务器 URL。 |
| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 |
| `headers` | `{}` | 额外的 WebSocket 标头。 |
| `requestTimeoutMs` | `60000` | 应用服务器控制平面调用的超时时间。 |
| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 |
| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/回合的原生 Codex 审批策略。 |
| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 |
| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 让 Codex 审核原生审批提示。`guardian_subagent` 仍然是旧版别名。 |
| `serviceTier` | 未设置 | 可选的 Codex 应用服务器服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 |
| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 |
| `command` | 受管 Codex 二进制文件 | 用于 stdio 传输的可执行文件。留空时使用受管二进制文件；仅在需要显式覆盖时设置。 |
| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 |
| `url` | 未设置 | WebSocket app-server URL。 |
| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 |
| `headers` | `{}` | 额外的 WebSocket 标头。 |
| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 |
| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 |
| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 |
| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 |
| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 让 Codex 审核原生审批提示。`guardian_subagent` 仍然是旧版别名。 |
| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版取值会被忽略。 |
环境覆盖仍可用于本地测试：
环境变量覆盖仍可用于本地测试：
- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -407,10 +417,9 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
当 `appServer.command` 未设置时，`OPENCLAW_CODEX_APP_SERVER_BIN` 会绕过受管二进制文件。
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。请改用
`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试中使用
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，优先使用配置，
因为这样可以将插件行为与其余 Codex 编排器设置保存在同一个已审查文件中。
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用
`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试时使用
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复的部署，优先使用配置，因为它会将插件行为与 Codex harness 其余设置保存在同一个经过审查的文件中。
## 常见配方
@ -428,7 +437,7 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
}
```
仅使用 Codex 的编排器验证：
仅使用 Codex 的 harness 验证：
```json5
{
@ -472,7 +481,7 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
}
```
带显式标头的远程应用服务器：
带显式标头的远程 app-server：
```json5
{
@ -496,146 +505,163 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
```
模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的
Codex 线程时，下一回合会再次将当前选定的
OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给
app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选择的模型继续运行。
Codex 线程时，下一轮会再次将当前选定的
OpenAI 模型、提供商、审批策略、沙箱和服务层级发送到
app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选定的模型继续执行。
## Codex 命令
内置插件将 `/codex` 注册为授权的斜杠命令。它是通用的，
适用于任何支持 OpenClaw 文本命令的渠道。
内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用的，适用于任何支持 OpenClaw 文本命令的渠道。
常见形式：
- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 Skills。
- `/codex models` 列出实时 Codex 应用服务器模型。
- `/codex models` 列出实时 Codex app-server 模型。
- `/codex threads [filter]` 列出最近的 Codex 线程。
- `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有 Codex 线程。
- `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有的 Codex 线程。
- `/codex compact` 请求 Codex app-server 压缩已附加的线程。
- `/codex review` 为已附加线程启动 Codex 原生审核。
- `/codex account` 显示账户和速率限制状态。
- `/codex mcp` 列出 Codex 应用服务器 MCP 服务器状态。
- `/codex skills` 列出 Codex 应用服务器 Skills。
- `/codex mcp` 列出 Codex app-server MCP 服务器状态。
- `/codex skills` 列出 Codex app-server Skills。
`/codex resume` 会写入与编排器在普通回合中使用的相同侧车绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持扩展历史启用。
`/codex resume` 会写入与 harness 用于正常轮次相同的 sidecar 绑定文件。在下一条消息时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持启用扩展历史记录。
该命令界面要求 Codex 应用服务器版本为 `0.125.0` 或更高。
如果未来版本或自定义应用服务器未公开该 JSON-RPC 方法，单独的控制方法会显示为 `unsupported by this Codex app-server`。
该命令界面要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，各个控制方法会显示为 `unsupported by this Codex app-server`。
## 钩子边界
Codex 编排器有三层钩子：
Codex harness 具有三层钩子：
| 层级 | 所有者 | 目的 |
| Layer | Owner | Purpose |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| OpenClaw 插件钩子 | OpenClaw | 在 Pi 和 Codex 编排器之间提供产品/插件兼容性。 |
| Codex 应用服务器扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的每回合适配器行为。 |
| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 |
| OpenClaw 插件钩子 | OpenClaw | 跨 PI 和 Codex harness 的产品/插件兼容性。 |
| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐轮适配器行为。 |
| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 |
OpenClaw 不使用项目级或全局的 Codex `hooks.json` 文件来路由
OpenClaw 不使用项目级或全局 Codex `hooks.json` 文件来路由
OpenClaw 插件行为。对于受支持的原生工具和权限桥接，
OpenClaw 会为 `PreToolUse`、`PostToolUse` 和
`PermissionRequest` 注入每线程的 Codex 配置。其他 Codex 钩子，例如 `SessionStart`、
`UserPromptSubmit` 和 `Stop`，仍然是 Codex 级控制；在 v1 合约中，它们不会作为 OpenClaw 插件钩子公开。
OpenClaw 会为每个线程注入 Codex 配置，用于 `PreToolUse`、`PostToolUse`、
`PermissionRequest` 和 `Stop`。其他 Codex 钩子，如 `SessionStart` 和
`UserPromptSubmit`，仍然是 Codex 级别的控制；在 v1 合约中，它们不会暴露为
OpenClaw 插件钩子。
对于 OpenClaw 动态工具，在 Codex 请求调用后，OpenClaw 才会执行该工具，因此 OpenClaw 会在编排器适配器中触发其拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。
OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调公开该操作，否则它无法重写原生 Codex 线程。
对于 OpenClaw 动态工具，OpenClaw 会在 Codex 发出调用请求后执行工具，因此 OpenClaw 会在 harness 适配器中触发它所拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。
OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调暴露该操作，否则它无法改写原生 Codex 线程。
压缩和 LLM 生命周期投影来自 Codex app-server
通知和 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。
通知以及 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。
OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和
`llm_output` 事件属于适配器级观察，而不是对 Codex 内部请求或压缩负载的逐字节捕获。
`llm_output` 事件是适配器级观察结果，并不是对
Codex 内部请求或压缩载荷的逐字节捕获。
Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为用于轨迹和调试的 `codex_app_server.hook` 智能体事件。
Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为
`codex_app_server.hook` 智能体事件，用于轨迹和调试。
它们不会调用 OpenClaw 插件钩子。
## V1 支持合约
Codex 模式并不是底层只换了一个模型调用的 Pi。Codex 接管了更多
原生模型循环，而 OpenClaw 会围绕这一边界适配它的插件和会话界面。
Codex 模式并不是在底层换了一次模型调用的 PI。Codex 接管了更多原生模型循环，而 OpenClaw 会围绕这一边界调整其插件和会话界面。
Codex 运行时 v1 中支持：
在 Codex runtime v1 中支持：
| 界面 | 支持情况 | 原因 |
| -------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex 应用服务器负责 OpenAI 回合、原生线程恢复和原生工具续接。 |
| OpenClaw 渠道路由和传输 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道仍位于模型运行时之外。 |
| OpenClaw 动态工具 | 支持 | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 始终位于执行路径中。 |
| 提示词和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程之前构建提示词叠加层，并将上下文投射到 Codex 回合中。 |
| 上下文引擎生命周期 | 支持 | 组装、摄取或回合后维护，以及上下文引擎压缩协调都会在 Codex 回合中运行。 |
| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 管理的动态工具运行。 |
| 生命周期钩子 | 作为适配器观察支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会以真实的 Codex 模式负载触发。 |
| 原生 shell、patch 和 MCP 的阻止或观察 | 通过原生钩子中继支持 | 对于已提交的原生工具界面，包括 Codex 应用服务器 `0.125.0` 或更高版本上的 MCP 负载，Codex 的 `PreToolUse` 和 `PostToolUse` 会被中继。支持阻止，但不支持参数重写。 |
| 原生权限策略 | 通过原生钩子中继支持 | 在运行时公开该能力的情况下，Codex 的 `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 不返回决策，Codex 会继续其正常的 guardian 或用户审批路径。 |
| 应用服务器轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求，以及它收到的 app-server 通知。 |
| Surface | Support | Why |
| --------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 负责 OpenAI 轮次、原生线程恢复，以及原生工具续接。 |
| OpenClaw 渠道路由与投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 以及其他渠道都保持在模型运行时之外。 |
| OpenClaw 动态工具 | 支持 | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 仍然位于执行路径中。 |
| 提示词与上下文插件 | 支持 | OpenClaw 会在启动或恢复线程之前构建提示词叠加层，并将上下文投射到 Codex 轮次中。 |
| 上下文引擎生命周期 | 支持 | 组装、摄取或轮次后的维护，以及上下文引擎压缩协调，都会为 Codex 轮次运行。 |
| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕由 OpenClaw 持有的动态工具运行。 |
| 生命周期钩子 | 作为适配器观察结果提供支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会以真实的 Codex 模式载荷触发。 |
| 最终答案修订关卡 | 通过原生钩子中继提供支持 | Codex `Stop` 会中继到 `before_agent_finalize`；`revise` 会在最终完成前要求 Codex 再进行一次模型传递。 |
| 原生 shell、patch 和 MCP 的阻止或观察 | 通过原生钩子中继提供支持 | 对于已承诺的原生工具表面，包括 Codex app-server `0.125.0` 或更高版本中的 MCP 载荷，Codex `PreToolUse` 和 `PostToolUse` 都会被中继。支持阻止；不支持参数重写。 |
| 原生权限策略 | 通过原生钩子中继提供支持 | 在运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略进行路由。如果 OpenClaw 不返回决定，Codex 会继续走它正常的 guardian 或用户审批路径。 |
| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送到 app-server 的请求，以及它接收到的 app-server 通知。 |
在 Codex 运行时 v1 中不支持：
在 Codex runtime v1 中不支持：
| 界面 | V1 边界 | 未来路径 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| 原生工具参数变更 | Codex 原生预工具钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/模式支持用于替换工具输入。 |
| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有镜像，并可投射未来上下文，但不应修改不受支持的内部结构。 | 如果需要对原生线程进行操作，则需添加显式的 Codex app-server API。 |
| 用于 Codex 原生工具记录的 `tool_result_persist` | 该钩子会转换由 OpenClaw 管理的转录写入，而不是 Codex 原生工具记录。 | 可以镜像已转换的记录，但规范性重写需要 Codex 支持。 |
| 丰富的原生压缩元数据 | OpenClaw 可以观察到压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 增量或摘要负载。 | 需要更丰富的 Codex 压缩事件。 |
| 压缩干预 | 在 Codex 模式下，当前 OpenClaw 压缩钩子仅为通知级别。 | 如果插件需要否决或重写原生压缩，则需添加 Codex 压缩前/后钩子。 |
| 停止或最终答案门控 | Codex 具有原生停止钩子，但 OpenClaw 不会将最终答案门控公开为 v1 插件合约。 | 未来可加入带循环和超时保护的可选原语。 |
| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但 Codex 核心会在内部构建最终的 OpenAI API 请求。 | 需要 Codex 模型请求跟踪事件或调试 API。 |
| Surface | V1 边界 | 未来路径 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 原生工具参数变更 | Codex 原生 pre-tool 钩子可以阻止调用，但 OpenClaw 不会重写 Codex 原生工具参数。 | 这需要 Codex 钩子/schema 支持替换后的工具输入。 |
| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有一个镜像，并且可以投射未来上下文，但不应修改不受支持的内部结构。 | 如果需要对原生线程进行修改，应添加显式的 Codex app-server API。 |
| 用于 Codex 原生工具记录的 `tool_result_persist` | 该钩子转换的是由 OpenClaw 持有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范性重写仍需要 Codex 支持。 |
| 丰富的原生压缩元数据 | OpenClaw 可以观察到压缩开始和完成，但不会接收到稳定的保留/丢弃列表、token 变化量或摘要载荷。 | 这需要更丰富的 Codex 压缩事件。 |
| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式下仅为通知级别。 | 如果插件需要否决或重写原生压缩，应添加 Codex 的 pre/post 压缩钩子。 |
| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但最终的 OpenAI API 请求由 Codex core 在内部构建。 | 这需要 Codex 模型请求追踪事件或调试 API。 |
## 工具、媒体和压缩
## 工具、媒体与压缩
Codex 编排器只会改变底层嵌入式智能体执行器。
Codex harness 只改变底层的嵌入式智能体执行器。
OpenClaw 仍然会构建工具列表，并从编排器接收动态工具结果。文本、图像、视频、音乐、TTS、审批和消息工具输出仍然通过正常的 OpenClaw 传输路径继续处理。
OpenClaw 仍然会构建工具列表，并从
harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出
仍然通过正常的 OpenClaw 投递路径继续工作。
原生钩子中继被有意设计为通用机制，但 v1 支持合约仅限于 OpenClaw 已测试的 Codex 原生工具和权限路径。在
Codex 运行时中，这包括 shell、patch 和 MCP 的 `PreToolUse`、
`PostToolUse` 以及 `PermissionRequest` 负载。在运行时合约明确命名之前，不要假设未来每个 Codex 钩子事件都会成为 OpenClaw 插件界面。
原生钩子中继被有意设计为通用机制，但 v1 支持合约仅限于
OpenClaw 已测试的 Codex 原生工具和权限路径。在
Codex runtime 中，这包括 shell、patch 和 MCP `PreToolUse`、
`PostToolUse` 以及 `PermissionRequest` 载荷。在运行时合约明确命名前，
不要假设未来每一个 Codex 钩子事件都属于 OpenClaw 插件表面。
对于 `PermissionRequest`，只有当策略做出决定时，OpenClaw 才会返回明确的允许或拒绝决策。无决策结果并不等于允许。Codex 会将其视为没有钩子决策，并继续走它自己的 guardian 或用户审批路径。
对于 `PermissionRequest`，只有当策略做出决定时，OpenClaw 才会返回明确的允许或拒绝决定。
“无决定”结果并不等于允许。Codex 会将其视为没有
钩子决定，并回退到它自己的 guardian 或用户审批路径。
当 Codex 将 `_meta.codex_approval_kind` 标记为
`"mcp_tool_call"` 时，Codex MCP 工具审批征询会通过 OpenClaw 的插件审批流程进行路由。Codex 的 `request_user_input` 提示会被发回原始聊天，而下一个排队的后续消息会响应该原生服务器请求，而不是作为额外上下文进行引导。其他 MCP 征询请求仍会以失败结束。
`"mcp_tool_call"` 时，Codex MCP 工具审批征求会通过 OpenClaw 的插件
审批流程进行路由。Codex `request_user_input` 提示会被发送回
原始聊天，而下一个排队的后续消息会回答该原生
服务器请求，而不是作为额外上下文进行引导。其他 MCP 征求请求仍然会以关闭式失败。
当所选模型使用 Codex 编排器时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset`，以及未来的模型或编排器切换。该镜像包含用户提示词、最终助手文本，以及当 app-server 发出这些内容时的轻量级 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它尚未公开人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。
当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset`，以及将来的模型或 harness 切换。该镜像包括用户提示词、最终助手文本，以及 app-server 发出这些记录时的轻量级 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩的开始和完成信号。它尚未公开可供人类阅读的压缩摘要，也尚未提供一份可审计列表来说明 Codex 在压缩后保留了哪些条目。
由于 Codex 拥有规范的原生线程，`tool_result_persist` 当前不会重写 Codex 原生工具结果记录。它仅在 OpenClaw 写入由 OpenClaw 管理的会话转录工具结果时适用。
由于 Codex 拥有规范的原生线程，`tool_result_persist` 当前不会
重写 Codex 原生工具结果记录。它仅在
OpenClaw 正在写入由 OpenClaw 持有的会话转录工具结果时适用。
媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用相应的提供商/模型设置，例如
媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 以及媒体理解
仍会继续使用相应的 provider/模型设置，例如
`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和
`messages.tts`。
## 故障排除
**Codex 没有显示为普通 `/model` 提供商：** 这对于新配置是预期行为。请选择一个 `openai/gpt-*` 模型，并设置
**Codex 没有显示为普通的 `/model` provider：** 对于
新配置，这是预期行为。请选择一个 `openai/gpt-*` 模型，并设置
`embeddedHarness.runtime: "codex"`（或使用旧版 `codex/*` 引用），启用
`plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了
`codex`。
**OpenClaw 使用了 Pi 而不是 Codex：** `runtime: "auto"` 在没有 Codex 编排器接管运行时，仍可能使用 Pi 作为兼容性后端。测试时请设置
`embeddedHarness.runtime: "codex"` 以强制选择 Codex。现在，强制 Codex 运行时在失败时会直接报错，而不是回退到 Pi，除非你显式设置
`embeddedHarness.fallback: "pi"`。一旦选择了 Codex app-server，其故障会直接暴露，不会再有额外的回退配置。
**OpenClaw 使用了 PI 而不是 Codex：** `runtime: "auto"` 在没有 Codex harness 声明接管该运行时，仍然可能使用 PI 作为
兼容性后端。测试时请设置
`embeddedHarness.runtime: "codex"` 以强制选择 Codex。
现在，除非你显式设置 `embeddedHarness.fallback: "pi"`，否则强制的 Codex 运行时会在失败时直接报错，而不是回退到 PI。一旦选中了 Codex app-server，其失败会直接暴露出来，不需要额外的回退配置。
**应用服务器被拒绝：** 升级 Codex，使 app-server 握手报告的版本为
`0.125.0` 或更高。相同版本号的预发布版或带构建后缀的版本，例如
`0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为 OpenClaw 测试的是稳定版 `0.125.0` 这一协议下限。
**app-server 被拒绝：** 请升级 Codex，使 app-server 握手
报告版本 `0.125.0` 或更高。相同版本号的预发布版或带构建后缀的
版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为
OpenClaw 测试的是稳定版 `0.125.0` 协议下限。
**模型发现速度慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`
或禁用模型发现。
**模型发现过慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`
或禁用发现。
**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，
并确认远程应用服务器使用相同的 Codex app-server 协议版本。
**WebSocket 传输立即失败：** 请检查 `appServer.url`、`authToken`，
以及远程 app-server 是否使用相同版本的 Codex app-server 协议。
**非 Codex 模型使用了 Pi：** 除非你为该智能体强制设置了
**非 Codex 模型使用了 PI：** 除非你为该智能体强制设置了
`embeddedHarness.runtime: "codex"`，或选择了旧版
`codex/*` 引用，否则这是预期行为。普通的 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下会继续走它们正常的提供商路径。如果你强制设置 `runtime: "codex"`，则该智能体的每个嵌入式回合都必须是 Codex 支持的 OpenAI 模型。
`codex/*` 引用，否则这是预期行为。普通的 `openai/gpt-*` 和其他 provider 引用在 `auto` 模式下会保持其正常的
provider 路径。如果你强制设置 `runtime: "codex"`，则该智能体的每一个嵌入式
轮次都必须使用受 Codex 支持的 OpenAI 模型。
## 相关内容
- [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness)
- [Agent Runtimes](/zh-CN/concepts/agent-runtimes)
- [模型提供商](/zh-CN/concepts/model-providers)
- [Model providers](/zh-CN/concepts/model-providers)
- [OpenAI provider](/zh-CN/providers/openai)
- [Status](/zh-CN/cli/status)
- [Plugin hooks](/zh-CN/plugins/hooks)
- [配置参考](/zh-CN/gateway/configuration-reference)
- [测试](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke)
- [Configuration reference](/zh-CN/gateway/configuration-reference)
- [Testing](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke)

118
docs/zh-CN/plugins/hooks.md
View File

@ -2,25 +2,25 @@
read_when:
- 你正在构建一个插件，需要 `before_tool_call`、`before_agent_reply`、消息钩子或生命周期钩子
- 你需要从插件中阻止、重写或要求批准工具调用
- 你正在内部钩子和插件钩子之间做选择
summary: 插件钩子：拦截智能体、工具、消息、会话和 Gateway 网关生命周期事件
- 你正在内部钩子和插件钩子之间做出选择
summary: 插件钩子：拦截智能体、工具、消息、会话以及 Gateway 网关生命周期事件
title: 插件钩子
x-i18n:
generated_at: "2026-04-25T18:51:26Z"
generated_at: "2026-04-26T00:28:47Z"
model: gpt-5.4
provider: openai
source_hash: 4fc848daa4a0da6f55bf0f75d184ffa4925b64c3f22529c99623535842bd6733
source_hash: c9f1d08cb60b438b5478dc813600cc7c2b7a4169b0785812a04e395e1c893b02
source_path: plugins/hooks.md
workflow: 15
---
插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装流程或 Gateway 网关启动时，请使用它们。
如果你想要一个由操作员安装的小型 `HOOK.md` 脚本来处理命令和 Gateway 网关事件，例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`，请改用 [内部钩子](/zh-CN/automation/hooks)。
如果你想为命令和 Gateway 网关事件（例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`）使用一个由操作员安装的小型 `HOOK.md` 脚本，请改用 [内部钩子](/zh-CN/automation/hooks)。
## 快速开始
在你的插件入口中使用 `api.on(...)` 注册类型化的插件钩子：
在你的插件入口中，使用 `api.on(...)` 注册带类型的插件钩子：
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -52,40 +52,41 @@ export default definePluginEntry({
});
```
钩子处理器会按 `priority` 的降序依次运行。相同优先级的钩子会保持注册顺序。
钩子处理程序会按 `priority` 的降序依次运行。相同优先级的钩子会保持注册顺序。
## 钩子目录
钩子按它们所扩展的表面分组。**加粗** 的名称接受决策结果（阻止、取消、覆盖或要求批准）；其余都仅用于观察。
钩子按其扩展的表面进行分组。名称以 **粗体** 标出的钩子接受决策结果（阻止、取消、覆盖或要求批准）；其余钩子仅用于观察。
**智能体轮次**
- `before_model_resolve` — 在加载会话消息之前覆盖提供商或模型
- `before_model_resolve` — 在加载会话消息之前覆盖 provider 或模型
- `before_prompt_build` — 在模型调用之前添加动态上下文或系统提示文本
- `before_agent_start` — 仅用于兼容性的组合阶段；优先使用上面的两个钩子
- `before_agent_start` — 仅用于兼容性的合并阶段；优先使用上面的两个钩子
- **`before_agent_reply`** — 使用合成回复或静默来短路模型轮次
- **`before_agent_finalize`** — 检查自然生成的最终答案，并请求再进行一次模型传递
- `agent_end` — 观察最终消息、成功状态和运行时长
**会话观察**
- `model_call_started` / `model_call_ended` — 观察已清洗的提供商/模型调用元数据、耗时、结果以及有界请求 ID 哈希，不包含提示词或响应内容
- `llm_input` — 观察提供商输入（系统提示词、提示词、历史记录）
- `llm_output` — 观察提供商输出
- `model_call_started` / `model_call_ended` — 观察已脱敏的 provider/模型调用元数据、耗时、结果以及有界 request-id 哈希，不包含提示词或响应内容
- `llm_input` — 观察 provider 输入（系统提示、提示词、历史记录）
- `llm_output` — 观察 provider 输出
**工具**
- **`before_tool_call`** — 重写工具参数、阻止执行或要求批准
- `after_tool_call` — 观察工具结果、错误和耗时
- **`tool_result_persist`** — 重写由工具结果生成的助手消息
- **`tool_result_persist`** — 重写根据工具结果生成的助手消息
- **`before_message_write`** — 检查或阻止进行中的消息写入（少见）
**消息与投递**
- **`inbound_claim`** — 在智能体路由之前认领一条入站消息（合成回复）
- **`inbound_claim`** — 在智能体路由之前声明一条入站消息（合成回复）
- `message_received` — 观察入站内容、发送者、线程和元数据
- **`message_sending`** — 重写出站内容或取消投递
- `message_sent` — 观察出站投递成功或失败
- **`before_dispatch`** — 在交给渠道之前检查或重写一次出站分发
- **`before_dispatch`** — 在交给渠道之前检查或重写出站分发
- **`reply_dispatch`** — 参与最终回复分发流水线
**会话与压缩**
@ -96,12 +97,12 @@ export default definePluginEntry({
**子智能体**
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — 协调子智能体路由与完成结果投递
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — 协调子智能体路由和完成结果投递
**生命周期**
- `gateway_start` / `gateway_stop` — 随 Gateway 网关启动或停止插件拥有的服务
- **`before_install`** — 检查 Skills 或插件安装扫描，并可选择阻止安装
- `gateway_start` / `gateway_stop` — 随 Gateway 网关启动或停止由插件拥有的服务
- **`before_install`** — 检查 Skills 或插件安装扫描，并可选择阻止
## 工具调用策略
@ -111,7 +112,7 @@ export default definePluginEntry({
- `event.params`
- 可选的 `event.runId`
- 可选的 `event.toolCallId`
- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId` 以及诊断用的 `ctx.trace`
- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId` 以及诊断字段 `ctx.trace`
它可以返回：
@ -136,35 +137,37 @@ type BeforeToolCallResult = {
规则：
- `block: true` 是终止性的，并会跳过更低优先级的处理器。
- `block: false` 会被视为没有决策。
- `params` 会重写执行时使用的工具参数。
- `requireApproval` 会暂停智能体运行，并通过插件批准机制向用户请求批准。`/approve` 命令既可批准 exec 批准，也可批准插件批准。
- 即使较高优先级的钩子请求了批准，较低优先级的 `block: true` 仍然可以阻止执行。
- `onResolution` 会接收最终的批准决策 —— `allow-once`、`allow-always`、`deny`、`timeout` 或 `cancelled`。
- `block: true` 是终止性的，并会跳过更低优先级的处理程序。
- `block: false` 会被视为未作出决策。
- `params` 会重写实际执行时的工具参数。
- `requireApproval` 会暂停智能体运行，并通过插件审批向用户发起请求。`/approve` 命令既可批准 exec 审批，也可批准插件审批。
- 即使更高优先级的钩子请求了批准，更低优先级的 `block: true` 仍然可以阻止执行。
- `onResolution` 会接收最终解析出的审批决定 —— `allow-once`、`allow-always`、`deny`、`timeout` 或 `cancelled`。
### 工具结果持久化
工具结果可以包含结构化的 `details`，用于 UI 渲染、诊断、媒体路由或插件拥有的元数据。请将 `details` 视为运行时元数据，而不是提示词内容：
工具结果可以包含用于 UI 渲染、诊断、媒体路由或插件自有元数据的结构化 `details`。请将 `details` 视为运行时元数据，而不是提示内容：
- OpenClaw 会在提供商重放和压缩输入之前去除 `toolResult.details`，以防元数据进入模型上下文。
- OpenClaw 会在 provider 重放和压缩输入之前移除 `toolResult.details`，以防元数据成为模型上下文。
- 持久化的会话条目只保留有界的 `details`。超大的 details 会被替换为紧凑摘要，并带有 `persistedDetailsTruncated: true`。
- `tool_result_persist` 和 `before_message_write` 会在最终持久化上限生效之前运行。钩子仍应保持返回的 `details` 足够小，并避免只把与提示词相关的文本放在 `details` 中；模型可见的工具输出应放在 `content` 中。
- `tool_result_persist` 和 `before_message_write` 会在最终持久化大小限制之前运行。钩子仍应保持返回的 `details` 较小，并避免只将与提示相关的文本放在 `details` 中；模型可见的工具输出应放在 `content` 中。
## 提示词与模型钩子
## 提示与模型钩子
新插件请使用特定阶段的钩子：
新插件请使用按阶段划分的钩子：
- `before_model_resolve`：只接收当前提示词和附件元数据。返回 `providerOverride` 或 `modelOverride`。
- `before_prompt_build`：接收当前提示词和会话消息。返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。
- `before_model_resolve`：仅接收当前提示和附件元数据。返回 `providerOverride` 或 `modelOverride`。
- `before_prompt_build`：接收当前提示和会话消息。返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。
`before_agent_start` 仍保留用于兼容性。优先使用上面的显式钩子，这样你的插件就不会依赖旧的组合阶段。
`before_agent_start` 仍保留用于兼容性。优先使用上面的显式钩子，这样你的插件就不会依赖旧式的合并阶段。
当 OpenClaw 能识别当前活动运行时，`before_agent_start` 和 `agent_end` 会包含 `event.runId`。同一个值也可通过 `ctx.runId` 获取。
当 OpenClaw 能识别当前活动运行时，`before_agent_start` 和 `agent_end` 会包含 `event.runId`。相同的值也可通过 `ctx.runId` 获取。
对于不应接收原始提示词、历史记录、响应、请求头、请求体或提供商请求 ID 的提供商调用遥测，请使用 `model_call_started` 和 `model_call_ended`。这些钩子包含稳定的元数据，例如 `runId`、`callId`、`provider`、`model`、可选的 `api`/`transport`、最终的 `durationMs`/`outcome`，以及当 OpenClaw 能推导时提供的 `upstreamRequestIdHash`（有界提供商请求 ID 哈希）。
对于不应接收原始提示词、历史记录、响应、请求头、请求体或 provider 请求 ID 的 provider 调用遥测，请使用 `model_call_started` 和 `model_call_ended`。这些钩子包含稳定的元数据，例如 `runId`、`callId`、`provider`、`model`、可选的 `api`/`transport`、最终的 `durationMs`/`outcome`，以及当 OpenClaw 能推导出有界 provider request-id 哈希时提供的 `upstreamRequestIdHash`。
需要 `llm_input`、`llm_output` 或 `agent_end` 的非内置插件必须设置：
`before_agent_finalize` 仅在 harness 即将接受自然生成的最终助手答案时运行。它不是 `/stop` 取消路径的一部分，也不会在用户中止轮次时运行。返回 `{ action: "revise", reason }` 可请求 harness 在最终确定之前再进行一次模型传递，返回 `{ action: "finalize", reason? }` 可强制最终确定，或者省略返回结果以继续。Codex 原生 `Stop` 钩子会作为 OpenClaw 的 `before_agent_finalize` 决策转发到此钩子。
需要使用 `llm_input`、`llm_output`、`before_agent_finalize` 或 `agent_end` 的非内置插件，必须设置：
```json
{
@ -180,60 +183,53 @@ type BeforeToolCallResult = {
}
```
可修改提示词的钩子可以按插件通过 `plugins.entries.<id>.hooks.allowPromptInjection=false` 禁用。
可修改提示词的钩子可以通过 `plugins.entries.<id>.hooks.allowPromptInjection=false` 按插件禁用。
## 消息钩子
对渠道级路由和投递策略，请使用消息钩子：
使用消息钩子来处理渠道级路由和投递策略：
- `message_received`：观察入站内容、发送者、`threadId`、`messageId`、`senderId`、可选的运行/会话关联信息以及元数据。
- `message_sending`：重写 `content` 或返回 `{ cancel: true }`。
- `message_sent`：观察最终成功或失败状态。
- `message_sent`：观察最终成功或失败。
对于仅音频的 TTS 回复，即使渠道负载没有可见文本/说明，`content` 也可能包含隐藏的口述转录文本。重写该 `content` 只会更新钩子可见的转录文本；它不会被渲染为媒体说明。
对于仅音频的 TTS 回复，即使渠道负载中没有可见文本/说明，`content` 也可能包含隐藏的口述转录内容。重写该 `content` 只会更新钩子可见的转录文本；它不会作为媒体说明呈现。
消息钩子上下文会在可用时公开稳定的关联字段：
`ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、
`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。优先使用这些一等字段，而不是读取旧版元数据。
消息钩子上下文在可用时会暴露稳定的关联字段：`ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。在读取旧版元数据之前，优先使用这些一等字段。
优先使用类型化的 `threadId` 和 `replyToId` 字段，而不是使用特定于渠道的元数据。
在使用渠道特定元数据之前，优先使用带类型的 `threadId` 和 `replyToId` 字段。
决策规则：
- 带有 `cancel: true` 的 `message_sending` 是终止性的。
- 带有 `cancel: false` 的 `message_sending` 会被视为没有决策。
- 重写后的 `content` 会继续传递给更低优先级的钩子，除非之后的钩子取消投递。
- 带有 `cancel: false` 的 `message_sending` 会被视为未作出决策。
- 重写后的 `content` 会继续传递给更低优先级的钩子，除非后续钩子取消了投递。
## 安装钩子
`before_install` 会在内置的 Skills 和插件安装扫描之后运行。返回额外发现项，或返回 `{ block: true, blockReason }` 以停止安装。
`block: true` 是终止性的。`block: false` 会被视为没有决策。
`block: true` 是终止性的。`block: false` 会被视为未作出决策。
## Gateway 网关生命周期
对于需要 Gateway 网关拥有状态的插件服务，请使用 `gateway_start`。上下文会公开 `ctx.config`、`ctx.workspaceDir` 以及用于检查和更新 cron 的 `ctx.getCron?.()`。使用 `gateway_stop` 清理长期运行的资源。
对于需要 Gateway 网关自有状态的插件服务，请使用 `gateway_start`。上下文会暴露 `ctx.config`、`ctx.workspaceDir` 以及用于检查和更新 cron 的 `ctx.getCron?.()`。使用 `gateway_stop` 清理长期运行的资源。
不要依赖内部的 `gateway:startup` 钩子来管理插件拥有的运行时服务。
不要依赖内部的 `gateway:startup` 钩子来处理插件自有的运行时服务。
## 即将弃用的内容
有少数与钩子相邻的表面已弃用，但仍受支持。请在下一个主要版本发布前完成迁移：
有一些与钩子相邻的表面已被弃用，但仍受支持。请在下一个主版本发布前完成迁移：
- **`inbound_claim` 和 `message_received` 处理器中的纯文本渠道信封**。请读取 `BodyForAgent` 和结构化的用户上下文块，而不要解析扁平信封文本。参见
[纯文本渠道信封 → BodyForAgent](/zh-CN/plugins/sdk-migration#active-deprecations)。
- **`before_agent_start`** 仍保留用于兼容性。新插件应使用 `before_model_resolve` 和 `before_prompt_build`，而不是这个组合阶段。
- **`before_tool_call` 中的 `onResolution`** 现在使用类型化的
`PluginApprovalResolution` 联合（`allow-once` / `allow-always` / `deny` /
`timeout` / `cancelled`），而不是自由形式的 `string`。
- **`inbound_claim` 和 `message_received` 处理程序中的纯文本渠道信封**。请读取 `BodyForAgent` 和结构化的用户上下文块，而不是解析扁平的信封文本。参见 [纯文本渠道信封 → BodyForAgent](/zh-CN/plugins/sdk-migration#active-deprecations)。
- **`before_agent_start`** 仍保留用于兼容性。新插件应使用 `before_model_resolve` 和 `before_prompt_build`，而不是这个合并阶段。
- **`before_tool_call` 中的 `onResolution`** 现在使用带类型的 `PluginApprovalResolution` 联合类型（`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`），而不是自由格式的 `string`。
有关完整列表 —— memory capability 注册、provider thinking
profile、外部认证提供商、提供商发现类型、任务运行时访问器，以及 `command-auth` → `command-status` 重命名 —— 请参见
[插件 SDK migration → Active deprecations](/zh-CN/plugins/sdk-migration#active-deprecations)。
完整列表 —— 包括 memory 能力注册、provider thinking 配置文件、外部身份验证 provider、provider 发现类型、任务运行时访问器，以及 `command-auth` → `command-status` 重命名 —— 请参见 [插件 SDK 迁移 → 当前弃用项](/zh-CN/plugins/sdk-migration#active-deprecations)。
## 相关内容
- [插件 SDK migration](/zh-CN/plugins/sdk-migration) — 活跃弃用项和移除时间线
- [插件 SDK 迁移](/zh-CN/plugins/sdk-migration) — 当前弃用项与移除时间线
- [构建插件](/zh-CN/plugins/building-plugins)
- [插件 SDK 概览](/zh-CN/plugins/sdk-overview)
- [插件入口点](/zh-CN/plugins/sdk-entrypoints)

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

@ -1,103 +1,93 @@
---
read_when:
- 通过 ACP 运行编码 harness
- 在消息渠道上设置绑定到会话的 ACP 会话
- 将消息渠道会话绑定到持久化的 ACP 会话
- 排查 ACP 后端和插件连接问题
- 调试 ACP 完成交付或智能体到智能体循环问题
- 通过聊天操作 `/acp` 命令
summary: 对 Claude Code、Cursor、Gemini CLI 使用 ACP 运行时会话，以及显式的 Codex ACP 回退、OpenClaw ACP 和其他 harness 智能体。
- 在消息渠道上设置与对话绑定的 ACP 会话
- 将消息渠道中的会话绑定到持久化的 ACP 会话
- ACP 后端和插件连接的故障排除
- 调试 ACP 完成结果传递或智能体到智能体循环
- 从聊天中操作 `/acp` 命令
summary: 对 Claude Code、Cursor、Gemini CLI 使用 ACP 运行时会话，显式的 Codex ACP 回退、OpenClaw ACP，以及其他 harness 智能体也同样如此
title: ACP 智能体
x-i18n:
generated_at: "2026-04-26T00:04:54Z"
generated_at: "2026-04-26T00:28:54Z"
model: gpt-5.4
provider: openai
source_hash: fa4164b8d51cb8025c8898153258e96f7e2a2d78baacc1350292fa6a0bc8c377
source_hash: 6fbf36aa46bbd555881333368c858ec80271ce188d01fb0e71ef12a13d2d626e
source_path: tools/acp-agents.md
workflow: 15
---
[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
如果你用自然语言要求 OpenClaw 在当前会话中绑定或控制 Codex，并且内置的 `codex` 插件已启用，OpenClaw 应该使用原生 Codex app-server 插件（`/codex bind`、`/codex threads`、`/codex resume`、`/codex steer`、`/codex stop`），而不是 ACP。如果你明确要求 `/acp`、ACP、acpx 或 ACP 适配器测试，OpenClaw 仍然可以通过 ACP 路由 Codex。每次 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
如果你用自然语言请求 OpenClaw 在当前会话中绑定或控制 Codex，并且内置的 `codex` 插件已启用，OpenClaw 应使用原生 Codex 应用服务器插件（`/codex bind`、`/codex threads`、`/codex resume`、`/codex steer`、`/codex stop`），而不是 ACP。如果你明确请求 `/acp`、ACP、acpx 或 ACP 适配器测试，OpenClaw 仍然可以通过 ACP 路由 Codex。每次 ACP 会话生成都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。
如果你用自然语言要求 OpenClaw “在一个线程中启动 Claude Code” 或使用其他外部 harness，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。
如果你用自然语言请求 OpenClaw “在一个线程中启动 Claude Code” 或使用其他外部 harness，OpenClaw 应将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。
如果你想让 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。
## 你需要哪个页面？
## 我想看哪个页面？
这里有三个相近的入口，容易混淆：
这里有三个相邻但很容易混淆的入口：
| 你想要…… | 使用这个 | 说明 |
| ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 在当前会话中绑定或控制 Codex | `/codex bind`、`/codex threads` | 当 `codex` 插件启用时，使用原生 Codex app-server 路径；包括绑定的聊天回复、图片转发、模型/快速/权限设置、停止和引导控制。ACP 是显式回退路径 |
| _通过_ OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP 或其他外部 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 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 |
| 在当前会话中绑定或控制 Codex | `/codex bind`、`/codex threads` | 当 `codex` 插件启用时使用原生 Codex 应用服务器路径；包括绑定聊天回复、图片转发、model/fast/permissions、停止和 steer 控制。ACP 是显式回退路径 |
| 通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP，或其他外部 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 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有 harness 运行时 |
## 这是否开箱即用？
## 这是开箱即用的吗？
通常是的。全新安装默认启用了内置 `acpx` 运行时插件，并带有插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复它。运行 `/acp doctor` 可执行就绪性检查。
通常是的。全新安装默认会启用内置的 `acpx` 运行时插件，并带有一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复。运行 `/acp doctor` 可进行就绪状态检查。
首次运行时的注意事项：
首次运行的常见问题：
- 如果设置了 `plugins.allow`，它就是一个限制性的插件清单，必须包含 `acpx`；否则内置默认项会被有意阻止，且 `/acp doctor` 会报告缺少 allowlist 条目。
- 目标 harness 适配器（Codex、Claude 等）可能会在你首次使用时通过 `npx` 按需获取。
- 该 harness 的供应商认证仍然必须已经存在于主机上。
- 如果主机没有 npm 或网络访问能力，首次运行时的适配器获取将失败，直到缓存被预热或适配器通过其他方式安装。
- 该 harness 依赖的厂商认证仍然必须已存在于主机上。
- 如果主机没有 npm 或网络访问能力，首次适配器获取会失败，直到缓存预热完成或以其他方式安装适配器。
## 操作手册
在聊天中使用 `/acp` 的快速流程：
从聊天中快速执行 `/acp` 流程：
1. **启动** — `/acp spawn claude --bind here`、`/acp spawn gemini --mode persistent --thread auto`，或显式使用 `/acp spawn codex --bind here`
2. 在绑定的会话或线程中**工作**（或显式指定会话键）。
1. **生成** — `/acp spawn claude --bind here`、`/acp spawn gemini --mode persistent --thread auto`，或显式使用 `/acp spawn codex --bind here`
2. 在绑定的会话或线程中**工作**（或者显式指定会话键）。
3. **检查状态** — `/acp status`
4. **调整** — `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
5. 在不替换上下文的情况下**引导** — `/acp steer tighten logging and continue`
4. **调优** — `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
5. **引导**而不替换上下文 — `/acp steer tighten logging and continue`
6. **停止** — `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定）
当原生 Codex 插件启用时，应路由到该插件的自然语言触发示例：
当原生 Codex 插件启用时，以下自然语言触发词应路由到原生 Codex 插件：
- “把这个 Discord 渠道绑定到 Codex。”
- “将这个聊天附加到 Codex 线程 `<id>`。”
- “显示 Codex 线程，然后绑定这一个。”
- “把这个聊天附加到 Codex 线程 `<id>`。”
- “显示 Codex 线程，然后绑定这个。”
原生 Codex 会话绑定是默认的聊天控制路径。OpenClaw 动态工具仍然通过 OpenClaw 执行，而 Codex 原生工具（如 shell/apply-patch）则在 Codex 内部执行。对于 Codex 原生工具事件，OpenClaw 会按轮次注入原生 hook 中继，以便插件钩子能够阻止
`before_tool_call`、观察 `after_tool_call`，并通过 OpenClaw 审批来路由 Codex 的
`PermissionRequest` 事件。v1 中继刻意保持保守：它不会修改 Codex 原生工具参数、
重写 Codex 线程记录，也不会拦截最终回答/Stop hooks。只有当你需要 ACP 运行时/会话模型时，才使用显式 ACP。嵌入式 Codex 支持边界记录在
[Codex harness v1 support contract](/zh-CN/plugins/codex-harness#v1-support-contract)
中。
原生 Codex 会话绑定是默认的聊天控制路径。OpenClaw 动态工具仍通过 OpenClaw 执行，而 Codex 原生工具（如 shell/apply-patch）则在 Codex 内执行。对于 Codex 原生工具事件，OpenClaw 会注入一个按轮次生效的原生 hook 中继，以便插件钩子可以拦截 `before_tool_call`、观察 `after_tool_call`，并通过 OpenClaw 审批机制路由 Codex `PermissionRequest` 事件。Codex 的 `Stop` 钩子会被中继到 OpenClaw 的 `before_agent_finalize`，此时插件可以在 Codex 最终输出答案前请求再进行一次模型调用。该中继刻意保持保守：它不会修改 Codex 原生工具参数，也不会重写 Codex 线程记录。只有当你想使用 ACP 运行时/会话模型时，才应显式使用 ACP。嵌入式 Codex 支持边界记录在 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) 中。
应路由到 ACP 运行时的自然语言触发示例：
以下自然语言触发词应路由到 ACP 运行时：
- “把这个任务作为一次性的 Claude Code ACP 会话运行，并总结结果。”
- “为这个任务使用 Gemini CLI 在线程中运行，然后把后续跟进保留在同一个线程里。”
- “这个任务使用 Gemini CLI 在线程中执行，然后后续继续在同一个线程里进行。”
- “通过 ACP 在线程后台运行 Codex。”
OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑定到当前会话或线程，并将后续跟进路由到该会话，直到关闭或过期。只有在明确要求 ACP/acpx，或所请求的操作无法使用原生 Codex 插件时，Codex 才会走这条路径。
OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持时绑定到当前会话或线程，并将后续消息路由到该会话，直到关闭或过期。只有在明确请求 ACP/acpx，或所请求操作无法使用原生 Codex 插件时，Codex 才会走这条路径。
对于 `sessions_spawn`，只有在 ACP 已启用、
请求方未处于沙箱隔离状态，且 ACP 运行时后端已加载时，才会声明 `runtime: "acp"`。
它面向 ACP harness id，例如 `codex`、`claude`、`gemini` 或 `opencode`。不要传入来自 `agents_list` 的普通 OpenClaw 配置智能体 id，除非该条目已明确配置为 `agents.list[].runtime.type="acp"`；否则应使用默认的子智能体运行时。当某个 OpenClaw 智能体配置了
`runtime.type="acp"` 时，OpenClaw 会使用 `runtime.acp.agent` 作为底层 harness id。
对于 `sessions_spawn`，只有在 ACP 已启用、请求方未处于沙箱隔离状态，并且 ACP 运行时后端已加载时，`runtime: "acp"` 才会被公布。它面向 `codex`、`claude`、`gemini` 或 `opencode` 等 ACP harness id。除非 `agents_list` 中的某个普通 OpenClaw 配置智能体条目明确设置了 `agents.list[].runtime.type="acp"`，否则不要传入它的 id；在其他情况下，请使用默认的子智能体运行时。当某个 OpenClaw 智能体配置了 `runtime.type="acp"` 时，OpenClaw 会使用 `runtime.acp.agent` 作为底层 harness id。
## ACP 与子智能体
当你需要外部 harness 运行时时，使用 ACP。当 `codex` 插件启用时，Codex 会话绑定/控制请使用原生 Codex app-server。当你需要 OpenClaw 原生的委派运行时，使用子智能体。
当你想使用外部 harness 运行时时，请使用 ACP。当 `codex` 插件启用并需要 Codex 会话绑定/控制时，请使用原生 Codex 应用服务器。当你想使用 OpenClaw 原生委派运行时，请使用子智能体。
| 区域 | ACP 会话 | 子智能体运行 |
| ------------- | ------------------------------------- | ---------------------------------- |
| 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 |
| 会话键 | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| 主要命令 | `/acp ...` | `/subagents ...` |
| 启动工具 | `sessions_spawn`，并使用 `runtime:"acp"` | `sessions_spawn`（默认运行时） |
| 生成工具 | `sessions_spawn`，配合 `runtime:"acp"` | `sessions_spawn`（默认运行时） |
另请参见 [子智能体](/zh-CN/tools/subagents)。
另见[子智能体](/zh-CN/tools/subagents)。
## ACP 如何运行 Claude Code
@ -106,46 +96,46 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑
1. OpenClaw ACP 会话控制平面
2. 内置 `acpx` 运行时插件
3. Claude ACP 适配器
4. Claude 侧的运行时/会话机制
4. Claude 侧运行时/会话机制
重要区别：
- ACP Claude 是一个 harness 会话，带有 ACP 控制、会话恢复、后台任务跟踪，以及可选的会话/线程绑定。
- ACP Claude 是一个 harness 会话，具备 ACP 控制、会话恢复、后台任务跟踪，以及可选的会话/线程绑定。
- CLI 后端是独立的纯文本本地回退运行时。参见 [CLI 后端](/zh-CN/gateway/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`、仓库检出目录、后端工作区）。它独立于聊天界面。
示例：
- `/codex bind` — 保留这个聊天，启动或附加原生 Codex app-server，并将未来消息路由到这里。
- `/codex model gpt-5.4`、`/codex fast on`、`/codex permissions yolo` — 在聊天中调整绑定的原生 Codex 线程。
- `/codex stop` 或 `/codex steer focus on the failing tests first` — 控制当前活跃的原生 Codex 轮次。
- `/acp spawn codex --bind here` — 针对 Codex 的显式 ACP 回退。
- `/acp spawn codex --thread auto` — OpenClaw 可能会创建子线程/话题并在那里绑定。
- `/acp spawn codex --bind here --cwd /workspace/repo` — 仍绑定在同一个聊天中，但 Codex 在 `/workspace/repo` 中运行。
- `/codex bind` —— 保留当前聊天，生成或附加原生 Codex 应用服务器，并将未来消息路由到这里。
- `/codex model gpt-5.4`、`/codex fast on`、`/codex permissions yolo` —— 直接从聊天中调优绑定的原生 Codex 线程。
- `/codex stop` 或 `/codex steer focus on the failing tests first` —— 控制当前活跃的原生 Codex 轮次。
- `/acp spawn codex --bind here` —— 对 Codex 使用显式 ACP 回退。
- `/acp spawn codex --thread auto` —— OpenClaw 可能创建一个子线程/话题并在那里绑定。
- `/acp spawn codex --bind here --cwd /workspace/repo` —— 保持当前聊天绑定，Codex 在 `/workspace/repo` 中运行。
说明：
- `--bind here` 和 `--thread ...` 互斥。
- `--bind here` 仅在声明支持当前会话绑定的渠道上有效；否则 OpenClaw 会返回清晰的不支持提示。绑定会在 Gateway 网关重启后继续保留。
- 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions`——对于 `--bind here` 则不需要。
- 如果你在不提供 `--cwd` 的情况下启动到另一个 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。继承路径缺失（`ENOENT`/`ENOTDIR`）时会回退到后端默认值；其他访问错误（例如 `EACCES`）则会作为启动错误直接显示。
- `--bind here` 仅适用于声明支持当前会话绑定的渠道；否则 OpenClaw 会返回明确的不支持提示。绑定在 Gateway 网关重启后仍会保留。
- 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions` —— 对于 `--bind here` 则不需要。
- 如果你在没有 `--cwd` 的情况下生成到不同的 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。若继承路径缺失（`ENOENT`/`ENOTDIR`），则回退到后端默认值；其他访问错误（例如 `EACCES`）会直接作为生成错误显示。
### 线程绑定会话
@ -154,15 +144,15 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑
- OpenClaw 将一个线程绑定到目标 ACP 会话。
- 该线程中的后续消息会路由到绑定的 ACP 会话。
- ACP 输出会回传到同一个线程。
- 取消聚焦/关闭/归档/空闲超时或最大生命周期到期时，绑定会被移除。
- 取消聚焦、关闭、归档、空闲超时或达到最大存活时间后，绑定会被移除。
线程绑定支持取决于适配器本身。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回明确的不支持/不可用提示。
线程绑定支持是适配器特定的。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回明确的不支持/不可用提示。
线程绑定 ACP 所需的功能开关：
- `acp.enabled=true`
- `acp.dispatch.enabled` 默认开启（设置为 `false` 可暂停 ACP 分发）
- 启用渠道适配器的 ACP 线程启动开关（适配器特定）
- `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发）
- 启用渠道适配器的 ACP 线程生成开关（适配器特定）
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
@ -171,8 +161,8 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑
- 任何暴露会话/线程绑定能力的渠道适配器。
- 当前内置支持：
- Discord 线程/渠道
- Telegram 话题（群组/超级群组中的论坛话题以及私信话题）
- 插件渠道也可以通过同样的绑定接口添加支持。
- Telegram 话题（群组/超级群组中的论坛话题，以及私信话题）
- 插件渠道也可以通过相同的绑定接口添加支持。
## 渠道特定设置
@ -180,15 +170,15 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑
### 绑定模型
- `bindings[].type="acp"` 标记一个持久化的 ACP 会话绑定。
- `bindings[].match` 标识目标会话：
- `bindings[].type="acp"` 表示一个持久化的 ACP 会话绑定。
- `bindings[].match` 用于标识目标会话：
- Discord 渠道或线程：`match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- 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:*>"`
对于稳定的群组绑定，优先使用 `chat_id:*`。
- `bindings[].agentId` 是所属的 OpenClaw 智能体 id。
- `bindings[].agentId` 是拥有该绑定的 OpenClaw 智能体 id。
- 可选的 ACP 覆盖项位于 `bindings[].acp` 下：
- `mode`（`persistent` 或 `oneshot`）
- `label`
@ -293,18 +283,18 @@ ACP 绑定会话的覆盖优先级：
行为：
- OpenClaw 会在使用前确保已存在配置好的 ACP 会话。
- OpenClaw 会确保配置的 ACP 会话在使用前已存在。
- 该渠道或话题中的消息会路由到配置好的 ACP 会话。
- 在绑定的会话中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话键。
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。
- 对于没有显式 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置中继承目标智能体的工作区。
- 继承的工作区路径缺失时，会回退到后端默认 `cwd`；非缺失的访问失败则会作为启动错误直接显示。
- 在已绑定的会话中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话键。
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然生效。
- 对于未显式指定 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置继承目标智能体的工作区。
- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败会作为生成错误返回。
## 启动 ACP 会话（接口）
### 来自 `sessions_spawn`
### 从 `sessions_spawn` 启动
使用 `runtime: "acp"` 从智能体轮次或工具调用中启动 ACP 会话。
使用 `runtime: "acp"` 从智能体轮次或工具调用中启动一个 ACP 会话。
```json
{
@ -318,28 +308,28 @@ ACP 绑定会话的覆盖优先级：
说明：
- `runtime` 默认是 `subagent`，因此对于 ACP 会话请显式设置 `runtime: "acp"`。
- 如果省略 `agentId`，则在已配置的情况下，OpenClaw 会使用 `acp.defaultAgent`。
- `runtime` 默认值是 `subagent`，因此对于 ACP 会话，需要显式设置 `runtime: "acp"`。
- 如果省略 `agentId`，OpenClaw 会在已配置时使用 `acp.defaultAgent`。
- `mode: "session"` 需要 `thread: true` 才能保持持久化的绑定会话。
接口详情：
接口细节：
- `task`（必填）：发送到 ACP 会话的初始提示。
- `task`（必填）：发送给 ACP 会话的初始提示。
- `runtime`（ACP 必填）：必须为 `"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 启动会在已配置时继承目标智能体的工作区；继承路径缺失时会回退到后端默认值，而真实访问错误会被直接返回。
- `label`（可选）：用于会话/banner 文本中的面向操作员标签。
- `cwd`（可选）：请求的运行时工作目录（由后端/运行时策略校验）。如果省略，ACP 生成会在已配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会被返回。
- `label`（可选）：在会话/banner 文本中使用的面向操作员的标签。
- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其会话历史。需要 `runtime: "acp"`。
- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式回传给请求方会话。
- 在可用时，接受的响应会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以对其执行 tail 来查看完整中继历史。
- `runTimeoutSeconds`（可选）：在 N 秒后中止 ACP 子轮次。`0` 会让该轮次走 Gateway 网关的无超时路径。相同的值会同时应用到 Gateway 网关运行和 ACP 运行时，这样卡住或配额耗尽的 harness 就不会无限期占用父智能体通道。
- `model`（可选）：ACP 子会话的显式模型覆盖。Codex ACP 启动会在 `session/new` 之前，将 OpenClaw Codex 引用（例如 `openai-codex/gpt-5.4`）规范化为 Codex ACP 启动配置；如 `openai-codex/gpt-5.4/high` 这类斜杠形式也会设置 Codex ACP 推理强度。其他 harness 必须声明 ACP `models` 并支持 `session/set_model`；否则 OpenClaw/acpx 会清晰报错，而不是静默回退到目标智能体默认值。
- `thinking`（可选）：ACP 子会话的显式 thinking/推理强度。对于 Codex ACP，`minimal` 会映射为低强度，`low`/`medium`/`high`/`xhigh` 会直接映射，而 `off` 会省略推理强度启动覆盖。
- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式传回请求方会话。
- 可用时，返回结果中可能包含 `streamLogPath`，指向一个按会话范围生成的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以对其执行 tail 以查看完整中继历史。
- `runTimeoutSeconds`（可选）：在 N 秒后中止 ACP 子轮次。`0` 会让该轮次走 Gateway 网关的无超时路径。同样的值会同时应用到 Gateway 网关运行和 ACP 运行时，避免卡住或额度耗尽的 harness 无限期占用父智能体通道。
- `model`（可选）：为 ACP 子会话显式覆盖模型。Codex ACP 生成会在 `session/new` 之前，将 OpenClaw 的 Codex 引用（例如 `openai-codex/gpt-5.4`）规范化为 Codex ACP 启动配置；带斜杠的形式（例如 `openai-codex/gpt-5.4/high`）还会设置 Codex ACP 的推理强度。其他 harness 必须声明 ACP `models` 并支持 `session/set_model`；否则 OpenClaw/acpx 会清晰失败，而不会静默回退到目标智能体默认值。
- `thinking`（可选）：为 ACP 子会话显式设置 thinking/推理强度。对于 Codex ACP，`minimal` 映射为低强度，`low`/`medium`/`high`/`xhigh` 直接映射，而 `off` 会省略推理强度启动覆盖。
## 交付模型
@ -347,42 +337,42 @@ 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 会话是后台子级，类似子智能体：
- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求执行工作。
- 子级在其自己的 ACP harness 会话中运行。
- 子级轮次运行在与原生子智能体启动相同的后台通道上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。
- 完成状态会通过内部任务完成通知路径回传。
- 当需要面向用户的回复时，父级会用正常的助手语气重写子级结果。
- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
- 子级在自己的 ACP harness 会话中运行。
- 子级轮次运行在与原生子智能体生成相同的后台通道上，因此较慢的 ACP harness 不会阻塞无关的主会话工作。
- 完成结果会通过内部任务完成通知路径回报。
- 当需要面向用户的回复时，父级会用正常 assistant 语气重写子级结果。
不要将此路径视为父级与子级之间的点对点聊天。子级已经拥有一个返回给父级的完成通道。
不要把这一路径视为父子之间的点对点聊天。子级已经有一个回传给父级的完成通道。
### `sessions_send` 和 A2A 交付
### `sessions_send` 与 A2A 交付
`sessions_send` 可以在启动后将消息发送到另一个会话。对于普通对等会话，OpenClaw 在注入消息后会使用智能体到智能体（A2A）的后续跟进路径：
`sessions_send` 可以在生成后将目标指向另一个会话。对于普通对等会话，在注入消息后，OpenClaw 会使用智能体到智能体（A2A）后续路径：
- 等待目标会话的回复
- 可选地让请求方和目标方进行有限次数的后续轮次交换
- 要求目标生成一条通知消息
- 将该通知投递到可见的渠道或线程
- 可选地让请求方和目标交换有限轮数的后续消息
- 要求目标生成一条 announce 消息
- 将该 announce 投递到可见渠道或线程
该 A2A 路径是对等发送的一种回退方式，用于发送方需要一个可见的后续结果时。当无关会话能够查看并向某个 ACP 目标发送消息时，例如在较宽松的 `tools.sessions.visibility` 设置下，它仍然保持启用。
该 A2A 路径是用于对等发送的一种回退机制，适用于发送方需要一个可见后续回复的情况。当一个无关会话在较宽泛的 `tools.sessions.visibility` 设置下可以看到并向 ACP 目标发送消息时，该机制仍保持启用。
只有当请求方是其自己所拥有的父级拥有的一次性 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
{
@ -395,28 +385,28 @@ ACP 会话既可以是交互式工作区，也可以是由父级拥有的后台
常见用例：
- 将一个 Codex 会话从你的笔记本电脑切换到手机——告诉你的智能体从你上次离开的地方继续
- 继续一个你在 CLI 中交互式启动、现在希望通过智能体以无头方式继续的编码会话
- 继续因 Gateway 网关重启或空闲超时而中断的工作
- 将 Codex 会话从你的笔记本电脑切换到手机 —— 告诉你的智能体从你上次中断的地方继续
- 继续一个你在 CLI 中交互式启动、现在想通过智能体以无头方式继续的编码会话
- 接续因 Gateway 网关重启或空闲超时而中断的工作
说明：
- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用，会返回错误。
- `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。
- `resumeSessionId` 会恢复上游 ACP 会话历史；你正在创建的新 OpenClaw 会话仍会正常应用 `thread` 和 `mode`，因此 `mode: "session"` 仍然需要 `thread: true`。
- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。
- 如果找不到该会话 ID，启动会以清晰错误失败——不会静默回退到新会话。
- 如果找不到该会话 ID，生成会以明确错误失败 —— 不会静默回退到新会话。
<Accordion title="部署后的冒烟测试">
<Accordion title="部署后冒烟测试">
在 Gateway 网关部署后，执行一次真实的端到端在线检查，而不要只依赖单元测试：
在 Gateway 网关部署后，执行一次真实的端到端检查，而不是只依赖单元测试：
1. 验证目标主机上的已部署 Gateway 网关版本和提交。
2. 打开一个临时的 ACPX 桥接会话，连接到在线智能体。
3. 要求该智能体调用 `sessions_spawn`，并使用 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务内容为 `Reply with exactly LIVE-ACP-SPAWN-OK`。
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. 清理临时桥接会话。
5. 清理这个临时桥接会话。
将门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"`——绑定线程的 `mode: "session"` 和流中继路径属于单独的、更丰富的集成测试阶段。
将该检查保持在 `mode: "run"`，并跳过 `streamTo: "parent"` —— 线程绑定的 `mode: "session"` 和流式中继路径属于另外更丰富的集成测试阶段。
</Accordion>
@ -426,16 +416,16 @@ 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"`。
- `sessions_spawn` 配合 `runtime: "acp"` 时不支持 `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` 命令启动
在需要时，使用 `/acp spawn` 从聊天中进行显式的操作员控制。
在需要时，使用 `/acp spawn` 从聊天中进行显式操作员控制。
```text
/acp spawn codex --mode persistent --thread auto
@ -452,7 +442,7 @@ ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内部。
- `--cwd <absolute-path>`
- `--label <name>`
参见 [Slash Commands](/zh-CN/tools/slash-commands)。
参见[斜杠命令](/zh-CN/tools/slash-commands)。
## 会话目标解析
@ -462,45 +452,45 @@ ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内部。
1. 显式目标参数（或 `/acp steer` 的 `--session`）
- 先尝试 key
- 然后尝试 UUID 形状的 session id
- 再尝试 label
2. 当前线程绑定（如果当前会话/线程已绑定到某个 ACP 会话）
- 然后尝试 UUID 形态的 session id
- 最后尝试 label
2. 当前线程绑定（如果当前会话/线程绑定到了某个 ACP 会话）
3. 当前请求方会话回退
当前会话绑定和线程绑定都会参与第 2 步。
如果无法解析任何目标，OpenClaw 会返回清晰的错误（`Unable to resolve session target: ...`）。
如果无法解析出目标，OpenClaw 会返回明确错误（`Unable to resolve session target: ...`）。
## 启动绑定模式
## 生成绑定模式
`/acp spawn` 支持 `--bind here|off`。
| 模式 | 行为 |
| ------ | ---------------------------------------------------------------------- |
| `here` | 原地绑定当前活跃会话；如果当前没有活跃会话则失败。 |
| `off` | 不创建当前会话绑定。 |
| `off` | 不创建当前会话绑定。 |
说明：
- `--bind here` 是“让这个渠道或聊天由 Codex 提供支持”的最简单操作路径。
- `--bind here` 不会创建子线程。
- `--bind here` 仅在暴露当前会话绑定支持的渠道上可用。
- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中同时使用。
- `--bind here` 仅适用于暴露当前会话绑定支持的渠道。
- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中组合使用。
## 启动线程模式
## 生成线程模式
`/acp spawn` 支持 `--thread auto|here|off`。
| 模式 | 行为 |
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | 在活跃线程中：绑定该线程。在非线程环境中：在支持时创建/绑定一个子线程。 |
| `here` | 要求当前处于活跃线程中；如果不在则失败。 |
| `off` | 不绑定。会话以未绑定状态启动。 |
| `auto` | 在活跃线程中：绑定该线程。在非线程环境中：如果支持，则创建并绑定一个子线程。 |
| `here` | 要求当前处于活跃线程中；如果不是则失败。 |
| `off` | 不绑定。会话以未绑定状态启动。 |
说明：
- 在非线程绑定界面上，默认行为实际上等同于 `off`。
- 线程绑定启动需要渠道策略支持：
- 在不支持线程绑定的界面上，默认行为实际上等同于 `off`。
- 线程绑定生成需要渠道策略支持：
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
- 如果你想固定当前会话而不创建子线程，请使用 `--bind here`。
@ -511,64 +501,63 @@ ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱内部。
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/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 steer` | 向运行中的会话发送 steer 指令。 | `/acp steer --session support inbox prioritize failing tests` |
| `/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 cwd` | 设置运行时工作目录覆盖。 | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | 设置审批策略配置。 | `/acp permissions strict` |
| `/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 model` | 设置运行时模型覆盖值。 | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | 移除会话运行时选项覆盖值。 | `/acp reset-options` |
| `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
| `/acp doctor` | 后端健康状态、能力、可执行修复。 | `/acp doctor` |
| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` |
| `/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` 提供了便捷命令和一个通用 setter。
等价操作：
- `/acp model <id>` 映射到运行时配置键 `model`。对于 Codex ACP，OpenClaw 会将 `openai-codex/<model>` 规范化为适配器模型 id，并将斜杠形式的推理后缀（如 `openai-codex/gpt-5.4/high`）映射到 Codex ACP 的 `reasoning_effort`。对于其他 harness，模型控制取决于适配器是否支持 ACP `models` 和 `session/set_model`。
- `/acp set thinking <level>` 映射到运行时配置键 `thinking`。对于 Codex ACP，只要适配器支持，OpenClaw 就会发送相应的 `reasoning_effort`。
- `/acp model <id>` 映射到运行时配置键 `model`。对于 Codex ACP，OpenClaw 会将 `openai-codex/<model>` 规范化为适配器模型 id，并将类似 `openai-codex/gpt-5.4/high` 这样的斜杠推理后缀映射为 Codex ACP 的 `reasoning_effort`。对于其他 harness，模型控制取决于适配器是否支持 ACP `models` 和 `session/set_model`。
- `/acp set thinking <level>` 映射到运行时配置键 `thinking`。对于 Codex ACP，在适配器支持时，OpenClaw 会发送相应的 `reasoning_effort`。
- `/acp permissions <profile>` 映射到运行时配置键 `approval_policy`。
- `/acp timeout <seconds>` 映射到运行时配置键 `timeout`。
- `/acp cwd <path>` 会直接更新运行时 `cwd` 覆盖。
- `/acp cwd <path>` 直接更新运行时 `cwd` 覆盖值。
- `/acp set <key> <value>` 是通用路径。
- 特殊情况：`key=cwd` 使用 `cwd` 覆盖路径。
- `/acp reset-options` 会清除目标会话的所有运行时覆盖项。
- `/acp reset-options` 会清除目标会话的所有运行时覆盖值。
## acpx harness、插件设置和权限
关于 acpx harness 配置（Claude Code / Codex / Gemini CLI 别名）、
plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参见
关于 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` | 后端插件缺失、被禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；如果设置了 `plugins.allow` allowlist，请将 `acpx` 包含进去，然后运行 `/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` | 智能体不在 allowlist 中。 | 使用被允许的 `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 runtime backend is not configured` | 后端插件缺失、被禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；如果设置了 `plugins.allow` 允许列表，请将 `acpx` 包含进去；然后运行 `/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`。 | 移动到目标聊天/渠道后重试，或使用不绑定的生成方式。 |
| `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.` | 当前绑定目标归其他用户所有。 | 由所有者重新绑定，或使用其他会话或线程。 |
| `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。 |
| `Cannot apply --model ... did not advertise model support` | 目标 harness 未暴露通用 ACP 模型切换支持。 | 使用声明了 ACP `models`/`session/set_model` 的 harness，使用 Codex ACP 模型引用，或如果该 harness 有自己的启动参数，则直接在其中配置模型。 |
| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已过期或被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见 [权限配置](/zh-CN/tools/acp-agents-setup#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。 |
| `Cannot apply --model ... did not advertise model support` | 目标 harness 未暴露通用 ACP 模型切换能力。 | 使用声明支持 ACP `models`/`session/set_model` 的 harness，使用 Codex ACP 模型引用，或如果该 harness 有自己的启动参数，则直接在 harness 中配置模型。 |
| Missing ACP metadata for bound session | ACP 会话元数据已过期或被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 |
| ACP session fails early with little output | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完全权限，设置 `permissionMode=approve-all`；如需优雅降级，设置 `nonInteractivePermissions=deny`。 |
| ACP session stalls indefinitely after completing work | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止陈旧进程。 |
## 相关内容

180
docs/zh-CN/tools/browser-control.md
View File

@ -1,30 +1,30 @@
---
read_when:
- 通过本地控制 API 对智能体浏览器进行脚本操作或调试
- 查找 `openclaw browser` CLI 参考
- 通过本地控制 API 对智能体浏览器进行脚本编写或调试
- 正在查找 `openclaw browser` CLI 参考文档
- 添加带有快照和 refs 的自定义浏览器自动化
summary: OpenClaw 浏览器控制 API、CLI 参考和脚本操作
title: 浏览器控制 API
x-i18n:
generated_at: "2026-04-25T10:48:37Z"
generated_at: "2026-04-26T00:28:48Z"
model: gpt-5.4
provider: openai
source_hash: 1515ca1e31e6fd8fd3e0f34f17ce309c52202e26ed3b79e24a460380efab040d
source_hash: ebec67dbef0c63ac91f46736d73ec6f0ac21d5214cfcc47f6b8071923fe718c1
source_path: tools/browser-control.md
workflow: 15
---
有关设置、配置和故障排除，请参阅 [Browser](/zh-CN/tools/browser)。
关于设置、配置和故障排除，请参阅 [Browser](/zh-CN/tools/browser)。
本页是本地控制 HTTP API、`openclaw browser`
CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档。
## 控制 API（可选）
仅用于本地集成时，Gateway 网关会公开一个小型 loopback HTTP API：
仅用于本地集成时，Gateway 网关会暴露一个小型 loopback HTTP API：
- Status / 启动 / 停止：`GET /`、`POST /start`、`POST /stop`
- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
- 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
- 快照 / 截图：`GET /snapshot`、`POST /screenshot`
- 快照/截图：`GET /snapshot`、`POST /screenshot`
- 操作：`POST /navigate`、`POST /act`
- 钩子：`POST /hooks/file-chooser`、`POST /hooks/dialog`
- 下载：`POST /download`、`POST /wait/download`
@ -35,23 +35,23 @@ CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档
- 状态：`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>`。`POST /start?headless=true` 会为本地托管配置请求一次性无头启动，而不会更改持久化的浏览器配置；仅附加、远程 CDP 和现有会话配置会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。
所有端点都接受 `?profile=<name>`。`POST /start?headless=true` 会为本地托管 profile 请求一次性无头启动，而不会更改持久化的浏览器配置；attach-only、远程 CDP 和 existing-session profiles 会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。
如果配置了共享密钥 Gateway 网关身份验证，浏览器 HTTP 路由也需要身份验证：
如果配置了共享密钥 Gateway 网关认证，浏览器 HTTP 路由也需要认证：
- `Authorization: Bearer <gateway token>`
- `x-openclaw-password: <gateway password>`，或使用该密码的 HTTP Basic auth
- `x-openclaw-password: <gateway password>` 或使用该密码的 HTTP Basic 认证
注意：
- 这个独立的 loopback 浏览器 API **不会**使用 trusted-proxy 或
- 这个独立的 loopback 浏览器 API **不会** 使用可信代理或
Tailscale Serve 身份标头。
- 如果 `gateway.auth.mode` 为 `none` 或 `trusted-proxy`，这些 loopback 浏览器
路由不会继承这些携带身份信息的模式；请将它们保持为仅 loopback 可访问。
- 如果 `gateway.auth.mode` 是 `none` 或 `trusted-proxy`，这些 loopback 浏览器
路由也不会继承这些带有身份信息的模式；请将它们限制为仅 loopback 使用。
### `/act` 错误契约
### `/act` 错误约定
`POST /act` 对路由级验证和策略失败使用结构化错误响应：
`POST /act` 对路由级校验和策略失败使用结构化错误响应：
```json
{ "error": "<message>", "code": "ACT_*" }
@ -59,31 +59,31 @@ CLI 以及脚本模式（快照、refs、等待、调试流程）的参考文档
当前 `code` 值：
- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或无法识别。
- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载归一化或验证失败。
- `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）：现有会话配置不支持该操作。
- `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>" }`，但不带
其他运行时失败仍可能返回 `{ "error": "<message>" }`，而不包含
`code` 字段。
### Playwright 要求
某些功能（navigate / act / AI 快照 / 角色快照、元素截图、
某些功能（navigate/act/AI 快照/角色快照、元素截图、
PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回
明确的 501 错误。
未安装 Playwright 时仍可用的功能：
在没有 Playwright 的情况下，以下功能仍然可用：
- ARIA 快照
- 当每个标签页都有可用的 CDP
WebSocket 时，对托管的 `openclaw` 浏览器进行页面截图
- 对 `existing-session` / Chrome MCP 配置进行页面截图
- 从快照输出中进行 `existing-session` 基于 ref 的截图（`--ref`）
- 当每个标签页的 CDP
WebSocket 可用时，托管 `openclaw` 浏览器的页面截图
- `existing-session` / Chrome MCP profiles 的页面截图
- 来自快照输出的 `existing-session` 基于 ref 的截图（`--ref`）
仍然需要 Playwright 的功能：
以下功能仍然需要 Playwright：
- `navigate`
- `act`
@ -100,37 +100,37 @@ not supported for element screenshots`。
#### Docker Playwright 安装
如果你的 Gateway 网关在 Docker 中运行，请避免使用 `npx playwright`（会有 npm 覆盖冲突）。
请改用内置的 CLI：
如果你的 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`（例如，
要持久化浏览器下载内容，请设置 `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 的操作。智能体看到的是一个稳定接口，而底层的本地 / 远程浏览器和配置可以自由切换。
一个小型 loopback 控制服务器接收 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（点击/输入/快照/PDF）通过位于 CDP 之上的 Playwright 完成；当缺少 Playwright 时，只有非 Playwright 操作可用。智能体看到的是一个稳定的接口，而底层的本地/远程浏览器和 profiles 可以自由切换。
## CLI 快速参考
所有命令都接受 `--browser-profile <name>` 以定位到特定配置，并支持 `--json` 以输出机器可读格式。
所有命令都接受 `--browser-profile <name>` 来指定特定 profile，并接受 `--json` 以输出机器可读格式。
<AccordionGroup>
<Accordion title="基础：状态、标签页、打开 / 聚焦 / 关闭">
<Accordion title="基础：状态、标签页、打开/聚焦/关闭">
```bash
openclaw browser status
openclaw browser start
openclaw browser start --headless # 一次性本地托管无头启动
openclaw browser stop # 也会清除仅附加 / 远程 CDP 上的模拟设置
openclaw browser stop # 也会清除 attach-only/远程 CDP 上的仿真
openclaw browser tabs
openclaw browser tab # 当前标签页快捷方式
openclaw browser tab # 当前标签页的快捷方式
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
@ -170,7 +170,7 @@ openclaw browser responsebody "**/api" --max-chars 5000
```bash
openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double # 或 e12 用于角色 refs
openclaw browser click 12 --double # 或对角色 refs 使用 e12
openclaw browser click-coords 120 340 # 视口坐标
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
@ -204,7 +204,7 @@ 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 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
@ -218,19 +218,23 @@ openclaw browser set device "iPhone 14"
注意：
- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器 / 对话框的 click / press 之前运行它们。
- `click` / `type` / 等操作需要来自 `snapshot` 的 `ref`（数字 `12`、角色 ref `e12` 或可操作的 ARIA ref `ax12`）。操作有意不支持 CSS 选择器。当可见视口位置是唯一可靠目标时，请使用 `click-coords`。
- 下载、trace 和 upload 路径被限制在 OpenClaw 临时根目录下：`/tmp/openclaw{,/downloads,/uploads}`（回退为 `${os.tmpdir()}/openclaw/...`）。
- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入框。
- `upload` 和 `dialog` 是**预设**调用；请在触发文件选择器/对话框的 click/press 之前运行它们。
- `click`/`type`/等操作需要来自 `snapshot` 的 `ref`（数字 `12`、角色 ref `e12` 或可执行的 ARIA ref `ax12`）。操作有意不支持 CSS 选择器。当可见视口位置是唯一可靠目标时，请使用 `click-coords`。
- 下载、trace 和上传路径被限制在 OpenClaw 临时根目录下：`/tmp/openclaw{,/downloads,/uploads}`（回退为：`${os.tmpdir()}/openclaw/...`）。
- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。
当 OpenClaw
能够证明替换后的标签页时，例如 URL 相同，或者表单提交后单个旧标签页变成单个新标签页，稳定的标签页 id 和标签在 Chromium 原始目标替换后仍可保留。原始 target ids 仍然是易变的；在脚本中请优先使用来自 `tabs` 的
`suggestedTargetId`。
快照标志速览：
- `--format ai`（安装 Playwright 时的默认值）：带数字 refs 的 AI 快照（`aria-ref="<n>"`）。
- `--format aria`：带 `axN` refs 的无障碍树。安装 Playwright 时，OpenClaw 会通过后端 DOM id 将 refs 绑定到实时页面，以便后续操作可以使用它们；否则请将输出仅视为检查用途。
- `--efficient`（或 `--mode efficient`）：紧凑角色快照预设。设置 `browser.snapshotDefaults.mode: "efficient"` 可将其设为默认值（参见 [Gateway 配置](/zh-CN/gateway/configuration-reference#browser)）。
- `--format aria`：带 `axN` refs 的无障碍树。当 Playwright 可用时，OpenClaw 会将 refs 通过后端 DOM ids 绑定到活动页面，以便后续操作可以使用它们；否则请将输出仅视为检查用途。
- `--efficient`（或 `--mode efficient`）：紧凑角色快照预设。设置 `browser.snapshotDefaults.mode: "efficient"` 可将其设为默认值（请参阅 [Gateway 配置](/zh-CN/gateway/configuration-reference#browser)）。
- `--interactive`、`--compact`、`--depth`、`--selector` 会强制生成带 `ref=e12` refs 的角色快照。`--frame "<iframe>"` 会将角色快照限定到某个 iframe。
- `--labels` 会添加一张仅视口截图，并叠加 ref 标签（输出 `MEDIA:<path>`）。
- `--urls` 会将发现的链接目标追加到 AI 快照中。
- `--labels` 会添加带叠加 ref 标签的仅视口截图（打印 `MEDIA:<path>`）。
- `--urls` 会将发现的链接目标地址附加到 AI 快照中。
## 快照和 refs
@ -241,40 +245,42 @@ OpenClaw 支持两种“快照”样式：
- 操作：`openclaw browser click 12`、`openclaw browser type 23 "hello"`。
- 在内部，ref 通过 Playwright 的 `aria-ref` 解析。
- **角色快照（如 `e12` 这样的角色 refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
- 输出：带 `[ref=e12]`（以及可选 `[nth=1]`）的基于角色的列表 / 树。
- **角色快照（如 `e12` 的角色 refs）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
- 输出：基于角色的列表/树，带有 `[ref=e12]`（以及可选的 `[nth=1]`）。
- 操作：`openclaw browser click e12`、`openclaw browser highlight e12`。
- 在内部，ref 通过 `getByRole(...)` 解析（重复项还会配合 `nth()`）。
- 添加 `--labels` 可包含一张叠加 `e12` 标签的视口截图。
- 在内部，ref 通过 `getByRole(...)` 解析（重复项再加 `nth()`）。
- 添加 `--labels` 可包含带叠加 `e12` 标签的视口截图。
- 当链接文本有歧义且智能体需要明确的
导航目标时，添加 `--urls`。
导航目标时，请添加 `--urls`。
- **ARIA 快照（如 `ax12` 这样的 ARIA refs）**：`openclaw browser snapshot --format aria`
- 输出：以结构化节点形式表示的无障碍树。
- 操作：当快照路径能够通过 Playwright 和 Chrome 后端 DOM id 绑定
该 ref 时，`openclaw browser click ax12` 可以工作。
- 如果 Playwright 不可用，ARIA 快照仍然可用于
检查，但 refs 可能不可操作。当你需要可操作 refs 时，请使用 `--format ai`
- **ARIA 快照（如 `ax12` 的 ARIA refs）**：`openclaw browser snapshot --format aria`
- 输出：作为结构化节点的无障碍树。
- 操作：当快照路径可以通过 Playwright 和 Chrome 后端 DOM ids 绑定
ref 时，`openclaw browser click ax12` 可正常工作。
- 如果 Playwright 不可用，ARIA 快照仍可用于
检查，但 refs 可能无法执行操作。当你需要可操作 refs 时，请使用 `--format ai`
或 `--interactive` 重新生成快照。
ref 行为：
- refs **不会在导航之间保持稳定**；如果某项操作失败，请重新运行 `snapshot` 并使用新的 ref。
- 如果角色快照是使用 `--frame` 获取的，则角色 refs 会限定在该 iframe 内，直到下一次角色快照。
- 未知或过期的 `axN` refs 会快速失败，而不会退回到
Playwright 的 `aria-ref` 选择器。发生这种情况时，请在同一标签页上重新运行一次快照。
- refs **不会在导航后保持稳定**；如果失败，请重新运行 `snapshot` 并使用新的 ref。
- 当 `/act` 能够证明操作触发后的替换标签页时，它会返回当前原始 `targetId`
。后续命令请继续使用稳定的标签页 ids/标签。
- 如果角色快照是使用 `--frame` 获取的，那么角色 refs 会限定在该 iframe 内，直到下一次角色快照。
- 未知或过期的 `axN` refs 会快速失败，而不会继续回退到
Playwright 的 `aria-ref` 选择器。出现这种情况时，请在同一标签页上运行新的快照。
## 等待增强功能
## Wait 增强功能
你可以等待的不只是时间 / 文本：
你可以等待的不只是时间/文本：
- 等待 URL（支持 Playwright 的 glob）：
- 等待 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"`
这些条件可以组合使用：
@ -289,18 +295,18 @@ openclaw browser wait "#main" \
## 调试工作流
当某个操作失败时（例如“不可见”“严格模式冲突”“被遮挡”）：
当某个操作失败时（例如“not visible”“strict mode violation”“covered”）：
1. `openclaw browser snapshot --interactive`
2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用角色 refs）
3. 如果仍然失败：运行 `openclaw browser highlight <ref>` 查看 Playwright 实际定位的目标
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>`）
- 复现问题
- `openclaw browser trace stop`（会打印 `TRACE:<path>`）
## JSON 输出
@ -315,35 +321,35 @@ openclaw browser requests --filter api --json
openclaw browser cookies --json
```
JSON 格式的角色快照包含 `refs` 以及一个小型 `stats` 块（lines / chars / refs / interactive），以便工具推断负载大小和密度。
JSON 格式的角色快照包含 `refs` 以及一个小型 `stats` 块（lines/chars/refs/interactive），以便工具判断负载大小和密度。
## 状态和环境调节项
这些对于“让站点表现得像 X”这类工作流很有用：
这些功能适用于“让站点表现得像 X 一样”的工作流：
- Cookies：`cookies`、`cookies set`、`cookies clear`
- Storage：`storage local|session get|set|clear`
- Offline：`set offline on|off`
- 离线：`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 / 视口：
- HTTP Basic 认证：`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 浏览器配置可能包含已登录会话；请将其视为敏感信息。
- `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 端点功能强大；请通过隧道并加以保护。
这一行为。如果你不需要它，请使用 `browser.evaluateEnabled=false` 将其禁用。
- 关于登录和反机器人说明（X/Twitter 等），请参阅 [Browser login + X/Twitter posting](/zh-CN/tools/browser-login)。
- 请保持 Gateway 网关/节点主机为私有（仅 loopback 或仅 tailnet）。
- 远程 CDP 端点功能强大；请通过隧道进行访问并做好保护。
严格模式示例（默认阻止私有 / 内部目标）：
严格模式示例（默认阻止私有/内部目标地址）：
```json5
{
@ -359,7 +365,7 @@ JSON 格式的角色快照包含 `refs` 以及一个小型 `stats` 块（lines /
## 相关内容
- [Browser](/zh-CN/tools/browser) — 概览、配置、配置文件、安全
- [Browser login](/zh-CN/tools/browser-login) — 登录站点
- [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)

210
docs/zh-CN/tools/plugin.md
View File

@ -2,25 +2,25 @@
read_when:
- 安装或配置插件
- 了解插件发现和加载规则
- 使用与 Codex / Claude 兼容的插件捆绑包
- 使用与 Codex/Claude 兼容的插件包
sidebarTitle: Install and Configure
summary: 安装、配置和管理 OpenClaw 插件
title: 插件
x-i18n:
generated_at: "2026-04-26T00:16:09Z"
generated_at: "2026-04-26T00:29:26Z"
model: gpt-5.4
provider: openai
source_hash: 553c70416b9787437d46b3bd6f35570e532a3694c6c52d5d70e5014beed4328a
source_hash: b87c861ba38215bb3cf134356f4f630ea4a08ffcd63b8e8a8ad697f9b66fe2c0
source_path: tools/plugin.md
workflow: 15
---
插件通过新增功能来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些则是**外部**插件（由社区发布到 npm）。
插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、Agent harnesses、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是 **core**（随 OpenClaw 一起发布），另一些是 **external**（由社区在 npm 上发布）。
## 快速开始
<Steps>
<Step title="查看已加载内容">
<Step title="查看已加载的内容">
```bash
openclaw plugins list
```
@ -48,7 +48,7 @@ x-i18n:
</Step>
</Steps>
如果你更喜欢聊天原生控制方式，启用 `commands.plugins: true`，然后使用：
如果你更喜欢原生聊天控制方式，请启用 `commands.plugins: true` 并使用：
```text
/plugin install clawhub:@openclaw/voice-call
@ -56,17 +56,11 @@ x-i18n:
/plugin enable voice-call
```
安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，其次回退到 npm）。
安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，然后回退到 npm）。
如果配置无效，安装通常会以失败关闭的方式结束，并提示你使用
`openclaw doctor --fix`。唯一的恢复例外是一条较窄的内置插件重装路径，适用于选择加入
`openclaw.install.allowInvalidConfigRecovery`
的插件。
如果配置无效，安装通常会默认失败并提示你运行 `openclaw doctor --fix`。唯一的恢复例外是针对选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件，提供一条受限的内置插件重新安装路径。
打包分发的 OpenClaw 安装不会急切安装每个内置插件的全部运行时依赖树。当一个由 OpenClaw 拥有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于激活状态时，启动修复只会在导入该插件之前修复它所声明的运行时依赖。显式禁用仍然优先：`plugins.entries.<id>.enabled: false`、
`plugins.deny`、`plugins.enabled: false` 和 `channels.<id>.enabled: false`
都会阻止该插件/渠道的自动内置运行时依赖修复。外部插件和自定义加载路径仍然必须通过
`openclaw plugins install` 安装。
打包版 OpenClaw 安装不会急切安装每个内置插件的完整运行时依赖树。当某个 OpenClaw 自有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动修复只会在导入该插件之前修复它所声明的运行时依赖。显式禁用仍然优先：`plugins.entries.<id>.enabled: false`、`plugins.deny`、`plugins.enabled: false` 和 `channels.<id>.enabled: false` 会阻止该插件/渠道的自动内置运行时依赖修复。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
## 插件类型
@ -74,13 +68,12 @@ OpenClaw 可识别两种插件格式：
| 格式 | 工作方式 | 示例 |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **捆绑包** | 与 Codex / Claude / Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
两者都会显示在 `openclaw plugins list` 中。捆绑包详情请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。
两者都会显示在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参阅 [插件包](/zh-CN/plugins/bundles)。
如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins)
和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
## 官方插件
@ -95,7 +88,7 @@ OpenClaw 可识别两种插件格式：
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
### 核心（随 OpenClaw 提供）
### Core（随 OpenClaw 一起发布）
<AccordionGroup>
<Accordion title="模型提供商（默认启用）">
@ -107,8 +100,8 @@ OpenClaw 可识别两种插件格式：
</Accordion>
<Accordion title="Memory 插件">
- `memory-core` — 内置 memory 搜索（通过 `plugins.slots.memory` 默认启用）
- `memory-lancedb` — 按需安装的长期 memory，带自动召回/捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`）
- `memory-core` — 内置的 Memory 搜索（默认通过 `plugins.slots.memory` 使用）
- `memory-lancedb` — 按需安装的长期 Memory，带自动召回/捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`）
</Accordion>
<Accordion title="语音提供商（默认启用）">
@ -117,7 +110,7 @@ OpenClaw 可识别两种插件格式：
<Accordion title="其他">
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接插件（默认禁用）
- `copilot-proxy` — VS Code Copilot Proxy bridge（默认禁用）
</Accordion>
</AccordionGroup>
@ -139,29 +132,28 @@ OpenClaw 可识别两种插件格式：
}
```
| 字段 | 描述 |
| 字段 | 说明 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | 主开关（默认：`true`） |
| `enabled` | 主开关（默认值：`true`） |
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；拒绝优先） |
| `load.paths` | 额外的插件文件/目录 |
| `slots` | 排他性 slot 选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 按插件分别设置的开关 + 配置 |
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 按插件的开关 + 配置 |
配置更改**需要重启网关**。如果 Gateway 网关正以启用配置监听和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入完成后，通常会在稍后自动执行重启。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在你希望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 provider / 运行时钩子生效之前，请重启正在服务实时渠道的 Gateway 网关进程。
配置更改 **需要重启 gateway**。如果 Gateway 网关在启用配置监听和进程内重启的情况下运行（默认的 `openclaw gateway` 路径），那么通常会在配置写入完成后不久自动执行重启。对于原生插件运行时代码或生命周期钩子，没有受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 provider/运行时钩子生效之前，请重启正在服务实时渠道的 Gateway 网关进程。
`openclaw plugins list` 是本地插件注册表/配置快照。其中某个插件显示为
`enabled`，表示持久化注册表和当前配置允许该插件参与运行。但这并不能证明一个已经在运行的远程 Gateway 网关子进程已经重启并加载了相同的插件代码。在 VPS / 容器部署中，如果使用了包装进程，请将重启信号发送给实际的 `openclaw gateway run` 进程，或者对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
`openclaw plugins list` 是本地插件注册表/配置快照。那里显示为 `enabled` 的插件意味着持久化注册表和当前配置允许该插件参与运行。它并不能证明某个已经运行的远程 Gateway 网关子进程已经重启并加载了相同的插件代码。在 VPS/容器部署中，如果存在包装进程，请将重启发送给实际的 `openclaw gateway run` 进程，或对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
<Accordion title="插件状态：已禁用、缺失、无效">
<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
- **缺失**：配置引用了某个插件 id，但设备发现未找到它。
- **缺失**：配置引用了某个插件 ID，但发现流程未找到它。
- **无效**：插件存在，但其配置与声明的 schema 不匹配。
</Accordion>
## 设备发现和优先级
## 发现与优先级
OpenClaw 按以下顺序扫描插件（先匹配者优先）：
OpenClaw 会按以下顺序扫描插件（先匹配者优先）：
<Steps>
<Step title="配置路径">
@ -177,7 +169,7 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
</Step>
<Step title="内置插件">
随 OpenClaw 一起提供。许多插件默认启用（模型提供商、语音）。
随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。
其他插件则需要显式启用。
</Step>
</Steps>
@ -187,33 +179,24 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
- `plugins.enabled: false` 会禁用所有插件
- `plugins.deny` 始终优先于 allow
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
- 来自工作区的插件**默认禁用**（必须显式启用）
- 来自工作区的插件 **默认禁用**（必须显式启用）
- 内置插件遵循内建的默认启用集合，除非被覆盖
- 排他性 slot 可以强制启用该 slot 所选中的插件
- 某些内置的可选加入插件会在配置命名了某个由插件拥有的功能面时自动启用，例如 provider 模型引用、渠道配置或 harness 运行时
- OpenAI 系列的 Codex 路由保持独立的插件边界：
`openai-codex/*` 属于 OpenAI 插件，而内置的 Codex
app-server 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版
`codex/*` 模型引用来选择
- 独占槽位可以为该槽位强制启用所选插件
- 某些选择加入的内置插件会在配置命名了某个插件自有表面时自动启用，例如 provider 模型引用、渠道配置或 harness 运行时
- OpenAI 系列 Codex 路由保持独立的插件边界：
`openai-codex/*` 属于 OpenAI 插件，而内置的 Codex app-server 插件则由 `embeddedHarness.runtime: "codex"` 或旧版 `codex/*` 模型引用选择
## 运行时钩子故障排除
如果某个插件出现在 `plugins list` 中，但 `register(api)` 的副作用或钩子没有在实时聊天流量中运行，请先检查以下内容：
如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子在实时聊天流量中没有运行，请先检查以下内容：
- 运行 `openclaw gateway status --deep --require-rpc`，并确认当前活动的
Gateway 网关 URL、配置文件、配置路径和进程，正是你正在编辑的那些。
- 在插件安装/配置/代码更改后重启在线 Gateway 网关。在包装容器中，
PID 1 可能只是一个 supervisor；请重启或向子进程
`openclaw gateway run` 发送信号。
- 使用 `openclaw plugins inspect <id> --json` 确认钩子注册和诊断信息。非内置的会话钩子，例如 `llm_input`、
`llm_output` 和 `agent_end`，需要
`plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体回合的模型解析之前运行；`llm_output` 只会在一次模型尝试生成 assistant 输出后才运行。
- 要证明有效的会话模型，请使用 `openclaw sessions` 或
Gateway 网关的 session / Status 功能面；调试 provider 负载时，可使用
`--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
- 运行 `openclaw gateway status --deep --require-rpc`，确认当前活动的 Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的那些。
- 在插件安装/配置/代码更改后，重启正在运行的 Gateway 网关。在包装容器中，PID 1 可能只是一个监督进程；请重启或发送信号给子进程 `openclaw gateway run`。
- 使用 `openclaw plugins inspect <id> --json` 确认钩子注册和诊断信息。像 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end` 这样的非内置会话钩子需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在某次模型尝试产生助手输出之后运行。
- 若要证明会话实际使用的模型，请使用 `openclaw sessions` 或 Gateway 网关的会话/状态表面；在调试 provider 负载时，请用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
### 重复的渠道或工具归属
### 重复的渠道或工具所有权
症状：
@ -221,63 +204,62 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
这表示有多个已启用插件正试图拥有同一个渠道、设置流程或工具名称。最常见的原因是，某个外部渠道插件与现已提供相同渠道 id 的内置插件同时安装。
这意味着有多个已启用插件试图拥有同一个渠道、设置流程或工具名称。最常见的原因是某个外部渠道插件与一个现已提供相同渠道 ID 的内置插件同时安装。
调试步骤：
- 运行 `openclaw plugins list --enabled --verbose` 以查看每个已启用插件及其来源。
- 对每个可疑插件运行 `openclaw plugins inspect <id> --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。
- 在安装或移除插件包后运行 `openclaw plugins registry --refresh`，使持久化元数据反映当前安装状态。
- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件及其来源。
- 对每个可疑插件运行 `openclaw plugins inspect <id> --json`，比较 `channels`、`channelConfigs`、`tools` 和诊断信息。
- 在安装或移除插件包之后运行 `openclaw plugins registry --refresh`，使持久化元数据反映当前安装状态。
- 在安装、注册表或配置更改后重启 Gateway 网关。
修复选项：
- 如果一个插件有意替换另一个使用相同渠道 id 的插件，则首选插件应声明 `channelConfigs.<channel-id>.preferOver`，其值为较低优先级插件的 id。请参阅 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。
- 如果重复是意外造成的，可通过
`plugins.entries.<plugin-id>.enabled: false` 禁用其中一方，或移除过期的插件安装。
- 如果你显式启用了两个插件，OpenClaw 会保留这一请求并报告冲突。请为该渠道选择一个所有者，或重命名由插件拥有的工具，以确保运行时功能面明确无歧义。
- 如果某个插件有意替换另一个插件的相同渠道 ID，首选插件应声明 `channelConfigs.<channel-id>.preferOver`，其值为较低优先级插件的 ID。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。
- 如果重复是意外的，请使用 `plugins.entries.<plugin-id>.enabled: false` 禁用其中一方，或移除陈旧的插件安装。
- 如果你显式启用了两个插件，OpenClaw 会保留这一请求并报告冲突。请为该渠道选择一个所有者，或重命名插件自有工具，以确保运行时表面明确无歧义。
## 插件 slots（排他性类别）
## 插件槽位（独占类别）
某些类别是排他的（同一时间只能有一个处于激活状态）：
某些类别是独占的（一次只能有一个处于活动状态）：
```json5
{
plugins: {
slots: {
memory: "memory-core", // 或使用 "none" 禁用
contextEngine: "legacy", // 或填写某个插件 id
memory: "memory-core", // 或 "none" 以禁用
contextEngine: "legacy", // 或某个插件 ID
},
},
}
```
| Slot | 控制内容 | 默认值 |
| 槽位 | 控制内容 | 默认值 |
| --------------- | --------------------- | ------------------- |
| `memory` | 活跃的 memory 插件 | `memory-core` |
| `contextEngine` | 活跃的上下文引擎 | `legacy`（内建） |
| `memory` | 活动的 Memory 插件 | `memory-core` |
| `contextEngine` | 活动的上下文引擎 | `legacy`（内建） |
## CLI 参考
```bash
openclaw plugins list # 精简清单
openclaw plugins list --enabled # 仅显示已启用插件
openclaw plugins list # 紧凑清单
openclaw plugins list --enabled # 仅显示已启用的插件
openclaw plugins list --verbose # 每个插件的详细信息行
openclaw plugins list --json # 机器可读的清单
openclaw plugins list --json # 机器可读清单
openclaw plugins inspect <id> # 深度详情
openclaw plugins inspect <id> --json # 机器可读
openclaw plugins inspect --all # 全量表格
openclaw plugins inspect <id> --json # 机器可读格式
openclaw plugins inspect --all # 全量范围表格
openclaw plugins info <id> # inspect 的别名
openclaw plugins doctor # 诊断
openclaw plugins registry # 查看持久化注册表状态
openclaw plugins registry # 检查持久化注册表状态
openclaw plugins registry --refresh # 重建持久化注册表
openclaw doctor --fix # 修复插件注册表状态
openclaw plugins install <package> # 安装（优先 ClawHub，其次 npm）
openclaw plugins install <package> # 安装（优先 ClawHub，然后 npm）
openclaw plugins install clawhub:<pkg> # 仅从 ClawHub 安装
openclaw plugins install <spec> --force # 覆盖现有安装
openclaw plugins install <path> # 从本地路径安装
openclaw plugins install -l <path> # 为开发创建链接（不复制）
openclaw plugins install -l <path> # 链接（不复制），用于开发
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin # 记录精确解析后的 npm spec
@ -294,34 +276,32 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
内置插件随 OpenClaw 一起提供。许多插件默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。
内置插件随 OpenClaw 一起发布。许多默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要 `openclaw plugins enable <id>`。
`--force` 会就地覆盖现有已安装的插件或 hook 包。对于已跟踪 npm
插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标位置。
`--force` 会原地覆盖现有已安装的插件或 hook pack。对于已跟踪的 npm 插件的日常升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。
当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用插件之前，先将已安装的插件 id 添加到该允许列表中，因此重启后安装内容可立即被加载。
当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用插件之前，把已安装插件的 ID 添加到该允许列表中，因此重启后即可立即加载。
OpenClaw 会维护一个持久化的本地插件注册表，作为插件清单、贡献归属以及启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程在改变插件状态后都会刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过期或无效，`openclaw plugins registry
--refresh` 会根据安装记录、配置策略以及清单/包元数据重建其清单视图，而无需加载插件运行时模块。`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，并为后续更新记录新的 spec。传入不带版本的包名时，会将已精确 pin 的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的构件身份，OpenClaw 会跳过本次更新，不会下载、重新安装或重写配置。
OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献所有权和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程在更改插件状态后都会刷新该注册表。相同的 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的 manifest 元数据。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会根据安装记录、配置策略以及 manifest/package 元数据重建其 manifest 视图，而不会加载插件运行时模块。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，并记录新的 spec 供后续更新使用。传入不带版本的包名时，会把一个精确 pin 的安装移回注册表默认的发布线。如果已安装的 npm 插件已经匹配解析出的版本和记录的制品标识，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。
`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续执行，但仍不会绕过插件 `before_install` 策略拦截，也不会绕过扫描失败阻断。
`--dangerously-force-unsafe-install` 是用于内置危险代码扫描器误报时的破窗式覆盖开关。它允许插件安装和插件更新绕过内置的 `critical` 发现继续进行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖；而 `openclaw skills install` 仍是独立的 ClawHub Skills 下载/安装流程。
这个 CLI 标志仅适用于插件安装/更新流程。依赖 Gateway 网关的 Skills 依赖安装则改用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是单独的 ClawHub Skills 下载/安装流程。
兼容的捆绑包会参与相同的插件 list / inspect / enable / disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 以及由清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
兼容的 bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP server 条目。
`openclaw plugins inspect <id>` 还会报告已检测到的 bundle 能力，以及由 bundle 支持的或不受支持的 MCP 和 LSP server 条目。
Marketplace 源可以是来自
`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、像 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL，或者 git URL。对于远程 marketplace，插件条目必须保持在克隆后的 marketplace 仓库内部，并且只能使用相对路径源。
Marketplace 源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内部，并且只能使用相对路径源。
完整详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
完整详情请参见 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
## 插件 API 概览
原生插件会导出一个入口对象，其中暴露 `register(api)`。旧版插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
```typescript
export default definePluginEntry({
@ -341,21 +321,21 @@ export default definePluginEntry({
});
```
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧版插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。
`api.registrationMode` 会告诉插件其入口为何被加载：
`api.registrationMode` 会告诉插件它的入口为何被加载：
| 模式 | 含义 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由以及其他实时副作用。 |
| `discovery` | 只读能力发现。注册 provider 和元数据；可信的插件入口代码可能会被加载，但应跳过实时副作用。 |
| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 |
| `setup-runtime` | 加载渠道设置，且同时需要运行时入口。 |
| `discovery` | 只读能力发现。注册 provider 和元数据；受信任的插件入口代码可能会被加载，但应跳过实时副作用。 |
| `setup-only` | 通过轻量级 setup 入口加载渠道 setup 元数据。 |
| `setup-runtime` | 加载渠道 setup，且同时需要运行时入口。 |
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
会打开套接字、数据库、后台工作线程或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 来保护这些副作用。设备发现加载与激活加载分别缓存，且不会替换正在运行的 Gateway 网关注册表。设备发现是非激活式的，但并非免导入：OpenClaw 可能会评估可信的插件入口或渠道插件模块，以构建快照。请保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
会打开 socket、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 来保护这些副作用。发现加载与激活加载分别缓存，且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，而不是免导入的：OpenClaw 可能会执行受信任的插件入口或渠道插件模块来构建快照。请保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动放到完整运行时路径之后。
常见注册方法：
常见的注册方法：
| 方法 | 注册内容 |
| --------------------------------------- | --------------------------- |
@ -370,33 +350,31 @@ OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api
| `registerImageGenerationProvider` | 图像生成 |
| `registerMusicGenerationProvider` | 音乐生成 |
| `registerVideoGenerationProvider` | 视频生成 |
| `registerWebFetchProvider` | 网页抓取 / 提取提供商 |
| `registerWebFetchProvider` | 网页抓取 / 抓取 provider |
| `registerWebSearchProvider` | 网页搜索 |
| `registerHttpRoute` | HTTP 端点 |
| `registerCommand` / `registerCli` | CLI 命令 |
| `registerContextEngine` | 上下文引擎 |
| `registerService` | 后台服务 |
类型化生命周期钩子的钩子保护行为：
带类型生命周期钩子的守卫行为：
- `before_tool_call`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。
- `before_tool_call`：`{ block: false }` 为无操作，不会清除更早的 block。
- `before_install`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。
- `before_install`：`{ block: false }` 为无操作，不会清除更早的 block。
- `message_sending`：`{ cancel: true }` 为终止性结果；会跳过更低优先级的处理器。
- `message_sending`：`{ cancel: false }` 为无操作，不会清除更早的 cancel。
- `before_tool_call`：`{ block: true }` 是终止性的；会跳过更低优先级的处理程序。
- `before_tool_call`：`{ block: false }` 是空操作，不会清除先前的阻止。
- `before_install`：`{ block: true }` 是终止性的；会跳过更低优先级的处理程序。
- `before_install`：`{ block: false }` 是空操作，不会清除先前的阻止。
- `message_sending`：`{ cancel: true }` 是终止性的；会跳过更低优先级的处理程序。
- `message_sending`：`{ cancel: false }` 是空操作，不会清除先前的取消。
原生 Codex app-server 会将桥接的 Codex 原生工具事件回传到这个钩子功能面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex
`PermissionRequest` 审批。该桥接目前还不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界定义在
[Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) 中。
原生 Codex app-server 运行时会把桥接的 Codex 原生工具事件回传到这个钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。不过，这个桥接目前尚不会重写 Codex 原生工具参数。精确的 Codex 运行时支持边界定义在 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) 中。
完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
有关完整的带类型钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [插件捆绑包](/zh-CN/plugins/bundles) — Codex / Claude / Cursor 捆绑包兼容性
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
- [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性
- [插件 manifest](/zh-CN/plugins/manifest) — manifest schema
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型与加载流水线
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
- [社区插件](/zh-CN/plugins/community) — 第三方列表