chore(i18n): refresh zh-CN translations

2026-04-24 02:45:08 +00:00 · 2026-04-24 02:45:08 +00:00 · 82db5df76e
commit 82db5df76e
parent bc8d2086a7
3 changed files with 848 additions and 815 deletions
--- a/docs/zh-CN/help/testing-live.md
+++ b/docs/zh-CN/help/testing-live.md
@ -0,0 +1,501 @@
+---
+read_when:
+    - 运行实时模型矩阵 / CLI 后端 / ACP / 媒体提供商冒烟测试
+    - 调试实时测试凭证解析
+    - 添加新的提供商专用实时测试
+summary: 实时（涉及网络）的测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
+title: 测试——实时测试套件
+x-i18n:
+    generated_at: "2026-04-24T02:42:22Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: 097c6d6422cd66bb4dae90bd4585dfaf6bc6184c5cfd3f27aa5dda4f04954dcc
+    source_path: help/testing-live.md
+    workflow: 15
+---
+
+有关快速开始、QA 运行器、单元 / 集成测试套件以及 Docker 流程，请参阅
+[测试](/zh-CN/help/testing)。本页介绍**实时**（涉及网络）的测试
+套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及
+凭证处理。
+
+## 实时：Android 节点能力全面检测
+
+- 测试：`src/gateway/android-node.capabilities.live.test.ts`
+- 脚本：`pnpm android:test:integration`
+- 目标：调用已连接 Android 节点**当前公布的每一条命令**，并断言命令契约行为。
+- 范围：
+  - 已预先准备 / 需手动完成的设置（该测试套件不会安装 / 运行 / 配对应用）。
+  - 针对所选 Android 节点，逐条命令进行 Gateway 网关 `node.invoke` 验证。
+- 必需的预先设置：
+  - Android 应用已连接并与 Gateway 网关完成配对。
+  - 应用保持在前台。
+  - 你期望通过的能力所需的权限 / 捕获授权已授予。
+- 可选目标覆盖：
+  - `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
+  - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
+- 完整的 Android 设置详情： [Android App](/zh-CN/platforms/android)
+
+## 实时：模型冒烟测试（配置档案键）
+
+实时测试分为两层，以便我们隔离故障：
+
+- “Direct model” 用于确认提供商 / 模型在给定密钥下是否至少能够响应。
+- “Gateway smoke” 用于确认该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史记录、工具、沙箱策略等）。
+
+### 第 1 层：直接模型补全（无 Gateway 网关）
+
+- 测试：`src/agents/models.profiles.live.test.ts`
+- 目标：
+  - 枚举已发现的模型
+  - 使用 `getApiKeyForModel` 选择你拥有凭证的模型
+  - 对每个模型运行一次小型补全（并在需要时运行定向回归测试）
+- 启用方式：
+  - `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
+- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会实际运行该测试套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
+- 选择模型的方式：
+  - `OPENCLAW_LIVE_MODELS=modern` 运行 modern 允许列表（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
+  - `OPENCLAW_LIVE_MODELS=all` 是 modern 允许列表的别名
+  - 或者 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."`（逗号分隔的允许列表）
+  - modern / all 全量检测默认带有一个精心挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行完整的 modern 全量检测，或设置为正数以使用更小的上限。
+- 选择提供商的方式：
+  - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的允许列表）
+- 键的来源：
+  - 默认：配置档案存储和环境变量回退
+  - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用配置档案存储**
+- 存在原因：
+  - 将“提供商 API 已损坏 / 密钥无效”与“Gateway 网关智能体流水线已损坏”区分开来
+  - 容纳小型、隔离的回归测试（例如：OpenAI Responses / Codex Responses 推理回放 + 工具调用流程）
+
+### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（也就是 “@openclaw” 实际执行的内容）
+
+- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
+- 目标：
+  - 启动一个进程内 Gateway 网关
+  - 创建 / 修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
+  - 遍历带有密钥的模型并断言：
+    - 有“有意义”的响应（无工具）
+    - 真实工具调用可正常工作（read 探针）
+    - 可选的额外工具探针（exec+read 探针）
+    - OpenAI 回归路径（仅工具调用 → 后续跟进）持续可用
+- 探针详情（这样你可以更快解释失败原因）：
+  - `read` 探针：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。
+  - `exec+read` 探针：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。
+  - 图像探针：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
+  - 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
+- 启用方式：
+  - `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
+- 选择模型的方式：
+  - 默认：modern 允许列表（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
+  - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern 允许列表的别名
+  - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）来缩小范围
+  - modern / all Gateway 网关全量检测默认带有一个精心挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行完整的 modern 全量检测，或设置为正数以使用更小的上限。
+- 选择提供商的方式（避免 “OpenRouter everything”）：
+  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的允许列表）
+- 工具 + 图像探针在该实时测试中始终启用：
+  - `read` 探针 + `exec+read` 探针（工具压力测试）
+  - 当模型声明支持图像输入时，运行图像探针
+  - 流程（高级概览）：
+    - 测试生成一个带有 “CAT” + 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
+    - 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送
+    - Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
+    - 嵌入式智能体将多模态用户消息转发给模型
+    - 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）
+
+提示：要查看你在自己机器上可以测试哪些内容（以及准确的 `provider/model` id），请运行：
+
+```bash
+openclaw models list
+openclaw models list --json
+```
+
+## 实时：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
+
+- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
+- 目标：在不触碰你的默认配置的情况下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。
+- 特定后端的冒烟测试默认值位于所属扩展的 `cli-backend.ts` 定义中。
+- 启用：
+  - `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
+  - `OPENCLAW_LIVE_CLI_BACKEND=1`
+- 默认值：
+  - 默认提供商 / 模型：`claude-cli/claude-sonnet-4-6`
+  - 命令 / 参数 / 图像行为来自所属 CLI 后端插件元数据。
+- 覆盖项（可选）：
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示词中）。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 通过 CLI 参数传递图像文件路径，而不是注入到提示词中。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）控制在设置 `IMAGE_ARG` 时如何传递图像参数。
+  - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮消息并验证恢复流程。
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` 禁用默认的 Claude Sonnet -> Opus 同一会话连续性探针（当所选模型支持切换目标时，设置为 `1` 可强制启用）。
+
+示例：
+
+```bash
+OPENCLAW_LIVE_CLI_BACKEND=1 \
+  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5" \
+  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
+```
+
+Docker 配方：
+
+```bash
+pnpm test:docker:live-cli-backend
+```
+
+单提供商 Docker 配方：
+
+```bash
+pnpm test:docker:live-cli-backend:claude
+pnpm test:docker:live-cli-backend:claude-subscription
+pnpm test:docker:live-cli-backend:codex
+pnpm test:docker:live-cli-backend:gemini
+```
+
+说明：
+
+- Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
+- 它会在仓库 Docker 镜像内，以非 root 的 `node` 用户身份运行实时 CLI 后端冒烟测试。
+- 它会从所属扩展解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到一个带缓存的可写前缀目录 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认：`~/.cache/openclaw/docker-cli-tools`）。
+- `pnpm test:docker:live-cli-backend:claude-subscription` 要求通过以下任一方式提供可移植的 Claude Code 订阅 OAuth：`~/.claude/.credentials.json` 中带有 `claudeAiOauth.subscriptionType`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN`。它会先在 Docker 中直接验证 `claude -p`，然后在不保留 Anthropic API 键环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。此订阅测试通道默认禁用 Claude MCP / 工具及图像探针，因为 Claude 当前会将第三方应用用量计入额外使用计费，而不是普通订阅计划限额。
+- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
+- Claude 的默认冒烟测试还会将会话从 Sonnet 修补到 Opus，并验证恢复后的会话仍记得之前的备注。
+
+## 实时：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
+
+- 测试：`src/gateway/gateway-acp-bind.live.test.ts`
+- 目标：使用实时 ACP 智能体验证真实 ACP 会话绑定流程：
+  - 发送 `/acp spawn <agent> --bind here`
+  - 就地绑定一个合成的消息渠道会话
+  - 在同一会话上发送普通后续消息
+  - 验证该后续消息落入已绑定的 ACP 会话记录中
+- 启用：
+  - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
+  - `OPENCLAW_LIVE_ACP_BIND=1`
+- 默认值：
+  - Docker 中的 ACP 智能体：`claude,codex,gemini`
+  - 直接 `pnpm test:live ...` 使用的 ACP 智能体：`claude`
+  - 合成渠道：Slack 私信风格的会话上下文
+  - ACP 后端：`acpx`
+- 覆盖项：
+  - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
+  - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex`
+  - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini`
+  - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini`
+  - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'`
+  - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5`
+  - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.4`
+- 说明：
+  - 该测试通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成 originating-route 字段，以便测试可以附加消息渠道上下文，而无需伪装成外部投递。
+  - 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用嵌入式 `acpx` 插件的内置智能体注册表来启动所选 ACP 测试智能体。
+
+示例：
+
+```bash
+OPENCLAW_LIVE_ACP_BIND=1 \
+  OPENCLAW_LIVE_ACP_BIND_AGENT=claude \
+  pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
+```
+
+Docker 配方：
+
+```bash
+pnpm test:docker:live-acp-bind
+```
+
+单智能体 Docker 配方：
+
+```bash
+pnpm test:docker:live-acp-bind:claude
+pnpm test:docker:live-acp-bind:codex
+pnpm test:docker:live-acp-bind:gemini
+```
+
+Docker 说明：
+
+- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
+- 默认情况下，它会按顺序对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。
+- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可缩小矩阵范围。
+- 它会读取 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，把 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。
+- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 `acpx` 就能让来自已加载 profile 的提供商环境变量继续对其子测试 CLI 可用。
+
+## 实时：Codex app-server 测试支架冒烟测试
+
+- 目标：通过常规 Gateway 网关
+  `agent` 方法验证插件自有的 Codex 测试支架：
+  - 加载内置的 `codex` 插件
+  - 选择 `OPENCLAW_AGENT_RUNTIME=codex`
+  - 在强制使用 Codex 测试支架的情况下，向 `openai/gpt-5.4` 发送第一轮 Gateway 网关智能体请求
+  - 向同一个 OpenClaw 会话发送第二轮请求，并验证 app-server
+    线程可以恢复
+  - 通过相同的 Gateway 网关命令
+    路径运行 `/codex status` 和 `/codex models`
+  - 可选运行两个经 Guardian 审核的提权 shell 探针：一个应被批准的
+    无害命令，以及一个应被拒绝的伪造密钥上传命令，
+    以便智能体回问
+- 测试：`src/gateway/gateway-codex-harness.live.test.ts`
+- 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
+- 默认模型：`openai/gpt-5.4`
+- 可选图像探针：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
+- 可选 MCP / 工具探针：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
+- 可选 Guardian 探针：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
+- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex
+  测试支架无法通过静默回退到 PI 来蒙混过关。
+- 认证：Codex app-server 认证来自本地 Codex 订阅登录。Docker
+  冒烟测试在适用时也可以为非 Codex 探针提供 `OPENAI_API_KEY`，
+  另外还可选复制 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
+
+本地配方：
+
+```bash
+source ~/.profile
+OPENCLAW_LIVE_CODEX_HARNESS=1 \
+  OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \
+  OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \
+  OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \
+  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.4 \
+  pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts
+```
+
+Docker 配方：
+
+```bash
+source ~/.profile
+pnpm test:docker:live-codex-harness
+```
+
+Docker 说明：
+
+- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
+- 它会读取已挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
+  认证文件，将 `@openai/codex` 安装到一个可写且已挂载的 npm
+  前缀中，暂存源码树，然后仅运行 Codex 测试支架实时测试。
+- Docker 默认启用图像、MCP / 工具以及 Guardian 探针。需要更窄的调试
+  运行时，可设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或
+  `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或
+  `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
+- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与实时
+  测试配置保持一致，因此旧别名或 PI 回退都无法掩盖 Codex 测试支架
+  回归问题。
+
+### 推荐的实时测试配方
+
+范围窄且明确的允许列表速度最快，也最不容易波动：
+
+- 单模型，直接调用（无 Gateway 网关）：
+  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
+
+- 单模型，Gateway 网关冒烟测试：
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+- 跨多个提供商的工具调用：
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+- Google 聚焦（Gemini API key + Antigravity）：
+  - Gemini（API key）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+说明：
+
+- `google/...` 使用 Gemini API（API key）。
+- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
+- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具链差异）。
+- Gemini API 与 Gemini CLI：
+  - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / 配置档案认证）；这就是大多数用户所说的 “Gemini”。
+  - CLI：OpenClaw 通过 shell 调用本地 `gemini` 二进制；它有自己的认证方式，行为也可能不同（流式传输 / 工具支持 / 版本偏差）。
+
+## 实时：模型矩阵（我们的覆盖范围）
+
+这里没有固定的 “CI 模型列表”（实时测试是可选启用的），但以下是建议在带有密钥的开发机器上定期覆盖的**推荐**模型。
+
+### 现代冒烟测试集（工具调用 + 图像）
+
+这是我们预期应持续正常工作的 “常用模型” 运行集：
+
+- OpenAI（非 Codex）：`openai/gpt-5.4`（可选：`openai/gpt-5.4-mini`）
+- OpenAI Codex OAuth：`openai-codex/gpt-5.5`
+- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
+- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型）
+- Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash`
+- Z.AI（GLM）：`zai/glm-4.7`
+- MiniMax：`minimax/MiniMax-M2.7`
+
+使用工具 + 图像运行 Gateway 网关冒烟测试：
+`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+### 基线：工具调用（Read + 可选 Exec）
+
+每个提供商家族至少选一个：
+
+- OpenAI：`openai/gpt-5.4`（或 `openai/gpt-5.4-mini`）
+- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
+- Google：`google/gemini-3-flash-preview`（或 `google/gemini-3.1-pro-preview`）
+- Z.AI（GLM）：`zai/glm-4.7`
+- MiniMax：`minimax/MiniMax-M2.7`
+
+可选的额外覆盖（有的话更好）：
+
+- xAI：`xai/grok-4`（或当前最新可用版本）
+- Mistral：`mistral/`…（选择一个你已启用、支持 `tools` 的模型）
+- Cerebras：`cerebras/`…（如果你有访问权限）
+- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
+
+### 视觉：图像发送（附件 → 多模态消息）
+
+在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 的支持视觉的变体等），以覆盖图像探针。
+
+### 聚合器 / 替代 Gateway 网关
+
+如果你已启用相应密钥，我们也支持通过以下方式测试：
+
+- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选项）
+- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
+
+你还可以纳入实时矩阵的更多提供商（如果你有凭证 / 配置）：
+
+- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
+- 通过 `models.providers`（自定义端点）：`minimax`（云 / API），以及任何兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
+
+提示：不要试图在文档中硬编码 “所有模型”。权威列表是你机器上 `discoverModels(...)` 返回的内容，以及当前可用的所有密钥。
+
+## 凭证（切勿提交）
+
+实时测试发现凭证的方式与 CLI 相同。实际含义如下：
+
+- 如果 CLI 能工作，实时测试应该也能找到相同的密钥。
+- 如果实时测试提示 “no creds”，请按你调试 `openclaw models list` / 模型选择时的方式来排查。
+
+- 每个智能体的认证配置档案：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义）
+- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
+- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时 home 中，但它不是主要的配置档案键存储）
+- 默认情况下，本地实时运行会将活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时 home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，这样探针就不会落到你真实主机的工作区中。
+
+如果你想依赖环境变量中的密钥（例如导出在你的 `~/.profile` 中），请在本地测试前运行 `source ~/.profile`，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
+
+## Deepgram 实时测试（音频转录）
+
+- 测试：`extensions/deepgram/audio.live.test.ts`
+- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
+
+## BytePlus（国际版）编码计划实时测试
+
+- 测试：`extensions/byteplus/live.test.ts`
+- 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
+- 可选模型覆盖：`BYTEPLUS_CODING_MODEL=ark-code-latest`
+
+## ComfyUI 工作流媒体实时测试
+
+- 测试：`extensions/comfy/comfy.live.test.ts`
+- 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
+- 范围：
+  - 覆盖内置 comfy 图像、视频和 `music_generate` 路径
+  - 如果未配置 `models.providers.comfy.<capability>`，则跳过各项能力
+  - 在修改 comfy 工作流提交、轮询、下载或插件注册后很有用
+
+## 图像生成实时测试
+
+- 测试：`test/image-generation.runtime.live.test.ts`
+- 命令：`pnpm test:live test/image-generation.runtime.live.test.ts`
+- 测试支架：`pnpm test:live:media image`
+- 范围：
+  - 枚举每个已注册的图像生成提供商插件
+  - 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
+  - 默认优先使用实时 / 环境变量 API 键，而不是已存储的认证配置档案，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
+  - 跳过没有可用认证 / 配置档案 / 模型的提供商
+  - 通过共享运行时能力运行标准图像生成变体：
+    - `google:flash-generate`
+    - `google:pro-generate`
+    - `google:pro-edit`
+    - `openai:default-generate`
+- 当前覆盖的内置提供商：
+  - `fal`
+  - `google`
+  - `minimax`
+  - `openai`
+  - `openrouter`
+  - `vydra`
+  - `xai`
+- 可选缩小范围：
+  - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"`
+  - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
+  - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
+- 可选认证行为：
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置档案存储认证，并忽略仅存在于环境变量中的覆盖
+
+## 音乐生成实时测试
+
+- 测试：`extensions/music-generation-providers.live.test.ts`
+- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
+- 测试支架：`pnpm test:live:media music`
+- 范围：
+  - 覆盖共享的内置音乐生成提供商路径
+  - 当前覆盖 Google 和 MiniMax
+  - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
+  - 默认优先使用实时 / 环境变量 API 键，而不是已存储的认证配置档案，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
+  - 跳过没有可用认证 / 配置档案 / 模型的提供商
+  - 在可用时运行两种已声明的运行时模式：
+    - `generate`，仅使用提示词输入
+    - 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
+  - 当前共享测试通道覆盖：
+    - `google`：`generate`、`edit`
+    - `minimax`：`generate`
+    - `comfy`：单独的 Comfy 实时文件，不在此共享检测中
+- 可选缩小范围：
+  - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
+  - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
+- 可选认证行为：
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置档案存储认证，并忽略仅存在于环境变量中的覆盖
+
+## 视频生成实时测试
+
+- 测试：`extensions/video-generation-providers.live.test.ts`
+- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
+- 测试支架：`pnpm test:live:media video`
+- 范围：
+  - 覆盖共享的内置视频生成提供商路径
+  - 默认使用适合发布的冒烟测试路径：非 FAL 提供商、每个提供商一个文生视频请求、一秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认为 `180000`）
+  - 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
+  - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
+  - 默认优先使用实时 / 环境变量 API 键，而不是已存储的认证配置档案，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
+  - 跳过没有可用认证 / 配置档案 / 模型的提供商
+  - 默认仅运行 `generate`
+  - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，如果可用，还会运行已声明的转换模式：
+    - 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商 / 模型在共享检测中接受基于缓冲区的本地图像输入时，运行 `imageToVideo`
+    - 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享检测中接受基于缓冲区的本地视频输入时，运行 `videoToVideo`
+  - 当前在共享检测中已声明但被跳过的 `imageToVideo` 提供商：
+    - `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
+  - 提供商专用的 Vydra 覆盖：
+    - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
+    - 该文件会运行 `veo3` 文生视频，以及默认使用远程图像 URL 固定样例的 `kling` 测试通道
+  - 当前 `videoToVideo` 实时覆盖：
+    - 仅 `runway`，且所选模型为 `runway/gen4_aleph`
+  - 当前在共享检测中已声明但被跳过的 `videoToVideo` 提供商：
+    - `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
+    - `google`，因为当前共享 Gemini / Veo 测试通道使用基于本地缓冲区的输入，而该路径在共享检测中不被接受
+    - `openai`，因为当前共享测试通道缺乏组织特定的视频修补 / remix 访问保证
+- 可选缩小范围：
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"`
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 可在默认检测中包含所有提供商，包括 FAL
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可在激进的冒烟测试中降低每个提供商的操作上限
+- 可选认证行为：
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置档案存储认证，并忽略仅存在于环境变量中的覆盖
+
+## 媒体实时测试支架
+
+- 命令：`pnpm test:live:media`
+- 目的：
+  - 通过单一仓库原生入口点运行共享的图像、音乐和视频实时测试套件
+  - 自动从 `~/.profile` 加载缺失的提供商环境变量
+  - 默认自动将每个测试套件缩小到当前具有可用认证的提供商
+  - 复用 `scripts/test-live.mjs`，因此心跳和静默模式行为保持一致
+- 示例：
+  - `pnpm test:live:media`
+  - `pnpm test:live:media image video --providers openai,google,minimax`
+  - `pnpm test:live:media video --video-providers openai,runway --all-providers`
+  - `pnpm test:live:media music --quiet`
+
+## 相关内容
+
+- [测试](/zh-CN/help/testing) —— 单元、集成、QA 和 Docker 测试套件
--- a/docs/zh-CN/help/testing.md
+++ b/docs/zh-CN/help/testing.md
--- a/docs/zh-CN/plugins/codex-harness.md
+++ b/docs/zh-CN/plugins/codex-harness.md
@ -1,24 +1,24 @@
 ---
 read_when:
