openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 15:35:55 +00:00
parent 18d7128f10
commit 01be6636d0
2 changed files with 220 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

312
docs/zh-CN/help/testing-live.md
View File

@ -7,16 +7,16 @@ sidebarTitle: Live tests
summary: 实时（涉及网络）的测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
title: 测试：实时测试套件
x-i18n:
generated_at: "2026-04-24T05:03:00Z"
generated_at: "2026-04-24T15:34:06Z"
model: gpt-5.4
provider: openai
source_hash: 03689542176843de6e0163011250d1c1225ee5af492f88acf945b242addd1cc9
source_hash: 3e9a76038dbfe50271225bd3b5405e5dea9a1a19d7591da2114709009f5de66e
source_path: help/testing-live.md
workflow: 15
---
如需了解快速开始、QA 运行器、单元/集成测试套件以及 Docker 流程，请参阅
[测试](/zh-CN/help/testing)。本页介绍 **实时**（涉及网络）的测试
如需了解快速开始、QA 运行器、单元 / 集成测试套件以及 Docker 流程，请参阅
[测试](/zh-CN/help/testing)。本页介绍**实时**（涉及网络）的测试
套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及
凭证处理。
@ -24,88 +24,88 @@ x-i18n:
- 测试：`src/gateway/android-node.capabilities.live.test.ts`
- 脚本：`pnpm android:test:integration`
- 目标：调用已连接 Android 节点当前**公布的每一条命令**，并断言命令契约行为。
- 目标：调用已连接 Android 节点当前**已声明的每一条命令**，并断言命令契约行为。
- 范围：
- 预先配置 / 手动设置（该测试套件不会安装 / 运行 / 配对应用）。
- 针对所选 Android 节点逐条命令进行 Gateway 网关 `node.invoke` 校验。
- 必需的预先设置：
- 已满足前置条件 / 手动设置（该测试套件不会安装 / 运行 / 配对应用）。
- 针对所选 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 应用](/zh-CN/platforms/android)
- 完整 Android 设置详情：[Android App](/zh-CN/platforms/android)
## 实时：模型冒烟测试（配置档案密钥）
## 实时：模型冒烟测试（配置档密钥）
实时测试分为两层，以便我们隔离故障：
- “直接模型”用于判断提供商 / 模型在给定密钥下是否至少能够响应。
- “Gateway 冒烟测试”用于判断该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史、工具、沙箱策略等）。
- “直接模型”用于确认提供商 / 模型在给定密钥下是否至少能够响应。
- “Gateway 冒烟测试”用于确认该模型的完整 Gateway 网关 + 智能体流水线能够正常工作（会话、历史、工具、沙箱策略等）。
### 第 1 层：直接模型补全（不经过 Gateway 网关）
- 测试：`src/agents/models.profiles.live.test.ts`
- 目标：
- 枚举已发现的模型
- 使用 `getApiKeyForModel` 选择你已配置凭证的模型
- 对每个模型运行一个小型补全测试（并在需要时运行针对性的回归测试）
- 枚举发现到的模型
- 使用 `getApiKeyForModel` 选择你已有凭证的模型
- 为每个模型运行一个小型补全测试（并在需要时运行定向回归测试）
- 启用方式：
- `pnpm test:live`（如果直接调用 Vitest，则使用 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）后才会实际运行此测试套件；否则会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 冒烟测试
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会实际运行此测试套件；否则会跳过，以便让 `pnpm test:live` 专注于 Gateway 网关冒烟测试
- 选择模型的方式：
- `OPENCLAW_LIVE_MODELS=modern` 运行 modern 允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_MODELS=all` 是 modern 允许列表的别名
- `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名
- 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."`（逗号分隔的允许列表）
- modern / all 扫描默认使用一个经过筛选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行完整 modern 扫描，或设置为正数以使用更小的上限。
- 完整扫描会对整个直接模型测试使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 超时时间。默认值：60 分钟。
- 直接模型探测默认使用 20 路并行；可设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 进行覆盖。
- modern / all 扫描默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行完整 modern 扫描，或设置为正数以使用更小的上限。
- 完整扫描对整个直接模型测试超时使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS`。默认值：60 分钟。
- 直接模型探测默认使用 20 路并行；可设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 覆盖。
- 选择提供商的方式：
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的允许列表）
- 密钥来源：
- 默认：配置档案存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用配置档案存储**
- 默认：配置档存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制仅使用**配置档存储**
- 存在原因：
- 将“提供商 API 损坏 / 密钥无效”与“Gateway 网关智能体流水线损坏”区分开
- 容纳小型、隔离的回归场景（例如：OpenAI Responses / Codex Responses 的推理重放 + 工具调用流程）
- 将“提供商 API 已损坏 / 密钥无效”与“Gateway 网关智能体流水线已损坏”分离
- 容纳小而独立的回归测试（示例：OpenAI Responses / Codex Responses 推理重放 + 工具调用流程）
### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（也就是 “@openclaw” 实际执行的内容）
- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
- 目标：
- 启动一个进程内 Gateway 网关
- 创建 / 修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
- 遍历有密钥的模型，并断言：
- 有“有意义”的响应（不使用工具）
- 真实的工具调用可正常工作（读取探针）
- 可选的额外工具探针（执行 + 读取探针）
- OpenAI 回归路径（仅工具调用 → 后续跟进）持续正常
- 探针细节（便于你快速解释故障）：
- 创建 / 修补一个 `agent:dev:*` 会话（每次运行按模型覆盖）
- 遍历带密钥的模型并断言：
- “有意义的”响应（无工具）
- 一个真实工具调用能够工作（读取探针）
- 可选的额外工具探针（exec+read 探针）
- OpenAI 回归路径（仅工具调用 → 后续跟进）持续可用
- 探针细节（这样你可以快速解释故障）：
- `read` 探针：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。
- `exec+read` 探针：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。
- 图像探针：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
- 图片探针：测试会附加一个生成的 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.2 + 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 全部都测”）：
- 默认：现代允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）以缩小范围
- modern / all Gateway 网关扫描默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行完整 modern 扫描，或设置为正数以使用更小的上限。
- 选择提供商的方式（避免“OpenRouter 全都测”）：
- `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`）
- 当模型声明支持图片输入时，会运行图片探针
- 流程（高层概述）：
- 测试生成一个带有 “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），请运行：
提示：若想查看你的机器上可以测试哪些内容（以及精确的 `provider/model` id），请运行：
```bash
openclaw models list
@ -115,23 +115,23 @@ openclaw models list --json
## 实时：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线，同时不触碰你的默认配置。
- 各后端的默认冒烟配置保存在所属扩展的 `cli-backend.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 后端插件元数据。
- 命令 / 参数 / 图片行为来自所属 CLI 后端插件元数据。
- 覆盖项（可选）：
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"`
- `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` 可强制启用）。
- `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` 可强制启用）。
示例：
@ -159,20 +159,20 @@ 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，并验证恢复后的会话仍然记得先前的备注。
- 它会以非 root 的 `node` 用户身份，在仓库 Docker 镜像内运行实时 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 智能体验证真实的 ACP 对话绑定流程：
- 发送 `/acp spawn <agent> --bind here`
- 原地绑定一个合成的消息渠道会话
- 在同一个会话上发送一次普通后续消息
- 验证该后续消息进入已绑定 ACP 会话的转录记录
- 就地绑定一个合成的消息渠道会话
- 在同一个会话中发送普通后续消息
- 验证该后续消息落入已绑定 ACP 会话的转录记录
- 启用：
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
@ -190,8 +190,8 @@ pnpm test:docker:live-cli-backend:gemini
- `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.2`
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2`
- 说明：
- 此测试通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成 originating-route 字段，以便测试能够附加消息渠道上下文，而无需伪装为外部投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用内嵌 `acpx` 插件中针对所选 ACP harness 智能体的内置智能体注册表。
- 该测试路径使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成 originating-route 字段，这样测试就能附加消息渠道上下文，而无需假装进行外部投递。
- 当 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 未设置时，测试会对所选 ACP harness 智能体使用嵌入式 `acpx` 插件的内置智能体注册表。
示例：
@ -218,35 +218,35 @@ pnpm test:docker:live-acp-bind:gemini
Docker 说明：
- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
- 默认情况下，它会按顺序对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后 `gemini`。
- 默认情况下，它会依次对所有受支持的实时 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 中获得的提供商环境变量继续提供给子 harness CLI。
- 在 Docker 内，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 acpx 就能让从配置文件中加载的提供商环境变量继续对其子 harness CLI 可用。
## 实时：Codex app-server harness 冒烟测试
- 目标：通过正常的 Gateway 网关
`agent` 方法验证由插件拥有的 Codex harness：
- 目标：通过常规 Gateway 网关
`agent` 方法验证由插件自有的 Codex harness：
- 加载内置的 `codex` 插件
- 选择 `OPENCLAW_AGENT_RUNTIME=codex`
- 在强制使用 Codex harness 的情况下，向 `openai/gpt-5.2` 发送第一轮 Gateway 网关智能体请求
- 向同一个 OpenClaw 会话发送第二轮请求，并验证 app-server
线程可以恢复
- 通过同一条 Gateway 网关命令
- 向同一个 OpenClaw 会话发送第二轮消息，并验证 app-server
线程能够恢复
- 通过同一 Gateway 网关命令
路径运行 `/codex status` 和 `/codex models`
- 可选运行两个经 Guardian 审核的提权 shell 探针：一个应被批准的良性
命令，以及一个应被拒绝的伪造密钥上传操作，
这样智能体会回头询问
- 可选运行两个经过 Guardian 审核的提权 shell 探针：一个应被批准的
无害命令，以及一个应被拒绝的伪造密钥上传，
以便智能体回过头来询问
- 测试：`src/gateway/gateway-codex-harness.live.test.ts`
- 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
- 默认模型：`openai/gpt-5.2`
- 可选图像探针：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选图片探针：`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
harness 不能通过静默回退到 PI 来蒙混过关。
- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，这样损坏的 Codex
harness 就不会因为静默回退到 PI 而误通过。
- 认证：Codex app-server 认证来自本地 Codex 订阅登录。Docker
冒烟测试在适用时也可以为非 Codex 探针提供 `OPENAI_API_KEY`，
冒烟测试在适用时也可提供 `OPENAI_API_KEY` 用于非 Codex 探针，
以及可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
本地配方：
@ -272,29 +272,29 @@ Docker 说明：
- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
- 它会加载挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
认证文件，将 `@openai/codex` 安装到可写的挂载 npm
认证文件，将 `@openai/codex` 安装到可写且已挂载的 npm
前缀中，暂存源代码树，然后只运行 Codex-harness 实时测试。
- Docker 默认启用图像、MCP / 工具和 Guardian 探针。设置
- 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 harness
测试配置一致，因此旧别名或 PI 回退无法掩盖 Codex harness
回归问题。
### 推荐的实时测试配方
范围更窄且明确的允许列表最快，也最不容易不稳定：
范围窄且显式的允许列表最快，也最不容易出问题：
- 单模型，直接模式（不经过 Gateway 网关）：
- 单模型，直接测试（不经过 Gateway 网关）：
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts`
- 单模型，Gateway 网关冒烟测试：
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- 跨多个提供商的工具调用：
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,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`
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- 聚焦 Google（Gemini API 密钥 + Antigravity）：
- Gemini（API 密钥）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
@ -303,111 +303,113 @@ Docker 说明：
说明：
- `google/...` 使用 Gemini API（API 密钥）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。
- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具行为差异）。
- Gemini API 与 Gemini CLI：
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / 配置档案认证）；这也是大多数用户所说的 “Gemini”。
- CLI：OpenClaw 会调用本地 `gemini` 二进制程序；它有自己的认证方式，行为也可能不同（流式传输 / 工具支持 / 版本偏差）。
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / 配置档认证）；这也是大多数用户所说的 “Gemini”。
- CLI：OpenClaw 会调用本地 `gemini` 二进制；它有自己的认证，并且行为可能不同（流式传输 / 工具支持 / 版本偏差）。
## 实时：模型矩阵（我们的覆盖范围）
没有固定的 “CI 模型列表”（实时测试是按需启用的），但以下是**推荐**在有密钥的开发机器上定期覆盖的模型。
没有固定的“CI 模型列表”（实时测试是选择启用的），但以下是建议你在有密钥的开发机器上定期覆盖的**推荐**模型。
### 现代冒烟测试集（工具调用 + 图像）
### 现代冒烟测试集（工具调用 + 图片）
这是我们期望持续可用的 “常见模型” 运行集：
这是我们期望持续保持可用的“常用模型”运行集：
- OpenAI（非 Codex）：`openai/gpt-5.2`
- OpenAI Codex OAuth：`openai-codex/gpt-5.2`
- 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`
- DeepSeek：`deepseek/deepseek-v4-flash` 和 `deepseek/deepseek-v4-pro`
- Z.AI（GLM）：`zai/glm-4.7`
- MiniMax：`minimax/MiniMax-M2.7`
使用工具 + 图像运行 Gateway 网关冒烟测试：
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,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`
运行带工具 + 图片的 Gateway 网关冒烟测试：
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,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,deepseek/deepseek-v4-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.2`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
- Google：`google/gemini-3-flash-preview`（或 `google/gemini-3.1-pro-preview`）
- DeepSeek：`deepseek/deepseek-v4-flash`
- Z.AI（GLM）：`zai/glm-4.7`
- MiniMax：`minimax/MiniMax-M2.7`
可选的额外覆盖（有更好，没有也可以）：
可选附加覆盖（有更好，没有也可以）：
- xAI：`xai/grok-4`（或最新可用版本）
- Mistral：`mistral/`…（选择一个你已启用的支持 “tools” 的模型）
- Mistral：`mistral/`…（选择一个你已启用、具备 “tools” 能力的模型）
- Cerebras：`cerebras/`…（如果你有访问权限）
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
### Vision：发送图像（附件 → 多模态消息）
### 视觉：图片发送（附件 → 多模态消息）
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 的支持视觉输入的变体等），以运行图像探针。
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图片的模型（Claude / Gemini / OpenAI 支持视觉的变体等），以覆盖图片探针。
### 聚合器 / 替代 Gateway 网关
如果你启用了相应密钥，我们也支持通过以下方式进行测试：
如果你启用了相关密钥，我们也支持通过以下方式测试：
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选项）
- 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(...)` 返回的内容，加上当前可用的密钥。
提示：不要试图在文档中硬编码“所有模型”。权威列表始终是你机器上的 `discoverModels(...)` 返回结果，加上当前可用的密钥。
## 凭证（切勿提交）
## 凭证（绝不要提交）
实时测试发现凭证的方式与 CLI 相同。实际含义如下：
实时测试发现凭证的方式与 CLI 完全相同。实际含义如下：
- 如果 CLI 能正常工作，实时测试应该也能找到相同的密钥。
- 如果实时测试提示 “无凭证”，就按你调试 `openclaw models list` / 模型选择时的相同方式进行调试。
- 如果 CLI 能用，实时测试通常也应找到同样的密钥。
- 如果实时测试提示“没有凭证”，就像调试 `openclaw models list` / 模型选择那样去调试。
- 每个智能体的认证配置档案：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试里 “profile keys” 的含义）
- 每个智能体的认证配置档：`~/.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` 路径覆盖项，这样探针就不会落到你真实主机的工作区中。
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试 home 中，但它不是主配置档密钥存储）
- 默认情况下，本地实时运行会把当前配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时测试 home 会跳过 `workspace/` 和 `sandboxes/`，并去除 `agents.*.workspace` / `agentDir` 路径覆盖，以便探针不会落到你真实主机的工作区中。
如果你想依赖环境变量中的密钥（例如在你的 `~/.profile` 中导出的变量），请在执行本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
如果你想依赖环境变量密钥（例如导出在你的 `~/.profile` 中），请在 `source ~/.profile` 之后运行本地测试，或使用下方的 Docker 运行器（它们可以把 `~/.profile` 挂载进容器）。
## 实时：Deepgram（音频转录）
## Deepgram 实时测试（音频转录）
- 测试：`extensions/deepgram/audio.live.test.ts`
- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
## 实时：BytePlus 编码计划
## 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 工作流媒体测试
## 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 工作流提交、轮询、下载或插件注册后尤其有用
- 覆盖内置 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`
- Harness：`pnpm test:live:media image`
- 范围：
- 枚举每个已注册的图像生成提供商插件
- 在探测之前，从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置档案，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / 配置档案 / 模型的提供商
- 通过共享运行时能力运行默认图像生成变体：
- 枚举每个已注册的图片生成提供商插件
- 在探测前，从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置档，因此 `auth-profiles.json` 中陈旧的测试密钥不会掩盖真实 shell 凭证
- 跳过没有可用认证 / 配置档 / 模型的提供商
- 通过共享运行时能力运行内置的图片生成变体：
- `google:flash-generate`
- `google:pro-generate`
- `google:pro-edit`
@ -420,14 +422,14 @@ Docker 说明：
- `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` 可强制使用配置档案存储认证，并忽略仅环境变量的覆盖
- `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`
@ -435,65 +437,65 @@ Docker 说明：
- 范围：
- 覆盖共享的内置音乐生成提供商路径
- 当前覆盖 Google 和 MiniMax
- 在探测之前，从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置档案，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / 配置档案 / 模型的提供商
- 在可用时运行声明的两种运行时模式：
- `generate`：仅提示词输入
- 在探测前，从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置档，因此 `auth-profiles.json` 中陈旧的测试密钥不会掩盖真实 shell 凭证
- 跳过没有可用认证 / 配置档 / 模型的提供商
- 在可用时运行两种已声明的运行时模式：
- 使用仅提示词输入的 `generate`
- 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
- 当前共享通道覆盖范围：
- 当前共享路径覆盖：
- `google`：`generate`、`edit`
- `minimax`：`generate`
- `comfy`：使用单独的 Comfy 实时文件，不在此共享扫描中
- 可选缩小范围：
- `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` 可强制使用配置档案存储认证，并忽略仅环境变量的覆盖
- `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`
- Harness：`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 凭证
- 跳过没有可用认证 / 配置档案 / 模型的提供商
- 默认使用对发布安全的冒烟测试路径：非 FAL 提供商、每个提供商一个文生视频请求、1 秒龙虾提示词，以及来自 `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`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地视频输入时，运行 `videoToVideo`
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，还会在可用时运行已声明的转换模式：
- 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于缓冲区的本地图片输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于缓冲区的本地视频输入时，运行 `videoToVideo`
- 当前在共享扫描中已声明但跳过的 `imageToVideo` 提供商：
- `vydra`，因为内置的 `veo3` 仅支持文本，而内置的 `kling` 需要远程图像 URL
- `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` 通道
- 该文件会运行 `veo3` 文生视频，以及一个默认使用远程图片 URL 固件的 `kling` 路径
- 当前 `videoToVideo` 实时覆盖：
- 仅 `runway`，并且仅在所选模型为 `runway/gen4_aleph` 时
- 仅 `runway`，且所选模型为 `runway/gen4_aleph` 时
- 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商：
- `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
- `google`，因为当前共享 Gemini / Veo 通道使用基于本地 buffer 的输入，而该路径在共享扫描中不被接受
- `openai`，因为当前共享通道缺少针对组织的视频修补 / remix 访问保证
- 可选缩小范围：
- `google`，因为当前共享 Gemini / Veo 路径使用基于本地缓冲区的输入，而该路径在共享扫描中不被接受
- `openai`，因为当前共享路径缺少特定组织的视频修补 / 混剪访问保证
- 可选范围缩小：
- `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_VIDEO_GENERATION_SKIP_PROVIDERS=""` 以将所有提供商纳入默认扫描，包括 FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 以降低每个提供商的操作上限，用于更激进的冒烟测试运行
- 可选认证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档案存储认证，并忽略仅环境变量的覆盖
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档存储认证，并忽略仅环境变量的覆盖
## 媒体实时 harness
## 媒体实时测试 Harness
- 命令：`pnpm test:live:media`
- 目的：
- 通过一个仓库原生入口运行共享的图像、音乐和视频实时测试套件
- 通过一个仓库原生入口运行共享的图片、音乐和视频实时测试套件
- 自动从 `~/.profile` 加载缺失的提供商环境变量
- 默认自动将每个测试套件缩小到当前具有可用认证的提供商
- 复用 `scripts/test-live.mjs`，因此心跳和安静模式行为保持一致
- 默认自动将每个套件缩小到当前具有可用认证的提供商
- 复用 `scripts/test-live.mjs`，因此心跳和静默模式行为保持一致
- 示例：
- `pnpm test:live:media`
- `pnpm test:live:media image video --providers openai,google,minimax`

86
docs/zh-CN/providers/deepseek.md
View File

@ -1,45 +1,53 @@
---
read_when:
- 你想在 OpenClaw 中使用 DeepSeek
- 你需要 API 密钥环境变量或 CLI 认证选项
summary: DeepSeek 设置（认证 + 模型选择）
- 你需要 API key 环境变量或 CLI 凭证选择
summary: DeepSeek 设置（凭证 + 模型选择）
title: DeepSeek
x-i18n:
generated_at: "2026-04-24T15:13:10Z"
generated_at: "2026-04-24T15:34:04Z"
model: gpt-5.4
provider: openai
source_hash: 5b0d2345c72328e14351d71c5784204dc6ed9dc922f919b6adfac394001c3261
source_hash: b6e9d4e24204cbc097c13ccd837d7a6f8dd36538f1b22aae644762b88b948d0f
source_path: providers/deepseek.md
workflow: 15
---
[DeepSeek](https://www.deepseek.com) 通过与 OpenAI 兼容的 API 提供强大的 AI 模型。
[DeepSeek](https://www.deepseek.com) 提供功能强大的 AI 模型，并带有与 OpenAI 兼容的 API。
| 属性 | 值 |
| 属性 | 值 |
| -------- | -------------------------- |
| 提供商 | `deepseek` |
| 认证 | `DEEPSEEK_API_KEY` |
| API | 与 OpenAI 兼容 |
| 提供商 | `deepseek` |
| 凭证 | `DEEPSEEK_API_KEY` |
| API | 与 OpenAI 兼容 |
| Base URL | `https://api.deepseek.com` |
## 入门指南
<Steps>
<Step title="获取你的 API 密钥">
在 [platform.deepseek.com](https://platform.deepseek.com/api_keys) 创建一个 API 密钥。
<Step title="获取你的 API key">
在 [platform.deepseek.com](https://platform.deepseek.com/api_keys) 创建一个 API key。
</Step>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice deepseek-api-key
```
这会提示你输入 API 密钥，并将 `deepseek/deepseek-v4-flash` 设置为默认模型。
这会提示你输入 API key，并将 `deepseek/deepseek-v4-flash` 设置为默认模型。
</Step>
<Step title="验证模型可用">
```bash
openclaw models list --provider deepseek
```
若要查看内置的静态目录而无需运行中的 Gateway 网关，
请使用：
```bash
openclaw models list --all --provider deepseek
```
</Step>
</Steps>
@ -60,26 +68,58 @@ x-i18n:
</AccordionGroup>
<Warning>
如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `DEEPSEEK_API_KEY`
对该进程可用（例如，在 `~/.openclaw/.env` 中或通过
`env.shellEnv`）。
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `DEEPSEEK_API_KEY`
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。
</Warning>
## 内置目录
| 模型引用 | 名称 | 输入 | 上下文 | 最大输出 | 说明 |
| ---------------------------- | ----------------- | ----- | ------------- | ---------- | ------------------------------------------ |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | 默认模型；支持 V4 thinking 的能力表面 |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | 支持 V4 thinking 的能力表面 |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2 非 thinking 能力表面 |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | 启用推理的 V3.2 能力表面 |
| 模型引用 | 名称 | 输入 | 上下文 | 最大输出 | 说明 |
| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | 默认模型；支持 V4 thinking 的接口 |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | 支持 V4 thinking 的接口 |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2 非 thinking 接口 |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | 启用推理的 V3.2 接口 |
<Tip>
V4 模型支持 DeepSeek 的 `thinking` 控制。OpenClaw 还会在后续轮次中重放
DeepSeek 的 `reasoning_content`，因此带有工具调用的 thinking 会话
DeepSeek `reasoning_content`，因此带有工具调用的 thinking 会话
可以继续进行。
</Tip>
## Thinking 和工具
DeepSeek V4 thinking 会话的重放约定比大多数
与 OpenAI 兼容的提供商更严格：当启用 thinking 的助手消息包含
工具调用时，DeepSeek 期望在后续请求中把先前助手的 `reasoning_content`
一并发回。OpenClaw 在 DeepSeek 插件内部处理了这一点，
因此普通的多轮工具使用可以在 `deepseek/deepseek-v4-flash` 和
`deepseek/deepseek-v4-pro` 上正常工作。
当在 OpenClaw 中禁用 thinking 时（包括 UI 中的 **None** 选择），
OpenClaw 会发送 DeepSeek `thinking: { type: "disabled" }`，并从发出的
历史记录中去除重放的 `reasoning_content`。这样可以让已禁用 thinking 的
会话走 DeepSeek 的非 thinking 路径。
默认快速路径请使用 `deepseek/deepseek-v4-flash`。如果你想使用能力更强的
V4 模型，并且可以接受更高的成本或延迟，请使用
`deepseek/deepseek-v4-pro`。
## 实时测试
直接实时模型套件在现代模型集中包含 DeepSeek V4。若只运行
DeepSeek V4 的直接模型检查：
```bash
OPENCLAW_LIVE_PROVIDERS=deepseek \
OPENCLAW_LIVE_MODELS="deepseek/deepseek-v4-flash,deepseek/deepseek-v4-pro" \
pnpm test:live src/agents/models.profiles.live.test.ts
```
该实时检查会验证两个 V4 模型都能完成请求，并且 thinking/工具的
后续轮次会保留 DeepSeek 所要求的重放负载。
## 配置示例
```json5
@ -100,6 +140,6 @@ DeepSeek 的 `reasoning_content`，因此带有工具调用的 thinking 会话
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="配置参考" href="/zh-CN/gateway/configuration-reference" icon="gear">
agents、模型和提供商的完整配置参考。
智能体、模型和提供商的完整配置参考。
</Card>
</CardGroup>