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-23 15:21:18 +00:00
parent b790c16139
commit e79780b332
2 changed files with 244 additions and 339 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,30 +1,27 @@
---
read_when:
- 你想使用内置的 Codex app-server harness
- 你想使用内置的 Codex app-server 测试工具
- 你需要 Codex 模型引用和配置示例
- 你想为仅使用 Codex 的部署禁用 Pi 回退
summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体回合
title: Codex Harness
summary: 通过内置的 Codex app-server 测试工具运行 OpenClaw 嵌入式智能体轮次
title: Codex 测试工具
x-i18n:
generated_at: "2026-04-23T07:26:01Z"
generated_at: "2026-04-23T15:20:02Z"
model: gpt-5.4
provider: openai
source_hash: 8172af40edb7d1f7388a606df1c8f776622ffd82b46245fb9fbd184fbf829356
source_hash: 4537cdc043768f19cd097b4542dfb3447bf3342c7c300832e160b795263c2a52
source_path: plugins/codex-harness.md
workflow: 15
---
# Codex Harness
# Codex 测试工具
内置的 `codex` 插件让 OpenClaw 能够通过 Codex app-server 运行嵌入式智能体回合，而不是使用内置的 Pi harness。
内置的 `codex` 插件让 OpenClaw 能通过 Codex app-server 运行嵌入式智能体轮次，而不是使用内置的 PI 测试工具。
当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型发现、
原生线程恢复、原生压缩，以及 app-server 执行。
OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、
批准、媒体投递，以及可见的对话记录镜像。
当你希望由 Codex 接管底层智能体会话时，可以使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。
OpenClaw 仍负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。
原生 Codex 回合同样遵循共享插件钩子，因此 prompt shim、
感知压缩的自动化、工具中间件和生命周期观察器都能与 Pi harness 保持一致：
原生 Codex 轮次也会遵循共享插件钩子，因此 prompt shim、感知压缩的自动化、工具中间件和生命周期观察器都能与 PI 测试工具保持一致：
- `before_prompt_build`
- `before_compaction`, `after_compaction`
@ -33,42 +30,38 @@ OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、
- `before_message_write`
- `agent_end`
内置插件还可以注册一个 Codex app-server 扩展工厂，以添加
异步 `tool_result` 中间件。
内置插件还可以注册一个 Codex app-server 扩展工厂，以添加异步 `tool_result` 中间件。
该 harness 默认关闭。只有在启用 `codex` 插件且解析后的模型是
`codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选择它。
如果你从未配置 `codex/*`，现有的 Pi、OpenAI、Anthropic、Gemini、本地和自定义提供商运行方式都会保持当前行为。
该测试工具默认关闭。只有在启用 `codex` 插件且解析后的模型是 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选中它。
如果你从未配置 `codex/*`，现有的 PI、OpenAI、Anthropic、Gemini、本地和自定义提供商运行都会保持当前行为。
## 选择正确的模型前缀
OpenClaw 为 OpenAI 访问和 Codex 形态的访问分别提供了不同路由：
OpenClaw 为 OpenAI 访问和 Codex 风格访问提供了不同路径：
| 模型引用 | 运行时路径 | 使用场景 |
| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
| `openai/gpt-5.4` | 通过 OpenClaw/Pi 管线的 OpenAI 提供商 | 你希望使用 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 |
| `openai-codex/gpt-5.4` | 通过 Pi 的 OpenAI Codex OAuth 提供商 | 你希望使用 ChatGPT/Codex OAuth，但不使用 Codex app-server harness。 |
| `codex/gpt-5.4` | 内置 Codex 提供商 + Codex harness | 你希望为嵌入式智能体回合使用原生 Codex app-server 执行。 |
| 模型引用 | 运行时路径 | 适用场景 |
| -------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
| `openai/gpt-5.4` | 通过 OpenClaw/PI 管线的 OpenAI 提供商路径 | 你希望通过 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 |
| `openai-codex/gpt-5.4` | 通过 PI 的 OpenAI Codex OAuth 提供商路径 | 你希望使用 ChatGPT/Codex OAuth，但不使用 Codex app-server 测试工具。 |
| `codex/gpt-5.4` | 内置 Codex 提供商加 Codex 测试工具 | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。 |
Codex harness 仅接管 `codex/*` 模型引用。现有的 `openai/*`、
`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会保持正常路径。
Codex 测试工具只接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会保留其常规路径。
## 要求
- OpenClaw，且内置 `codex` 插件可用。
- OpenClaw，并且可用内置 `codex` 插件。
- Codex app-server `0.118.0` 或更高版本。
- app-server 进程可用的 Codex 认证信息。
- app-server 进程可用的 Codex 身份验证。
该插件会阻止较旧版本或未标明版本的 app-server 握手。
这可确保 OpenClaw 使用的是其已测试过的协议表面。
该插件会阻止较旧版本或未带版本信息的 app-server 握手。
这样可确保 OpenClaw 始终使用它已针对其进行测试的协议表面。
对于 live 和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及
可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和
`~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。
对于实时测试和 Docker 冒烟测试，身份验证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
请使用与你本地 Codex app-server 相同的身份验证材料。
## 最小配置
使用 `codex/gpt-5.4`，启用内置插件，并强制使用 `codex` harness：
使用 `codex/gpt-5.4`，启用内置插件，并强制使用 `codex` 测试工具：
```json5
{
@ -91,7 +84,7 @@ Codex harness 仅接管 `codex/*` 模型引用。现有的 `openai/*`、
}
```
如果你的配置使用 `plugins.allow`，也请将 `codex` 包含在其中：
如果你的配置使用 `plugins.allow`，也需要把 `codex` 包含进去：
```json5
{
@ -106,13 +99,12 @@ Codex harness 仅接管 `codex/*` 模型引用。现有的 `openai/*`、
}
```
将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>` 也会
自动启用内置 `codex` 插件。显式插件条目在共享配置中依然很有用，因为它能清楚表明部署意图。
将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>` 也会自动启用内置 `codex` 插件。
显式插件条目在共享配置中仍然很有用，因为它能让部署意图更清晰。
## 添加 Codex 而不替换其他模型
如果你希望 `codex/*` 模型使用 Codex，而其他所有模型使用 Pi，
请保持 `runtime: "auto"`：
当你希望 `codex/*` 模型使用 Codex，而其余所有模型使用 PI 时，请保留 `runtime: "auto"`：
```json5
{
@ -144,17 +136,16 @@ Codex harness 仅接管 `codex/*` 模型引用。现有的 `openai/*`、
}
```
在这种配置下：
采用这种形式后：
- `/model codex` 或 `/model codex/gpt-5.4` 使用 Codex app-server harness。
- `/model gpt` 或 `/model openai/gpt-5.4` 使用 OpenAI 提供商路径。
- `/model opus` 使用 Anthropic 提供商路径。
- 如果选择的是非 Codex 模型，Pi 仍然是兼容性 harness。
- `/model codex` 或 `/model codex/gpt-5.4` 会使用 Codex app-server 测试工具。
- `/model gpt` 或 `/model openai/gpt-5.4` 会使用 OpenAI 提供商路径。
- `/model opus` 会使用 Anthropic 提供商路径。
- 如果选择的是非 Codex 模型，PI 仍然是兼容性测试工具。
## 仅使用 Codex 的部署
当你需要证明每个嵌入式智能体回合都使用 Codex harness 时，
请禁用 Pi 回退：
当你需要证明每个嵌入式智能体轮次都使用 Codex 测试工具时，请禁用 PI 回退：
```json5
{
@ -178,14 +169,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```
禁用回退后，如果 Codex 插件被禁用、
请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者
app-server 无法启动，OpenClaw 都会尽早失败。
禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 都会提前失败。
## 按智能体使用 Codex
你可以让某一个智能体仅使用 Codex，而默认智能体仍保持正常的
自动选择：
你可以让某个智能体仅使用 Codex，同时让默认智能体保持正常的自动选择：
```json5
{
@ -216,20 +204,17 @@ app-server 无法启动，OpenClaw 都会尽早失败。
}
```
使用常规会话命令切换智能体和模型。`/new` 会创建一个全新的
OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-server
线程。`/reset` 会清除该线程的 OpenClaw 会话绑定。
使用常规会话命令切换智能体和模型。`/new` 会创建一个全新的 OpenClaw 会话，而 Codex 测试工具会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定。
## 模型发现
默认情况下，Codex 插件会向 app-server 请求可用模型。如果
发现失败或超时，它会使用内置的回退目录：
默认情况下，`codex` 插件会向 app-server 查询可用模型。如果发现失败或超时，它会使用内置的回退目录：
- `codex/gpt-5.4`
- `codex/gpt-5.4-mini`
- `codex/gpt-5.2`
你可以在 `plugins.entries.codex.config.discovery` 下调整发现设置：
你可以在 `plugins.entries.codex.config.discovery` 下调整发现行为：
```json5
{
@ -249,8 +234,7 @@ OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-serv
}
```
如果你希望启动时避免探测 Codex，并固定使用回退目录，
请禁用发现：
如果你希望启动时避免探测 Codex，而是固定使用回退目录，可以禁用发现：
```json5
{
@ -269,7 +253,7 @@ OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-serv
}
```
## app-server 连接和策略
## App-server 连接和策略
默认情况下，插件会使用以下命令在本地启动 Codex：
@ -277,11 +261,10 @@ OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-serv
codex app-server --listen stdio://
```
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：
`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及
`sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人响应的原生批准提示上。
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex 测试工具会话：
`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和 `sandbox: "danger-full-access"`。这是一种适用于自主心跳的受信任本地操作姿态：Codex 可以使用 shell 和网络工具，而不会停在无人可答复的原生审批提示上。
如果要启用由 Codex guardian 审查的批准，请设置 `appServer.mode:
如果你希望启用由 Codex guardian 审核的审批，请设置 `appServer.mode:
"guardian"`：
```json5
@ -302,45 +285,11 @@ codex app-server --listen stdio://
}
```
Guardian 模式会展开为：
Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加网络访问等权限时，Codex 会将该审批请求路由给一个 reviewer 子智能体，而不是向人类发出提示。该 reviewer 会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多保护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。
```json5
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
appServer: {
mode: "guardian",
approvalPolicy: "on-request",
approvalsReviewer: "guardian_subagent",
sandbox: "workspace-write",
},
},
},
},
},
}
```
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。各个单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。
Guardian 是原生 Codex 批准审查器。当 Codex 请求离开
沙箱、在工作区外写入，或添加网络访问等权限时，
Codex 会将该批准请求路由给审查子智能体，而不是人类提示。
审查器会收集上下文并应用 Codex 的风险框架，然后
批准或拒绝该具体请求。当你希望比 YOLO 模式有更多防护措施，
但仍需要无人值守的智能体和心跳继续推进时，Guardian 会很有用。
当设置了 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` 时，
Docker live harness 会包含一个 Guardian 探针。它会以
Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令会被批准，
并验证向不受信任的外部目标上传伪造密钥会被拒绝，
从而使智能体回过头来请求显式批准。
各个独立策略字段的优先级仍高于 `mode`，因此高级部署可以
将该预设与显式选择混合使用。
对于已在运行的 app-server，请使用 WebSocket 传输协议：
对于已经在运行的 app-server，请使用 WebSocket 传输：
```json5
{
@ -364,23 +313,22 @@ Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令
支持的 `appServer` 字段：
| 字段 | 默认值 | 含义 |
| 字段 | 默认值 | 含义 |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `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"` | 使用 `"guardian_subagent"` 可让 Codex Guardian 审查提示。 |
| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"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"` | 使用 `"guardian_subagent"` 可让 Codex Guardian 审核提示。 |
| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 |
较旧的环境变量仍可作为本地测试的回退方式使用，前提是
对应的配置字段未设置：
较旧的环境变量在匹配配置字段未设置时，仍可作为本地测试的回退方式使用：
- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -390,12 +338,11 @@ Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用
`plugins.entries.codex.config.appServer.mode: "guardian"`，或者在一次性本地测试中使用
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，
更推荐使用配置，因为这样可以将插件行为与其余 Codex harness 设置一起保存在同一个经过审查的文件中。
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复的部署，更推荐使用配置，因为这样可以将插件行为与 Codex 测试工具的其余设置放在同一个经过审查的文件中。
## 常见方案
## 常见配方
使用默认 stdio 传输协议的本地 Codex：
使用默认 stdio 传输的本地 Codex：
```json5
{
@ -409,7 +356,7 @@ Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令
}
```
仅使用 Codex 的 harness 验证，并禁用 Pi 回退：
仅使用 Codex 的测试工具验证，并禁用 PI 回退：
```json5
{
@ -426,7 +373,7 @@ Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令
}
```
由 Guardian 审查的 Codex 批准：
由 Guardian 审核的 Codex 审批：
```json5
{
@ -448,7 +395,7 @@ Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令
}
```
使用显式请求头的远程 app-server：
带显式请求头的远程 app-server：
```json5
{
@ -471,79 +418,58 @@ Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令
}
```
模型切换仍由 OpenClaw 控制。当某个 OpenClaw 会话附加到现有
Codex 线程时，下一回合会再次将当前选定的
`codex/*` 模型、提供商、批准策略、沙箱和服务层级发送给
app-server。从 `codex/gpt-5.4` 切换到 `codex/gpt-5.2` 会保留
线程绑定，但会要求 Codex 继续使用新选择的模型。
模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有 Codex 线程时，下一个轮次会再次将当前选定的 `codex/*` 模型、提供商、审批策略、沙箱和服务层级发送到 app-server。
从 `codex/gpt-5.4` 切换到 `codex/gpt-5.2` 时，会保留线程绑定，但会要求 Codex 使用新选定的模型继续。
## Codex 命令
内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用命令，
可用于任何支持 OpenClaw 文本命令的渠道。
内置插件将 `/codex` 注册为一个已授权的斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道上工作。
常见形式：
- `/codex status` 显示实时 app-server 连接性、模型、账户、速率限制、MCP 服务器和 skills。
- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和技能。
- `/codex models` 列出实时 Codex app-server 模型。
- `/codex threads [filter]` 列出最近的 Codex 线程。
- `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有 Codex 线程。
- `/codex compact` 请求 Codex app-server 压缩已附加的线程。
- `/codex review` 为已附加线程启动 Codex 原生审查。
- `/codex review` 为已附加的线程启动 Codex 原生审查。
- `/codex account` 显示账户和速率限制状态。
- `/codex mcp` 列出 Codex app-server MCP 服务器状态。
- `/codex skills` 列出 Codex app-server Skills。
`/codex resume` 会写入与 harness 正常回合所使用的相同 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw `codex/*` 模型传入 app-server，并保持扩展历史记录启用。
`/codex resume` 会写入与测试工具用于常规轮次相同的 sidecar 绑定文件。下一条消息到来时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw `codex/*` 模型传入 app-server，并保持启用扩展历史记录。
该命令表面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，各个具体控制方法会显示为 `unsupported by this Codex app-server`。
该命令表面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，单独的控制方法会报告为 `unsupported by this Codex app-server`。
## 工具、媒体和压缩
Codex harness 仅改变底层嵌入式智能体执行器。
Codex 测试工具只改变底层嵌入式智能体执行器。
OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。
文本、图像、视频、音乐、TTS、批准以及消息工具输出仍然通过
正常的 OpenClaw 投递路径继续处理。
OpenClaw 仍然构建工具列表，并从测试工具接收动态工具结果。文本、图像、视频、音乐、TTS、审批和消息工具输出都会继续通过正常的 OpenClaw 传递路径处理。
当 Codex 将 `_meta.codex_approval_kind` 标记为
`"mcp_tool_call"` 时，Codex MCP 工具批准征询会通过 OpenClaw 的插件批准流程路由；其他征询和自由形式输入请求仍会以失败关闭方式处理。
当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批征询会通过 OpenClaw 的插件审批流路由；其他征询和自由格式输入请求仍会以默认拒绝方式处理。
当所选模型使用 Codex harness 时，原生线程压缩会委托给
Codex app-server。OpenClaw 会保留一个对话记录镜像，用于渠道历史、
搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该镜像包括用户提示、最终助手文本，以及在 app-server 发出时的轻量级 Codex 推理或计划记录。当前，OpenClaw 仅记录原生压缩的开始和完成信号。它尚未提供
人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。
当选定模型使用 Codex 测试工具时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或测试工具切换。该镜像包括用户提示、最终助手文本，以及 app-server 发出时的轻量级 Codex 推理或计划记录。当前，OpenClaw 只记录原生压缩开始和完成信号。它尚未提供人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。
媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解
仍继续使用匹配的提供商/模型设置，例如
`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和
`messages.tts`。
媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用匹配的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。
## 故障排除
**`/model` 中没有显示 Codex：** 启用 `plugins.entries.codex.enabled`，
设置一个 `codex/*` 模型引用，或者检查 `plugins.allow` 是否排除了 `codex`。
**`/model` 中没有出现 Codex：** 启用 `plugins.entries.codex.enabled`，设置一个 `codex/*` 模型引用，或者检查 `plugins.allow` 是否排除了 `codex`。
**OpenClaw 使用的是 Pi 而不是 Codex：** 如果没有任何 Codex harness 接管该运行，
OpenClaw 可能会使用 Pi 作为兼容性后端。测试时可设置
`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或者设置
`embeddedHarness.fallback: "none"`，以便在没有匹配插件 harness 时直接失败。一旦选定了 Codex app-server，其失败会直接暴露出来，而无需额外的回退配置。
**OpenClaw 使用的是 PI 而不是 Codex：** 如果没有 Codex 测试工具接管该运行，OpenClaw 可能会使用 PI 作为兼容性后端。测试时可设置 `embeddedHarness.runtime: "codex"` 来强制选择 Codex，或设置 `embeddedHarness.fallback: "none"` 以便在没有匹配插件测试工具时直接失败。一旦选中了 Codex app-server，其失败会直接暴露出来，不需要额外的回退配置。
**app-server 被拒绝：** 升级 Codex，使 app-server 握手
报告版本 `0.118.0` 或更高。
**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本 `0.118.0` 或更高。
**模型发现速度慢：** 调低 `plugins.entries.codex.config.discovery.timeoutMs`
或禁用发现。
**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`，或禁用发现。
**WebSocket 传输协议立即失败：** 检查 `appServer.url`、`authToken`，
以及远程 app-server 是否使用相同的 Codex app-server 协议版本。
**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，以及远程 app-server 是否使用相同版本的 Codex app-server 协议。
**非 Codex 模型使用了 Pi：** 这是预期行为。Codex harness 仅接管
`codex/*` 模型引用。
**某个非 Codex 模型使用了 PI：** 这是预期行为。Codex 测试工具只接管 `codex/*` 模型引用。
## 相关内容
- [Agent Harness Plugins](/zh-CN/plugins/sdk-agent-harness)
- [Model Providers](/zh-CN/concepts/model-providers)
- [Configuration Reference](/zh-CN/gateway/configuration-reference)
- [Testing](/zh-CN/help/testing#live-codex-app-server-harness-smoke)
- [智能体测试工具插件](/zh-CN/plugins/sdk-agent-harness)
- [模型提供商](/zh-CN/concepts/model-providers)
- [配置参考](/zh-CN/gateway/configuration-reference)
- [测试](/zh-CN/help/testing#live-codex-app-server-harness-smoke)

325
docs/zh-CN/plugins/skill-workshop.md
View File

@ -1,25 +1,25 @@
---
read_when:
- 你希望智能体将修正内容或可复用流程转换为工作区 Skills
- 你正在配置过程型 Skills 记忆
- 你希望智能体将修正内容或可复用流程转化为工作区 Skills
- 你正在配置流程性 Skills 记忆
- 你正在调试 `skill_workshop` 工具行为
- 你正在决定是否启用自动创建 Skills
summary: 将可复用流程以工作区 Skills 的形式进行实验性捕获，并支持审核、批准、隔离和 Skills 热刷新
summary: 将可复用流程以工作区 Skills 的形式进行实验性沉淀，并支持审查、审批、隔离以及热刷新 Skills
title: Skill Workshop 插件
x-i18n:
generated_at: "2026-04-21T20:35:14Z"
generated_at: "2026-04-23T15:20:00Z"
model: gpt-5.4
provider: openai
source_hash: 62dcb3e1a71999bfc39a95dc3d0984d3446c8a58f7d91a914dfc7256b4e79601
source_hash: 12036df53a7a34450f5b64819dd608d37e74a0e49d9fbeef431b9b2b53950f03
source_path: plugins/skill-workshop.md
workflow: 15
---
# Skill Workshop 插件
Skill Workshop **处于实验阶段**。默认禁用，其捕获启发式规则和审阅者提示可能会在不同版本之间发生变化，并且自动写入应仅在受信任的工作区中使用，且应先查看待处理模式的输出。
Skill Workshop **处于实验阶段**。它默认禁用，其捕获启发式规则和审查者提示可能会在不同版本之间发生变化，并且自动写入只应在可信工作区中使用，且应先审查 pending 模式的输出。
Skill Workshop 是用于工作区 Skills 的过程型记忆。它让智能体能够将可复用工作流、用户修正、来之不易的修复经验以及反复出现的陷阱，转换为以下位置下的 `SKILL.md` 文件：
Skill Workshop 是面向工作区 Skills 的流程性记忆。它让智能体能够将可复用的工作流、用户修正、来之不易的修复方案以及反复出现的陷阱，转化为以下路径下的 `SKILL.md` 文件：
```text
<workspace>/skills/<skill-name>/SKILL.md
@ -27,38 +27,38 @@ Skill Workshop 是用于工作区 Skills 的过程型记忆。它让智能体能
这不同于长期记忆：
- **Memory** 存储事实、偏好、实体和过去的上下文。
- **Skills** 存储智能体在未来任务中应遵循的可复用流程。
- **Skill Workshop** 是从一次有用的交互到持久化工作区 skill 的桥梁，带有安全检查和可选批准。
- **Memory** 用于存储事实、偏好、实体以及过去的上下文。
- **Skills** 用于存储智能体在未来任务中应遵循的可复用流程。
- **Skill Workshop** 则是将一次有价值的交互转化为持久化工作区技能的桥梁，并带有安全检查和可选审批。
当智能体学会如下流程时，Skill Workshop 会很有用：
当智能体学会如下流程时，Skill Workshop 很有用：
- 如何验证外部来源的动画 GIF 资源
- 如何验证外部来源的动态图像 `GIF` 资源
- 如何替换截图资源并验证尺寸
- 如何运行仓库特定的 QA 场景
- 如何调试反复出现的提供商故障
- 如何运行仓库特定的 `QA` 场景
- 如何调试反复出现的 provider 故障
- 如何修复过时的本地工作流说明
它不适用于：
- 像“用户喜欢蓝色”这样的事实
- 宽泛的自传式记忆
- 原始转录归档
- 原始对话记录归档
- 密钥、凭证或隐藏提示文本
- 不会重复出现的一次性指令
## 默认状态
内置插件**处于实验阶段**，并且**默认禁用**，除非在 `plugins.entries.skill-workshop` 中显式启用。
该内置插件**处于实验阶段**，并且**默认禁用**，除非你在 `plugins.entries.skill-workshop` 中显式启用它。
插件清单未设置 `enabledByDefault: true`。插件配置 schema 中的 `enabled: true` 默认值仅在插件条目已被选中并加载后才会生效。
插件清单未设置 `enabledByDefault: true`。插件配置 schema 中的 `enabled: true` 默认值，仅在该插件条目已被选中并加载之后才会生效。
“实验阶段”意味着：
实验阶段意味着：
- 该插件已具备足够支持，可用于选择加入的测试和内部试用
- 提案存储、审阅阈值和捕获启发式规则可能会持续演进
- 建议将待批准作为起始模式
- 自动应用适用于受信任的个人 / 工作区设置，不适用于共享或高频接收不可信输入的环境
- 该插件已具备足够支持，可用于选择性测试和 dogfooding
- 提案存储、审查者阈值和捕获启发式规则都可能继续演进
- 建议从待审批模式开始
- 自动应用适用于可信的个人或工作区环境，不适用于共享环境或存在大量不可信输入的环境
## 启用
@ -84,11 +84,11 @@ Skill Workshop 是用于工作区 Skills 的过程型记忆。它让智能体能
使用此配置时：
- `skill_workshop` 工具可用
- 明确的可复用修正会被排入待处理提案队列
- 基于阈值的审阅者流程可以提出 skill 更新建议
- 在待处理提案被应用之前，不会写入任何 skill 文件
- 显式的可复用修正会被加入待处理提案队列
- 基于阈值的审查者流程可以提出 Skills 更新提案
- 在待处理提案被应用之前，不会写入任何技能文件
仅在受信任的工作区中使用自动写入：
仅在可信工作区中使用自动写入：
```json5
{
@ -107,26 +107,26 @@ Skill Workshop 是用于工作区 Skills 的过程型记忆。它让智能体能
}
```
`approvalPolicy: "auto"` 仍会使用相同的扫描器和隔离路径。它不会应用存在严重扫描发现的问题提案。
`approvalPolicy: "auto"` 仍然使用相同的扫描器和隔离路径。它不会应用带有严重发现项的提案。
## 配置
| 键名 | 默认值 | 范围 / 取值 | 含义 |
| -------------------- | ----------- | -------------------------------------------- | ---------------------------------------------- |
| `enabled` | `true` | boolean | 在插件条目加载后启用该插件。 |
| `autoCapture` | `true` | boolean | 在智能体成功完成交互后启用交互后捕获 / 审阅。 |
| `approvalPolicy` | `"pending"` | `"pending"`, `"auto"` | 将提案加入队列，或自动写入安全提案。 |
| `reviewMode` | `"hybrid"` | `"off"`, `"heuristic"`, `"llm"`, `"hybrid"` | 选择显式修正捕获、LLM 审阅者、两者或都不用。 |
| `reviewInterval` | `15` | `1..200` | 在这么多次成功交互后运行审阅者。 |
| `reviewMinToolCalls` | `8` | `1..500` | 在观察到这么多次工具调用后运行审阅者。 |
| `reviewTimeoutMs` | `45000` | `5000..180000` | 内嵌审阅者运行的超时时间。 |
| `maxPending` | `50` | `1..200` | 每个工作区保留的待处理 / 已隔离提案最大数量。 |
| `maxSkillBytes` | `40000` | `1024..200000` | 生成的 skill / 支持文件的最大大小。 |
| 键 | 默认值 | 范围 / 取值 | 含义 |
| -------------------- | ----------- | ------------------------------------------- | -------------------------------------------------------------------- |
| `enabled` | `true` | boolean | 在插件条目加载后启用该插件。 |
| `autoCapture` | `true` | boolean | 在成功的智能体回合后启用回合后捕获 / 审查。 |
| `approvalPolicy` | `"pending"` | `"pending"`, `"auto"` | 将提案加入队列，或自动写入安全提案。 |
| `reviewMode` | `"hybrid"` | `"off"`, `"heuristic"`, `"llm"`, `"hybrid"` | 选择显式修正捕获、LLM 审查者、两者兼用，或两者都不用。 |
| `reviewInterval` | `15` | `1..200` | 每经过这么多个成功回合后运行审查者。 |
| `reviewMinToolCalls` | `8` | `1..500` | 在观察到这么多个工具调用后运行审查者。 |
| `reviewTimeoutMs` | `45000` | `5000..180000` | 内嵌审查者运行的超时时间。 |
| `maxPending` | `50` | `1..200` | 每个工作区保留的待处理 / 隔离提案的最大数量。 |
| `maxSkillBytes` | `40000` | `1024..200000` | 生成的技能 / 支持文件的最大大小。 |
推荐配置档案：
推荐配置档：
```json5
// 保守：仅显式工具使用，不启用自动捕获。
// 保守模式：仅显式工具使用，不进行自动捕获。
{
autoCapture: false,
approvalPolicy: "pending",
@ -135,7 +135,7 @@ Skill Workshop 是用于工作区 Skills 的过程型记忆。它让智能体能
```
```json5
// 先审阅：自动捕获，但需要批准。
// 先审查后应用：自动捕获，但需要审批。
{
autoCapture: true,
approvalPolicy: "pending",
@ -144,7 +144,7 @@ Skill Workshop 是用于工作区 Skills 的过程型记忆。它让智能体能
```
```json5
// 受信任自动化：立即写入安全提案。
// 可信自动化：立即写入安全提案。
{
autoCapture: true,
approvalPolicy: "auto",
@ -153,7 +153,7 @@ Skill Workshop 是用于工作区 Skills 的过程型记忆。它让智能体能
```
```json5
// 低成本：不调用审阅者 LLM，仅使用显式修正短语。
// 低成本：不调用审查者 LLM，仅使用显式修正短语。
{
autoCapture: true,
approvalPolicy: "pending",
@ -167,13 +167,13 @@ Skill Workshop 有三种捕获路径。
### 工具建议
当模型看到可复用流程，或用户要求它保存 / 更新某个 skill 时，可以直接调用 `skill_workshop`。
当模型看到可复用流程，或用户要求其保存 / 更新某个技能时，它可以直接调用 `skill_workshop`。
这是最显式的路径，即使在 `autoCapture: false` 时也可工作。
这是最显式的路径，即使在 `autoCapture: false` 时也能工作。
### 启发式捕获
当启用 `autoCapture`，且 `reviewMode` 为 `heuristic` 或 `hybrid` 时，插件会扫描成功交互中的显式用户修正短语：
当启用 `autoCapture` 且 `reviewMode` 为 `heuristic` 或 `hybrid` 时，插件会扫描成功回合中的显式用户修正短语：
- `next time`
- `from now on`
@ -183,40 +183,36 @@ Skill Workshop 有三种捕获路径。
- `prefer ... when/for/instead/use`
- `when asked`
启发式规则会根据最近匹配的用户指令创建提案。它会使用主题提示为常见工作流选择 skill 名称：
该启发式方法会根据最新匹配的用户指令创建提案。它使用主题提示为常见工作流选择技能名称：
- 动画 GIF 任务 -> `animated-gif-workflow`
- 动图 `GIF` 任务 -> `animated-gif-workflow`
- 截图或资源任务 -> `screenshot-asset-workflow`
- QA 或场景任务 -> `qa-scenario-workflow`
- GitHub PR 任务 -> `github-pr-workflow`
- `QA` 或场景任务 -> `qa-scenario-workflow`
- GitHub `PR` 任务 -> `github-pr-workflow`
- 回退 -> `learned-workflows`
启发式捕获是有意保持狭窄范围的。它适用于清晰的修正和可重复流程说明，不适用于通用的转录摘要。
启发式捕获有意保持狭窄范围。它适用于明确的修正和可重复的流程说明，不适用于通用的对话摘要。
### LLM 审阅者
### LLM 审查者
当启用 `autoCapture`，且 `reviewMode` 为 `llm` 或 `hybrid` 时，插件会在达到阈值后运行一个紧凑的内嵌审阅者。
当启用 `autoCapture` 且 `reviewMode` 为 `llm` 或 `hybrid` 时，插件会在达到阈值后运行一个紧凑的内嵌审查者。
审阅者会接收：
审查者会收到：
- 最近的转录文本，限制为最后 12,000 个字符
- 最多 12 个现有工作区 Skills
- 每个现有 skill 最多 2,000 个字符
- 最近的对话文本，限制为最后 12,000 个字符
- 最多 12 个现有工作区技能
- 每个现有技能最多 2,000 个字符
- 仅 JSON 指令
审阅者没有工具：
审查者没有工具可用：
- `disableTools: true`
- `toolsAllow: []`
- `disableMessageTool: true`
它可以返回：
审查者会返回 `{ "action": "none" }`，或返回一个提案。`action` 字段可以是 `create`、`append` 或 `replace`——当已存在相关技能时，优先使用 `append` / `replace`；仅在没有合适现有技能时才使用 `create`。
```json
{ "action": "none" }
```
或者返回一个 skill 提案：
`create` 示例：
```json
{
@ -229,38 +225,11 @@ Skill Workshop 有三种捕获路径。
}
```
它也可以向现有 skill 追加内容：
```json
{
"action": "append",
"skillName": "qa-scenario-workflow",
"title": "QA Scenario Workflow",
"reason": "Animated media QA needs reusable checks",
"description": "QA scenario workflow.",
"section": "Workflow",
"body": "- For animated GIF tasks, verify frame count and attribution before passing."
}
```
或者替换现有 skill 中的精确文本：
```json
{
"action": "replace",
"skillName": "screenshot-asset-workflow",
"title": "Screenshot Asset Workflow",
"reason": "Old validation missed image optimization",
"oldText": "- Replace the screenshot asset.",
"newText": "- Replace the screenshot asset, preserve dimensions, optimize the PNG, and run the relevant validation gate."
}
```
当相关 skill 已存在时，优先使用 `append` 或 `replace`。仅当没有任何现有 skill 适合时，才使用 `create`。
`append` 会添加 `section` + `body`。`replace` 会在指定技能中将 `oldText` 替换为 `newText`。
## 提案生命周期
每个生成的更新都会成为一个提案，包含：
每个生成的更新都会成为一个提案，并包含以下字段：
- `id`
- `createdAt`
@ -271,7 +240,7 @@ Skill Workshop 有三种捕获路径。
- `skillName`
- `title`
- `reason`
- `source`：`tool`、`agent_end` 或 `reviewer`
- `source`: `tool`、`agent_end` 或 `reviewer`
- `status`
- `change`
- 可选的 `scanFindings`
@ -279,10 +248,10 @@ Skill Workshop 有三种捕获路径。
提案状态：
- `pending` - 等待批准
- `pending` - 等待审批
- `applied` - 已写入 `<workspace>/skills`
- `rejected` - 已被操作员 / 模型拒绝
- `quarantined` - 因严重扫描发现而被阻止
- `quarantined` - 因扫描器发现严重问题而被阻止
状态按工作区存储在 Gateway 网关状态目录下：
@ -290,7 +259,7 @@ Skill Workshop 有三种捕获路径。
<stateDir>/skill-workshop/<workspace-hash>.json
```
待处理和已隔离提案会按 skill 名称和变更负载去重。存储会保留最新的待处理 / 已隔离提案，最多不超过 `maxPending`。
待处理和已隔离提案会按技能名称和变更载荷去重。存储会保留最新的待处理 / 已隔离提案，最多不超过 `maxPending`。
## 工具参考
@ -308,7 +277,7 @@ skill_workshop
{ "action": "status" }
```
结果结构：
结果格式：
```json
{
@ -328,7 +297,7 @@ skill_workshop
{ "action": "list_pending" }
```
列出其他状态：
如需列出其他状态：
```json
{ "action": "list_pending", "status": "applied" }
@ -349,7 +318,7 @@ skill_workshop
{ "action": "list_quarantine" }
```
当自动捕获看起来没有任何效果，而日志中提到 `skill-workshop: quarantined <skill>` 时，请使用此操作。
当自动捕获看起来没有任何效果，并且日志中提到 `skill-workshop: quarantined <skill>` 时，请使用这个命令。
### `inspect`
@ -364,7 +333,7 @@ skill_workshop
### `suggest`
创建一个提案。当使用 `approvalPolicy: "pending"` 时，默认会将其加入队列。
创建一个提案。当使用 `approvalPolicy: "pending"`（默认值）时，这会加入队列，而不是直接写入。
```json
{
@ -377,7 +346,8 @@ skill_workshop
}
```
强制安全写入：
<AccordionGroup>
<Accordion title="强制安全写入（apply: true）">
```json
{
@ -389,7 +359,9 @@ skill_workshop
}
```
即使在 `approvalPolicy: "auto"` 下也强制进入待处理状态：
</Accordion>
<Accordion title="在自动策略下强制设为待处理（apply: false）">
```json
{
@ -401,7 +373,9 @@ skill_workshop
}
```
向某个章节追加内容：
</Accordion>
<Accordion title="追加到指定 section">
```json
{
@ -413,7 +387,9 @@ skill_workshop
}
```
替换精确文本：
</Accordion>
<Accordion title="替换精确文本">
```json
{
@ -424,6 +400,9 @@ skill_workshop
}
```
</Accordion>
</AccordionGroup>
### `apply`
应用一个待处理提案。
@ -454,7 +433,7 @@ quarantined proposal cannot be applied
### `write_support_file`
在现有或提议中的 skill 目录内写入一个支持文件。
在现有或拟议中的技能目录内写入一个支持文件。
允许的顶级支持目录：
@ -474,111 +453,111 @@ quarantined proposal cannot be applied
}
```
支持文件按工作区作用域管理，会进行路径检查、受 `maxSkillBytes` 的字节大小限制、经过扫描，并以原子方式写入。
支持文件按工作区范围管理，会进行路径检查，受 `maxSkillBytes` 字节限制，经过扫描，并以原子方式写入。
## Skill 写入
## Skills 写入
Skill Workshop 仅会写入以下路径：
Skill Workshop 只会写入以下路径：
```text
<workspace>/skills/<normalized-skill-name>/
```
Skill 名称会被规范化：
技能名称会进行规范化处理：
- 转为小写
- 非 `[a-z0-9_-]` 的连续字符会变为 `-`
- 移除开头 / 结尾的非字母数字字符
- 去除开头 / 结尾的非字母数字字符
- 最大长度为 80 个字符
- 最终名称必须匹配 `[a-z0-9][a-z0-9_-]{1,79}`
对于 `create`：
- 如果 skill 不存在，Skill Workshop 会写入一个新的 `SKILL.md`
- 如果已存在，Skill Workshop 会将内容追加到 `## Workflow`
- 如果技能不存在，Skill Workshop 会写入一个新的 `SKILL.md`
- 如果技能已存在，Skill Workshop 会将正文追加到 `## Workflow`
对于 `append`：
- 如果 skill 已存在，Skill Workshop 会追加到请求的章节
- 如果不存在，Skill Workshop 会先创建一个最小 skill，然后再追加
- 如果技能存在，Skill Workshop 会追加到请求的 section
- 如果技能不存在，Skill Workshop 会先创建一个最小技能，再执行追加
对于 `replace`：
- skill 必须已经存在
- 该技能必须已经存在
- `oldText` 必须精确存在
- 只会替换第一个精确匹配项
所有写入都是原子的，并会立即刷新内存中的 Skills 快照，因此无需重启 Gateway 网关也能看到新的或更新后的 skill。
所有写入都是原子的，并会立即刷新内存中的 Skills 快照，因此新建或更新后的技能无需重启 Gateway 网关即可变得可见。
## 安全模型
Skill Workshop 会对生成的 `SKILL.md` 内容和支持文件进行安全扫描。
Skill Workshop 会对生成的 `SKILL.md` 内容和支持文件执行安全扫描。
严重发现会将提案隔离：
严重发现项会将提案隔离：
| 规则 id | 阻止这类内容： |
| ------------------------------------- | ------------------------------------------------------------------ |
| `prompt-injection-ignore-instructions` | 告诉智能体忽略先前 / 更高优先级指令 |
| `prompt-injection-system` | 引用系统提示、开发者消息或隐藏指令 |
| `prompt-injection-tool` | 鼓励绕过工具权限 / 批准 |
| `shell-pipe-to-shell` | 包含将 `curl` / `wget` 通过管道传给 `sh`、`bash` 或 `zsh` 的内容 |
| `secret-exfiltration` | 看起来会通过网络发送 env / 进程环境数据 |
| 规则 id | 会拦截这样的内容…… |
| -------------------------------------- | --------------------------------------------------------------------- |
| `prompt-injection-ignore-instructions` | 指示智能体忽略先前 / 更高优先级指令 |
| `prompt-injection-system` | 引用 system prompt、开发者消息或隐藏指令 |
| `prompt-injection-tool` | 鼓励绕过工具权限 / 审批 |
| `shell-pipe-to-shell` | 包含将 `curl` / `wget` 通过管道传给 `sh`、`bash` 或 `zsh` 的内容 |
| `secret-exfiltration` | 看起来会通过网络发送 env / process env 数据 |
警告发现会被保留，但不会单独造成阻止：
警告发现项会保留，但不会单独构成拦截：
| 规则 id | 警告内容： |
| ------------------- | ------------------------------ |
| `destructive-delete` | 宽泛的 `rm -rf` 风格命令 |
| `unsafe-permissions` | `chmod 777` 风格的权限使用 |
| 规则 id | 警告内容…… |
| -------------------- | -------------------------------- |
| `destructive-delete` | 宽泛的 `rm -rf` 风格命令 |
| `unsafe-permissions` | `chmod 777` 风格的权限使用 |
已隔离提案：
- 保留 `scanFindings`
- 保留 `quarantineReason`
- 会显示在 `list_quarantine` 中
- 会保留 `scanFindings`
- 会保留 `quarantineReason`
- 会出现在 `list_quarantine` 中
- 不能通过 `apply` 应用
要从已隔离提案中恢复，请创建一个移除了不安全内容的新安全提案。不要手动编辑存储 JSON。
若要从已隔离提案中恢复，请创建一个移除了不安全内容的新安全提案。不要手动编辑存储 JSON。
## 提示指导
## 提示词指引
启用后，Skill Workshop 会注入一段简短提示，告诉智能体使用 `skill_workshop` 来保存持久化的过程型记忆。
启用后，Skill Workshop 会注入一段简短提示，告知智能体使用 `skill_workshop` 来保存持久化的流程性记忆。
该指导强调：
该指引强调：
- 保存流程，而不是事实 / 偏好
- 用户修正
- 不明显但成功的流程
- 反复出现的陷阱
- 通过 append / replace 修复过时 / 过薄 / 错误的 skill
- 在长工具循环或艰难修复后保存可复用流程
- 使用简短的祈使句风格 skill 文本
- 不要转储转录内容
- 通过 append / replace 修复过时 / 过薄 / 错误的技能
- 在长工具循环或艰难修复之后保存可复用流程
- 简短的祈使式技能文本
- 不要转储对话记录
写入模式文本会随 `approvalPolicy` 改变：
- 待处理模式：将建议加入队列；仅在显式批准后应用
- 自动模式：在明确可复用时应用安全的工作区 skill 更新
- pending 模式：将建议加入队列；仅在显式批准后应用
- auto 模式：在明确可复用时应用安全的工作区 Skills 更新
## 成本和运行时行为
## 成本与运行时行为
启发式捕获不会调用模型。
LLM 审阅会在当前 / 默认智能体模型上执行一个内嵌运行。它是基于阈值触发的，因此默认不会在每次交互时都运行。
LLM 审查会在当前 / 默认智能体模型上执行一次内嵌运行。它基于阈值触发，因此默认不会在每个回合都运行。
审阅者：
审查者：
- 在可用时使用相同的已配置提供商 / 模型上下文
- 在可用时使用相同的已配置 provider / model 上下文
- 否则回退到运行时智能体默认值
- 具有 `reviewTimeoutMs`
- 受 `reviewTimeoutMs` 限制
- 使用轻量级引导上下文
- 没有工具
- 不会直接写入任何内容
- 只能生成一个提案，然后该提案会经过常规扫描器以及批准 / 隔离路径
- 只能产出一个提案，之后仍需经过常规扫描器以及审批 / 隔离路径
如果审阅者失败、超时或返回无效 JSON，插件会记录一条 warning / debug 日志消息，并跳过该次审阅流程。
如果审查者失败、超时或返回无效 JSON，插件会记录 warning / debug 日志消息，并跳过该次审查。
## 运行模式
## 使用模式
当用户这样说时，请使用 Skill Workshop：
@ -589,7 +568,7 @@ LLM 审阅会在当前 / 默认智能体模型上执行一个内嵌运行。它
- “this took a while; remember the process”
- “update the local skill for this”
好的 skill 文本：
好的技能文本：
```markdown
## Workflow
@ -601,19 +580,19 @@ LLM 审阅会在当前 / 默认智能体模型上执行一个内嵌运行。它
- Verify the local asset renders in the target UI before final reply.
```
差的 skill 文本：
较差的技能文本：
```markdown
The user asked about a GIF and I searched two websites. Then one was blocked by
Cloudflare. The final answer said to check attribution.
```
不应保存差版本的原因：
较差版本不应保存的原因：
- 呈现为转录内容形态
- 不是祈使句
- 呈现为对话记录形态
- 不是祈使式
- 包含嘈杂的一次性细节
- 没有告诉下一个智能体应该做什么
- 没有告诉下一个智能体该做什么
## 调试
@ -623,7 +602,7 @@ Cloudflare. The final answer said to check attribution.
openclaw plugins list --enabled
```
在智能体 / 工具上下文中检查提案计数：
在智能体 / 工具上下文中检查提案数量：
```json
{ "action": "status" }
@ -643,15 +622,15 @@ openclaw plugins list --enabled
常见症状：
| 症状 | 可能原因 | 检查项 |
| 症状 | 可能原因 | 检查项 |
| ------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| 工具不可用 | 插件条目未启用 | `plugins.entries.skill-workshop.enabled` 和 `openclaw plugins list` |
| 没有出现自动提案 | `autoCapture: false`、`reviewMode: "off"`，或未达到阈值 | 配置、提案状态、Gateway 网关日志 |
| 启发式规则未捕获 | 用户措辞未匹配修正规则模式 | 使用显式 `skill_workshop.suggest` 或启用 LLM 审阅者 |
| 审阅者未创建提案 | 审阅者返回了 `none`、无效 JSON，或已超时 | Gateway 网关日志、`reviewTimeoutMs`、阈值 |
| 提案未被应用 | `approvalPolicy: "pending"` | `list_pending`，然后执行 `apply` |
| 提案从待处理列表中消失 | 复用了重复提案、达到最大待处理裁剪上限，或已被应用 / 拒绝 / 隔离 | `status`、带状态过滤的 `list_pending`、`list_quarantine` |
| skill 文件存在，但模型没有使用它 | skill 快照未刷新，或 skill 门控将其排除 | `openclaw skills` 状态和工作区 skill 资格 |
| 工具不可用 | 插件条目未启用 | `plugins.entries.skill-workshop.enabled` 和 `openclaw plugins list` |
| 没有出现自动提案 | `autoCapture: false`、`reviewMode: "off"`，或未达到阈值 | 配置、提案状态、Gateway 网关日志 |
| 启发式未捕获 | 用户措辞未匹配修正模式 | 使用显式 `skill_workshop.suggest` 或启用 LLM 审查者 |
| 审查者未创建提案 | 审查者返回 `none`、无效 JSON 或超时 | Gateway 网关日志、`reviewTimeoutMs`、阈值 |
| 提案未被应用 | `approvalPolicy: "pending"` | `list_pending`，然后执行 `apply` |
| 提案从 pending 中消失 | 复用了重复提案、max pending 修剪，或已被应用 / 拒绝 / 隔离 | `status`、带状态筛选的 `list_pending`、`list_quarantine` |
| 技能文件存在，但模型未命中 | Skills 快照未刷新，或技能门控将其排除 | `openclaw skills` 状态以及工作区技能资格 |
相关日志：
@ -664,7 +643,7 @@ openclaw plugins list --enabled
## QA 场景
基于仓库的 QA 场景：
由仓库支持的 QA 场景：
- `qa/scenarios/plugins/skill-workshop-animated-gif-autocreate.md`
- `qa/scenarios/plugins/skill-workshop-pending-approval.md`
@ -679,7 +658,7 @@ pnpm openclaw qa suite \
--concurrency 1
```
运行审阅者覆盖：
运行审查者覆盖：
```bash
pnpm openclaw qa suite \
@ -687,7 +666,7 @@ pnpm openclaw qa suite \
--concurrency 1
```
审阅者场景被有意单独拆分，因为它启用了 `reviewMode: "llm"` 并覆盖了内嵌审阅者流程。
审查者场景被有意单独拆分，因为它启用了 `reviewMode: "llm"` 并覆盖了内嵌审查者流程。
## 何时不应启用自动应用
@ -695,11 +674,11 @@ pnpm openclaw qa suite \
- 工作区包含敏感流程
- 智能体正在处理不可信输入
- Skills 由一个较大的团队共享
- 你仍在调整提示或扫描规则
- Skills 会在较大的团队范围内共享
- 你仍在调整提示词或扫描器规则
- 模型经常处理带有敌意的网页 / 邮件内容
请先使用待处理模式。仅在你审查过该工作区中智能体提出的 skill 类型之后，再切换到自动模式。
先使用 pending 模式。只有在你审查过该工作区中智能体提出的技能类型之后，再切换到 auto 模式。
## 相关文档