-    - 你想使用内置的 Codex app-server 测试框架
+    - 你想使用内置的 Codex app-server 测试工具
    - 你需要 Codex 模型引用和配置示例
-    - 你想为仅使用 Codex 的部署禁用 PI 回退
-summary: 通过内置的 Codex app-server 测试框架运行 OpenClaw 嵌入式智能体回合
-title: Codex 测试框架
+    - 你想为仅使用 Codex 的部署禁用 Pi 回退机制
+summary: 通过内置的 Codex app-server 测试工具运行 OpenClaw 嵌入式智能体轮次
+title: Codex 测试工具
 x-i18n:
-    generated_at: "2026-04-24T00:54:22Z"
+    generated_at: "2026-04-24T02:42:21Z"
    model: gpt-5.4
    provider: openai
-    source_hash: e2d12f877e27080a0b91b5c597b171f25fbdc74756bf040d483e3da4461f1d7c
+    source_hash: c56024e68540007c60e2bfcc4d090a788736dc941290cd82ed83b19aadde942d
    source_path: plugins/codex-harness.md
    workflow: 15
 ---

-内置的 `codex` 插件让 OpenClaw 能够通过 Codex app-server 运行嵌入式智能体回合，而不是使用内置的 PI 测试框架。
+内置的 `codex` 插件可让 OpenClaw 通过 Codex app-server 而不是内置的 Pi 测试工具来运行嵌入式智能体轮次。

