From e79780b3323d00aa01b0862e270a0bf95f4e10bc Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 15:21:18 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/plugins/codex-harness.md | 258 ++++++++------------- docs/zh-CN/plugins/skill-workshop.md | 325 +++++++++++++-------------- 2 files changed, 244 insertions(+), 339 deletions(-) diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index 62671ca7e..98425fd18 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -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/` 也会 -自动启用内置 `codex` 插件。显式插件条目在共享配置中依然很有用，因为它能清楚表明部署意图。 +将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 也会自动启用内置 `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 ` 将当前 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) diff --git a/docs/zh-CN/plugins/skill-workshop.md b/docs/zh-CN/plugins/skill-workshop.md index 034d3c8b8..7e5a09ba2 100644 --- a/docs/zh-CN/plugins/skill-workshop.md +++ b/docs/zh-CN/plugins/skill-workshop.md @@ -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 /skills//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` - 已写入 `/skills` - `rejected` - 已被操作员 / 模型拒绝 -- `quarantined` - 因严重扫描发现而被阻止 +- `quarantined` - 因扫描器发现严重问题而被阻止 状态按工作区存储在 Gateway 网关状态目录下： @@ -290,7 +259,7 @@ Skill Workshop 有三种捕获路径。 /skill-workshop/.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-workshop: quarantined ` 时，请使用这个命令。 ### `inspect` @@ -364,7 +333,7 @@ skill_workshop ### `suggest` -创建一个提案。当使用 `approvalPolicy: "pending"` 时，默认会将其加入队列。 +创建一个提案。当使用 `approvalPolicy: "pending"`（默认值）时，这会加入队列，而不是直接写入。 ```json { @@ -377,7 +346,8 @@ skill_workshop } ``` -强制安全写入： + + ```json { @@ -389,7 +359,9 @@ skill_workshop } ``` -即使在 `approvalPolicy: "auto"` 下也强制进入待处理状态： + + + ```json { @@ -401,7 +373,9 @@ skill_workshop } ``` -向某个章节追加内容： + + + ```json { @@ -413,7 +387,9 @@ skill_workshop } ``` -替换精确文本： + + + ```json { @@ -424,6 +400,9 @@ skill_workshop } ``` + + + ### `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 /skills// ``` -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 模式。 ## 相关文档