-当你希望 Codex 接管底层智能体会话时，可以使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。
+当你希望由 Codex 接管底层智能体会话时，可使用此功能：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。

-原生 Codex 回合也会遵循共享的插件钩子，因此提示词 shim、压缩感知自动化、工具中间件和生命周期观察器都能与 PI 测试框架保持一致：
+原生 Codex 轮次同样遵循共享的插件钩子，因此 prompt shim、压缩感知自动化、工具中间件和生命周期观察器都会与 Pi 测试工具保持一致：

 - `before_prompt_build`
 - `before_compaction`, `after_compaction`
@ -27,48 +27,47 @@ x-i18n:
 - `before_message_write`
 - `agent_end`

-内置插件还可以注册一个 Codex app-server 扩展工厂，以添加异步 `tool_result` 中间件。
+内置插件还可以注册 Codex app-server 扩展工厂，以添加异步 `tool_result` 中间件。

-该测试框架默认关闭。新配置应保持 OpenAI 模型引用的规范形式为 `openai/gpt-*`，并在希望使用原生 app-server 执行时，显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。为兼容性考虑，旧版 `codex/*` 模型引用仍会自动选择该测试框架。
+该测试工具默认关闭。新配置应保持 OpenAI 模型引用的规范形式为 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。出于兼容性考虑，旧版 `codex/*` 模型引用仍会自动选择该测试工具。

 ## 选择正确的模型前缀

-OpenAI 系列路由对前缀非常敏感。当你希望通过 PI 使用 Codex OAuth 时，请使用 `openai-codex/*`；当你希望直接访问 OpenAI API，或希望强制使用原生 Codex app-server 测试框架时，请使用 `openai/*`：
+OpenAI 系列路由对前缀有明确要求。当你希望通过 Pi 使用 Codex OAuth 时，使用 `openai-codex/*`；当你希望直接访问 OpenAI API，或强制使用原生 Codex app-server 测试工具时，使用 `openai/*`：

-| 模型引用 | 运行时路径 | 适用场景 |
+| 模型引用                                              | 运行时路径                                   | 适用场景                                                                  |
 | ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
-| `openai/gpt-5.4` | 通过 OpenClaw/PI 管线的 OpenAI 提供商 | 你希望使用 `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 测试框架 | 你希望嵌入式智能体回合使用原生 Codex app-server 执行。 |
+| `openai/gpt-5.4`                                      | 通过 OpenClaw/Pi 线路的 OpenAI 提供商路径    | 你希望使用 `OPENAI_API_KEY` 直接访问当前的 OpenAI Platform API。          |
+| `openai-codex/gpt-5.5`                                | 通过 OpenClaw/Pi 的 OpenAI Codex OAuth 路径  | 你希望使用 ChatGPT/Codex 订阅凭证，并采用默认的 Pi 运行器。               |
+| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server 测试工具                    | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。                  |

-GPT-5.5 当前在 OpenClaw 中仅支持订阅/OAuth。请将 `openai-codex/gpt-5.5` 用于 PI OAuth，或将 `openai/gpt-5.5` 与 Codex app-server 测试框架一起使用。一旦 OpenAI 在公共 API 中开放 GPT-5.5，对 `openai/gpt-5.5` 的直接 API key 访问也会被支持。
+在 OpenClaw 中，GPT-5.5 目前仅支持订阅 / OAuth。对于 Pi OAuth，使用 `openai-codex/gpt-5.5`；对于 Codex app-server 测试工具，使用 `openai/gpt-5.5`。一旦 OpenAI 在公共 API 上启用 GPT-5.5，`openai/gpt-5.5` 的直接 API key 访问也将受支持。

-旧版 `codex/gpt-*` 引用仍然作为兼容性别名被接受。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server 测试框架配置应使用 `openai/gpt-*`，并配合 `embeddedHarness.runtime:
-"codex"`。
+旧版 `codex/gpt-*` 引用仍接受为兼容性别名。新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server 测试工具配置应使用 `openai/gpt-*`，并配合 `embeddedHarness.runtime: "codex"`。

-`agents.defaults.imageModel` 遵循相同的前缀拆分。当图像理解应通过 OpenAI Codex OAuth 提供商路径运行时，请使用 `openai-codex/gpt-*`。当图像理解应通过受限的 Codex app-server 回合运行时，请使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；仅文本的 Codex 模型会在媒体回合开始前失败。
+`agents.defaults.imageModel` 遵循相同的前缀区分。当图像理解应通过 OpenAI Codex OAuth 提供商路径运行时，使用 `openai-codex/gpt-*`。当图像理解应通过受限的 Codex app-server 轮次运行时，使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；仅文本的 Codex 模型会在媒体轮次开始前失败。

-使用 `/status` 确认当前会话的实际测试框架。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含所选测试框架 id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。
+使用 `/status` 可确认当前会话的实际测试工具。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关中的结构化 `agent harness selected` 记录。它包含所选测试工具 id、选择原因、运行时 / 回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。

-测试框架选择不是实时会话控制。当嵌入式回合运行时，OpenClaw 会在该会话上记录选中的测试框架 id，并在同一会话 id 的后续回合中继续使用它。当你希望未来的会话改用其他测试框架时，请更改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在将现有对话在 PI 和 Codex 之间切换前，请使用 `/new` 或 `/reset` 启动一个新会话。这样可以避免通过两个不兼容的原生会话系统重放同一份转录。
+测试工具选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会把所选测试工具 id 记录到该会话上，并在同一会话 id 的后续轮次中继续使用它。当你希望未来的新会话使用其他测试工具时，请更改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有对话于 Pi 和 Codex 之间切换前，请使用 `/new` 或 `/reset` 启动一个全新的会话。这样可以避免将同一份转录内容通过两个不兼容的原生会话系统重复回放。

-在引入测试框架固定机制之前创建的旧会话，只要已有转录历史，就会被视为固定使用 PI。更改配置后，请使用 `/new` 或 `/reset` 让该对话改为使用 Codex。
+在测试工具固定机制引入之前创建的旧会话，一旦已有转录历史，就会被视为固定到 Pi。更改配置后，使用 `/new` 或 `/reset` 可让该对话改为使用 Codex。

-`/status` 会在 `Fast` 旁边显示实际使用的非 PI 测试框架，例如 `Fast · codex`。默认的 PI 测试框架仍显示为 `Runner: pi (embedded)`，不会额外添加单独的测试框架标记。
+`/status` 会在 `Fast` 旁显示实际生效的非 Pi 测试工具，例如 `Fast · codex`。默认的 Pi 测试工具仍显示为 `Runner: pi (embedded)`，不会额外添加单独的测试工具标记。

 ## 要求

- OpenClaw，并且可用内置的 `codex` 插件。
+- OpenClaw，且已提供内置的 `codex` 插件。
 - Codex app-server `0.118.0` 或更高版本。
- app-server 进程可使用 Codex 认证。
+- app-server 进程可用的 Codex 认证信息。

-该插件会阻止较旧或未标注版本的 app-server 握手。这可确保 OpenClaw 使用的是已经过测试的协议表面。
+该插件会阻止较旧版本或无版本信息的 app-server 握手。这可确保 OpenClaw 仅运行在已验证的协议接口之上。

 对于实时和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。

 ## 最小配置

-使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` 测试框架：
+使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` 测试工具：

 ```json5
 {
@ -91,7 +90,7 @@ GPT-5.5 当前在 OpenClaw 中仅支持订阅/OAuth。请将 `openai-codex/gpt-5
 }
 ```

-如果你的配置使用了 `plugins.allow`，也请将 `codex` 包含在其中：
+如果你的配置使用 `plugins.allow`，也请在其中加入 `codex`：

 ```json5
 {
@ -106,11 +105,11 @@ GPT-5.5 当前在 OpenClaw 中仅支持订阅/OAuth。请将 `openai-codex/gpt-5
 }
 ```

-如果旧配置将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>`，仍会自动启用内置的 `codex` 插件。新配置应优先使用 `openai/<model>`，并配合上面的显式 `embeddedHarness` 条目。
+旧配置如果将 `agents.defaults.model` 或某个智能体模型设为 `codex/<model>`，仍会自动启用内置 `codex` 插件。新配置应优先使用 `openai/<model>`，并配合上面的显式 `embeddedHarness` 配置项。

-## 添加 Codex 而不替换其他模型
+## 在不替换其他模型的情况下加入 Codex

-如果你希望旧版 `codex/*` 引用选择 Codex，而其他情况都使用 PI，请保持 `runtime: "auto"`。对于新配置，建议在应使用该测试框架的智能体上显式设置 `runtime: "codex"`。
+如果你希望旧版 `codex/*` 引用选择 Codex，而其他一切仍使用 Pi，请保持 `runtime: "auto"`。对于新配置，建议仅在应使用该测试工具的智能体上显式设置 `runtime: "codex"`。

 ```json5
 {
@ -140,15 +139,15 @@ GPT-5.5 当前在 OpenClaw 中仅支持订阅/OAuth。请将 `openai-codex/gpt-5
 }
 ```

-采用这种形式时：
+在这种结构下：

- `/model gpt` 或 `/model openai/gpt-5.5` 会在此配置中使用 Codex app-server 测试框架。
+- `/model gpt` 或 `/model openai/gpt-5.5` 会为此配置使用 Codex app-server 测试工具。
 - `/model opus` 使用 Anthropic 提供商路径。
- 如果选择了非 Codex 模型，PI 仍然是兼容性测试框架。
+- 如果选择了非 Codex 模型，Pi 仍然是兼容性测试工具。

-## 仅 Codex 部署
+## 仅使用 Codex 的部署

-当你需要证明每个嵌入式智能体回合都使用 Codex 测试框架时，请禁用 PI 回退：
+当你需要证明每一个嵌入式智能体轮次都使用 Codex 测试工具时，请禁用 Pi 回退：

 ```json5
 {
@ -172,11 +171,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
 openclaw gateway run
 ```

-禁用回退后，如果 Codex 插件被禁用、app-server 版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败。
+禁用回退后，如果 Codex 插件被禁用、app-server 版本过旧，或 app-server 无法启动，OpenClaw 会提前失败。

 ## 按智能体使用 Codex

-你可以让某个智能体仅使用 Codex，而默认智能体继续保持正常的自动选择：
+你可以让某一个智能体仅使用 Codex，而默认智能体仍保持普通的自动选择：

 ```json5
 {
@ -207,17 +206,17 @@ openclaw gateway run
 }
 ```

-使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex 测试框架会根据需要创建或恢复其 sidecar app-server 线程。`/reset` 会清除 OpenClaw 针对该线程的会话绑定，并让下一回合重新根据当前配置解析测试框架。
+使用常规会话命令切换智能体和模型。`/new` 会创建一个全新的 OpenClaw 会话，而 Codex 测试工具会按需创建或恢复其旁路 app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮再次根据当前配置解析测试工具。

 ## 模型发现

-默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置的回退目录，其中包含：
+默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置的后备目录，其中包括：

 - GPT-5.5
 - GPT-5.4 mini
 - GPT-5.2

-你可以在 `plugins.entries.codex.config.discovery` 下调整发现配置：
+你可以在 `plugins.entries.codex.config.discovery` 下调整发现行为：

 ```json5
 {
@ -237,7 +236,7 @@ openclaw gateway run
 }
 ```

-如果你希望启动时避免探测 Codex，并固定使用回退目录，请禁用发现：
+如果你希望启动时避免探测 Codex 并固定使用后备目录，可禁用发现：

 ```json5
 {
@ -258,16 +257,15 @@ openclaw gateway run

 ## App-server 连接与策略

-默认情况下，插件会使用以下命令在本地启动 Codex：
+默认情况下，插件会以本地方式启动 Codex：

 ```bash
 codex app-server --listen stdio://
 ```

-默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex 测试框架会话：`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:
-"guardian"`：
+如需启用由 Codex guardian 审核的审批，请设置 `appServer.mode: "guardian"`：

 ```json5
 {
@ -287,11 +285,11 @@ codex app-server --listen stdio://
 }
 ```

-Guardian 是一个原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加如网络访问之类的权限时，Codex 会将该审批请求路由给审核子智能体，而不是生成人工提示。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多护栏，但仍需要无人值守的智能体持续推进工作，请使用 Guardian。
+Guardian 是原生 Codex 审批审查者。当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给审查子智能体，而不是提示人工。审查者会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你需要比 YOLO 模式更多的防护措施，但仍希望无人值守的智能体继续推进任务时，请使用 Guardian。

-`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。
+`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"`，以及 `sandbox: "workspace-write"`。各个策略字段仍可覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。

-对于已经运行的 app-server，请使用 WebSocket 传输：
+对于已在运行的 app-server，可使用 WebSocket 传输：

 ```json5
 {
@ -315,20 +313,20 @@ Guardian 是一个原生 Codex 审批审核器。当 Codex 请求离开沙箱、

 支持的 `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`。无效的旧值会被忽略。                     |

 较旧的环境变量在对应配置字段未设置时，仍可作为本地测试的回退方式使用：

@ -338,13 +336,11 @@ Guardian 是一个原生 Codex 审批审核器。当 Codex 请求离开沙箱、
 - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
 - `OPENCLAW_CODEX_APP_SERVER_SANDBOX`

-`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 测试工具其余设置保存在同一个已审阅的文件中。

 ## 常见配方

-使用默认 `stdio` 传输的本地 Codex：
+使用默认 stdio 传输的本地 Codex：

 ```json5
 {
@ -358,7 +354,7 @@ Guardian 是一个原生 Codex 审批审核器。当 Codex 请求离开沙箱、
 }
 ```

-仅 Codex 的测试框架验证，并禁用 PI 回退：
+仅使用 Codex 的测试工具验证，并禁用 Pi 回退：

 ```json5
 {
@ -375,7 +371,7 @@ Guardian 是一个原生 Codex 审批审核器。当 Codex 请求离开沙箱、
 }
 ```

-由 Guardian 审核的 Codex 审批：
+使用 guardian 审核的 Codex 审批：

 ```json5
 {
@ -420,63 +416,57 @@ Guardian 是一个原生 Codex 审批审核器。当 Codex 请求离开沙箱、
 }
 ```

-模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有 Codex 线程时，下一回合会再次向 app-server 发送当前选定的 OpenAI 模型、提供商、审批策略、沙箱和服务层级。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 时，会保留线程绑定，但会请求 Codex 继续使用新选定的模型。
+模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有的 Codex 线程时，下一轮会再次把当前选中的 OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给 app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选择的模型继续运行。

 ## Codex 命令

-内置插件将 `/codex` 注册为授权斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。
+内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用命令，可在任何支持 OpenClaw 文本命令的渠道上使用。

 常见形式：

- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和技能。
- `/codex models` 列出实时 Codex app-server 模型。
+- `/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 account` 显示账户和速率限制状态。
+- `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有的 Codex 线程。
+- `/codex compact` 请求 Codex app-server 压缩当前附加的线程。
+- `/codex review` 为当前附加的线程启动 Codex 原生审查。
+- `/codex account` 显示账号和速率限制状态。
 - `/codex mcp` 列出 Codex app-server MCP 服务器状态。
 - `/codex skills` 列出 Codex app-server Skills。

-`/codex resume` 会写入与测试框架正常回合使用的相同 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持启用扩展历史记录。
+`/codex resume` 会写入与测试工具正常轮次所使用的同一 sidecar 绑定文件。在下一条消息到来时，OpenClaw 会恢复该 Codex 线程，把当前选中的 OpenClaw 模型传入 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 测试框架只改变底层嵌入式智能体执行器。
+Codex 测试工具仅改变底层嵌入式智能体执行器。

-OpenClaw 仍然构建工具列表，并从测试框架接收动态工具结果。文本、图像、视频、音乐、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 测试框架时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一份转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或测试框架切换。该镜像包含用户提示、最终助手文本，以及 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`，选择带有 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），并检查 `plugins.allow` 是否排除了 `codex`。
+**`/model` 中没有出现 Codex：** 启用 `plugins.entries.codex.enabled`，选择一个带有 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），并检查 `plugins.allow` 是否排除了 `codex`。

-**OpenClaw 使用了 PI 而不是 Codex：** 如果没有 Codex 测试框架接管此次运行，OpenClaw 可能会使用 PI 作为兼容性后端。测试时可设置
-`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置
-`embeddedHarness.fallback: "none"` 以在没有匹配插件测试框架时直接失败。一旦选中了 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：** 这是预期行为，除非你强制设置了
-`embeddedHarness.runtime: "codex"`（或选择了旧版 `codex/*` 引用）。普通的
-`openai/gpt-*` 和其他提供商引用会继续走其常规提供商路径。
+**非 Codex 模型使用了 Pi：** 这是预期行为，除非你强制设置了 `embeddedHarness.runtime: "codex"`（或选择了旧版 `codex/*` 引用）。普通的 `openai/gpt-*` 和其他提供商引用会保持其正常的提供商路径。

 ## 相关内容

- [智能体测试框架插件](/zh-CN/plugins/sdk-agent-harness)
+- [智能体测试工具插件](/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)
+- [测试](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke)