@researai/deepscientist 1.5.16 → 1.6.0

package/docs/zh/15_CODEX_PROVIDER_SETUP.md

@@ -1,85 +1,357 @@
 # 15 Codex Provider 配置
 
-DeepScientist 不会为 MiniMax、GLM、火山方舟、阿里百炼单独实现一套 provider 适配器。
+DeepScientist 不会为 MiniMax、GLM、火山方舟、阿里百炼等 provider 额外维护一套独立适配层。
 
-它复用的是你本机已经能正常工作的 Codex CLI 配置。
+它复用的是你本机已经能正常工作的 Codex CLI。
 
-推荐顺序始终是：
+正确的理解方式是：
 
-1. 先让 Codex 自己能工作
-2. 确认 `codex` 或 `codex --profile <name>` 在终端里可用
-3. 运行 `ds doctor`
-4. 再运行 `ds` 或 `ds --codex-profile <name>`
+1. 先让 `codex` 自己能工作
+2. 再确认同一套配置在终端里可用
+3. 然后运行 `ds doctor`
+4. 最后再运行 `ds` 或 `ds --codex-profile <name>`
 
-## 三种推荐使用方式
+如果 Codex 本身还没工作，先修 DeepScientist 是错误顺序。
 
-### 1. 默认 OpenAI 登录路径
+如果你要配置其他内建 runner，请同时参考：
+
+- [24 Claude Code 配置指南](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+- [27 Kimi Code 配置指南](./27_KIMI_CODE_PROVIDER_SETUP.md)
+- [25 OpenCode 配置指南](./25_OPENCODE_PROVIDER_SETUP.md)
+
+## 官方文档先读哪些
+
+Codex provider 配置请以 OpenAI Codex 文档和目标 provider 文档为准：
+
+- Codex CLI reference：`https://developers.openai.com/codex/cli/reference`
+- Codex config reference：`https://developers.openai.com/codex/config-reference`
+- Ollama OpenAI compatibility：`https://docs.ollama.com/openai`
+- Ollama + Codex：`https://docs.ollama.com/integrations/codex`
+- Gemini OpenAI compatibility：`https://ai.google.dev/gemini-api/docs/openai`
+
+对 DeepScientist 来说，最重要的映射关系是：
+
+- Codex 的 provider、profile、模型名仍然写在 `~/.codex/config.toml`
+- DeepScientist 的 Codex runner 主要透传 `--profile`、`--model`、`approval_policy`、`sandbox_mode`、reasoning effort 和 env
+- DeepScientist 当前不会替 Codex 额外追加 `--oss` 或 `--local-provider`，所以要在 DeepScientist 中稳定复用 Ollama 时，优先使用 Codex profile，而不是只依赖一次性的 CLI 参数
+- 如果某个 provider 只提供 OpenAI Chat Completions，而没有 Responses API，最新版 Codex 路径可能不适合；这种场景优先考虑 [25 OpenCode 配置指南](./25_OPENCODE_PROVIDER_SETUP.md)
+
+## 哪些文件最重要
+
+Codex CLI 默认读取 `~/.codex/` 下面的本地状态。
 
-如果你的 Codex CLI 走的是标准 OpenAI 登录流，就用这一条。
+最重要的文件是：
+
+- `~/.codex/config.toml`
+  - provider、model、profile、feature 等主要配置
+- `~/.codex/auth.json`
+  - 当你走标准 OpenAI 登录流时，`codex login` 通常会写这个文件
+- `~/.codex/history.jsonl`
+  - 本地会话历史，不是配置必需项
+
+常用检查命令：
 
 ```bash
-codex --login
-ds doctor
-ds
+ls -la ~/.codex
+sed -n '1,220p' ~/.codex/config.toml
+codex --version
+codex --help
+codex exec --help
 ```
 
-### 2. 临时使用 provider profile
+## 推荐配置顺序
 
-如果你已经有一个可用的 Codex profile，例如 `m27`、`glm`、`ark`、`bailian`，最简单的方式就是直接在启动 `ds` 时透传它。
+建议严格按这个顺序走：
+
+1. 安装 Codex CLI，并确认正在使用的二进制就是你想要的那个
+2. 准备 `~/.codex/config.toml`
+3. 直接验证 `codex` 或 `codex --profile <name>`
+4. 用 `ds doctor` 验证 DeepScientist
+5. 最后再让 DeepScientist 复用这套 Codex 配置
+
+`codex login` 不等于 DeepScientist 的启动探测。login 只说明认证流程完成；`ds doctor` 会真的发送一次非交互式 Codex 请求，并要求返回 `HELLO`。如果 login 成功但 `ds doctor` 失败，请在同一个 shell 里先跑：
 
 ```bash
-codex --profile m27
-ds doctor --codex-profile m27
-ds --codex-profile m27
+printf 'Reply with exactly HELLO.' | codex --search exec --json --cd /tmp --skip-git-repo-check -
 ```
 
-如果你这一轮要强制指定某一个 Codex 可执行文件，也可以这样：
+如果使用 profile，再加上 profile：
 
 ```bash
-ds doctor --codex /absolute/path/to/codex --codex-profile m27
-ds --codex /absolute/path/to/codex --codex-profile m27
+printf 'Reply with exactly HELLO.' | codex --search --profile provider_alias exec --json --cd /tmp --skip-git-repo-check -
 ```
 
-这是最简单的路径。只是临时试用某个 provider 时，不需要先改 `runners.yaml`。
+如果这个直接命令失败，先修 Codex、provider key、模型或代理。如果它成功但 `ds doctor` 失败，再对比 `which codex`、`CODEX_HOME`、代理环境变量和 `~/DeepScientist/config/runners.yaml`。
 
-### 3. 持久化 provider profile
+## 第一步：先确认 Codex binary
 
-如果你希望 DeepScientist 之后默认就走这个 profile，可以写进 `runners.yaml`：
+先检查当前实际在用哪个 Codex：
+
+```bash
+which codex
+codex --version
+```
+
+如果你必须使用特定版本或特定路径的 Codex，可执行文件路径记下来，后续通过 `--codex` 传给 DeepScientist。
+
+例如：
+
+```bash
+ds doctor --codex /absolute/path/to/codex --codex-profile glm
+ds --codex /absolute/path/to/codex --codex-profile glm
+```
+
+## 第二步：理解 Codex 两种常见配置形态
+
+### A. OpenAI 登录形态
+
+如果你的 Codex 走标准 OpenAI 登录流，通常用这一种。
+
+典型流程：
+
+```bash
+codex login
+codex
+```
+
+这种情况下，`~/.codex/auth.json` 往往已经存在，`config.toml` 可以很精简。
+
+最小示例：
+
+```toml
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+
+[projects."/absolute/path/to/your/project"]
+trust_level = "trusted"
+```
+
+### B. `config.toml` 显式 provider 形态
+
+如果你要把 Codex 指向一个自定义 provider、代理或兼容网关，通常走这一种。
+
+常见写法之一：
+
+```toml
+model_provider = "myprovider"
+model = "gpt-5.4"
+model_reasoning_effort = "xhigh"
+
+[model_providers.myprovider]
+name = "My Provider"
+base_url = "https://example.com/codex"
+wire_api = "responses"
+experimental_bearer_token = "YOUR_TOKEN_HERE"
+requires_openai_auth = true
+```
+
+另一种常见写法是不用固定 bearer token，而是通过环境变量取 key：
+
+```toml
+[model_providers.myprovider]
+name = "My Provider"
+base_url = "https://example.com/codex"
+wire_api = "chat"
+env_key = "MYPROVIDER_API_KEY"
+requires_openai_auth = false
+```
+
+然后在启动 Codex 或 DeepScientist 的 shell 里导出环境变量：
+
+```bash
+export MYPROVIDER_API_KEY="..."
+```
+
+## 第三步：理解 `config.toml` 里最关键的字段
+
+### 顶层字段
+
+常见需要改的顶层字段包括：
+
+- `model_provider`
+  - 默认使用哪个 provider block
+- `model`
+  - 默认发送哪个模型名
+- `model_reasoning_effort`
+  - 例如 `medium`、`high`、`xhigh`
+- `service_tier`
+  - 可选，某些 provider 会用到
+
+### provider block 字段
+
+位于 `[model_providers.<name>]` 下：
+
+- `name`
+  - 人类可读名称
+- `base_url`
+  - Codex 实际请求的 provider endpoint
+- `wire_api`
+  - 通常是 `responses` 或 `chat`，按 provider 文档来
+- `env_key`
+  - 如果 API key 从环境变量读取，就写环境变量名
+- `experimental_bearer_token`
+  - 如果 provider 直接使用固定 bearer token，可写这里
+- `requires_openai_auth`
+  - provider 是否仍需要 OpenAI 认证形态
+- `request_max_retries`
+  - 可选，请求重试次数
+- `stream_max_retries`
+  - 可选，流式重试次数
+- `stream_idle_timeout_ms`
+  - 可选，流空闲超时
+
+### profile 字段
+
+profile 在 `[profiles.<alias>]` 下定义。
+
+示例：
+
+```toml
+[profiles.glm]
+model = "GLM-4.7"
+model_provider = "glm"
+```
+
+然后可以这样调用：
+
+```bash
+codex --profile glm
+```
+
+### 项目信任
+
+Codex 还会检查项目 trust。
+
+例如：
+
+```toml
+[projects."/ssdwork/deepscientist/DeepScientist"]
+trust_level = "trusted"
+```
+
+如果项目不在 trusted 状态，Codex 运行时可能还会再次确认。
+
+## 第四步：一套最稳妥的 profile 工作流
+
+### 4.1 编辑 `~/.codex/config.toml`
+
+建议先备份原文件：
+
+```bash
+cp ~/.codex/config.toml ~/.codex/config.toml.bak
+${EDITOR:-vim} ~/.codex/config.toml
+```
+
+### 4.2 新增 provider block
+
+通用模板：
+
+```toml
+[model_providers.provider_name]
+name = "Provider Name"
+base_url = "https://provider.example/v1"
+wire_api = "chat"
+env_key = "PROVIDER_API_KEY"
+requires_openai_auth = false
+request_max_retries = 4
+stream_max_retries = 10
+stream_idle_timeout_ms = 300000
+```
+
+### 4.3 新增 profile
+
+```toml
+[profiles.provider_alias]
+model = "provider-model-id"
+model_provider = "provider_name"
+```
+
+### 4.4 先直接验证 Codex
+
+交互式验证：
+
+```bash
+codex --profile provider_alias
+```
+
+非交互式 smoke check：
+
+```bash
+codex exec --profile provider_alias "Reply with exactly OK."
+```
+
+如果这里都还不通，不要先怪 DeepScientist，先把 Codex 自己修通。为了尽量贴近 DeepScientist 的实际探测，优先再跑：
+
+```bash
+printf 'Reply with exactly HELLO.' | codex --search --profile provider_alias exec --json --cd /tmp --skip-git-repo-check -
+```
+
+## 第五步：把同一套配置映射给 DeepScientist
+
+DeepScientist 推荐三种使用方式。
+
+### 1. 默认 OpenAI 登录路径
+
+```bash
+codex login
+ds doctor
+ds
+```
+
+### 2. 临时使用某个 provider profile
+
+```bash
+codex --profile glm
+codex exec --profile glm "Reply with exactly OK."
+ds doctor --codex-profile glm
+ds --codex-profile glm
+```
+
+### 3. 持久化写入 `runners.yaml`
+
+如果你希望 DeepScientist 默认总是走同一个 Codex profile，可以写进 `runners.yaml`：
 
 ```yaml
 codex:
   enabled: true
   binary: codex
   config_dir: ~/.codex
-  profile: minimax
+  profile: glm
   model: inherit
-  model_reasoning_effort: xhigh
+  model_reasoning_effort: high
   approval_policy: on-request
   sandbox_mode: workspace-write
 ```
 
 注意：
 
-- 对 provider-backed 的 Codex profile，建议优先使用 `model: inherit`
-- 除非你非常确定该 provider 接受你要显式传入的模型名，否则不要再额外硬写一个模型
-- DeepScientist 现在会在 `.ds/codex-home` 下启动一个隔离的运行时 home，但会先继承你配置的 `~/.codex` 里的 auth、config、skills、agents 与 prompts
+- `profile` 一般应该写你本地 Codex profile 的别名，例如 `glm`、`ark`、`bailian`、`m25`、`m27-local`
+- 对 provider-backed 的 Codex profile，优先使用 `model: inherit`
+- 只有当你非常确定 provider 接受那个显式模型名时，才在 DeepScientist 里硬写 `model:`
+- DeepScientist 实际运行 Codex 时会在 `.ds/codex-home` 下构造一个隔离运行时 home，但会先复制你 `~/.codex` 里的 auth、config、skills、agents 和 prompts
+- 如果 `ds doctor` 报 startup probe 失败，先看报告里的 `probe command`、`exit code`、`stderr excerpt` 和 `stdout excerpt`；这些字段反映的是真实 Codex 请求失败，而不只是 login 状态
+
+## 不改 `config.toml` 的临时覆盖方式
+
+Codex 自己支持 `-c key=value`。
+
+例如：
 
-## Provider 一览
+```bash
+codex -c model="gpt-5.4"
+codex -c model_provider="yunyi" -c model="gpt-5.4"
+codex exec -c model_reasoning_effort="high" "Reply with exactly OK."
+```
 
-| Provider | 官方文档 | 是否需要 Codex 登录 | DeepScientist 应该怎么用 |
-|---|---|---|---|
-| OpenAI | 正常 Codex 配置即可 | 是 | 不需要 profile，直接 `ds` |
-| MiniMax | [MiniMax Codex CLI](https://platform.minimaxi.com/docs/coding-plan/codex-cli) | 否 | 使用你自己的 Codex profile，例如 `ds --codex-profile m27` |
-| GLM | [GLM Coding Plan：其他工具](https://docs.bigmodel.cn/cn/coding-plan/tool/others) | 否 | 使用一个指向 GLM coding endpoint 的 Codex profile |
-| 火山方舟 | [Ark Coding Plan 总览](https://www.volcengine.com/docs/82379/1925114?lang=zh) | 否 | 使用一个指向 Ark coding endpoint 的 Codex profile |
-| 阿里百炼 | [百炼 Coding Plan：其他工具](https://help.aliyun.com/zh/model-studio/other-tools-coding-plan) | 否 | 使用一个指向 Bailian coding endpoint 的 Codex profile |
+这很适合临时验证；但如果你希望 DeepScientist 稳定复用，还是推荐把 profile 写进 `~/.codex/config.toml`。
 
 ## OpenAI
 
 ### 需要准备什么
 
-- 正常安装的 Codex CLI
-- 已成功执行过一次 `codex --login`，或者在 `codex` 交互界面里完成首次认证
+- 正常可用的 Codex CLI
+- 已成功执行 `codex login`
+- 能直接运行 `codex` 或 `codex exec "Reply with exactly OK."`
 
 ### DeepScientist 命令
 
@@ -99,119 +371,206 @@ codex:
   model: gpt-5.4
 ```
 
-## MiniMax
+## Ollama
 
-MiniMax 是最典型的 profile 模式。它的官方 Codex CLI 文档直接给了自定义 provider 的配置方式，并明确写了 `requires_openai_auth = false`。
+Ollama 官方同时提供 OpenAI-compatible API 和 Codex 集成说明。对 DeepScientist 来说，推荐把它整理成一个 Codex profile，然后通过 `ds doctor --codex-profile <name>` 使用。
 
-官方文档：
+### 什么时候适合走 Codex + Ollama
 
-- <https://platform.minimaxi.com/docs/coding-plan/codex-cli>
+适合：
 
-### 已验证的兼容性说明
+- 你已经能在本机稳定运行 Ollama
+- 目标模型能处理较长上下文、工具调用和代码修改
+- `http://localhost:11434/v1/responses` 能正常工作，或者你使用的是 Ollama 官方 Codex 集成生成的可用配置
 
-按 2026-04-04 对 MiniMax 官方 Codex CLI 页面和本地兼容性测试的核对结果：
+不适合：
 
-- MiniMax 官方 Codex CLI 页面当前建议使用 `@openai/codex@0.57.0`
-- MiniMax 当前应使用的 Coding Plan endpoint 是 `https://api.minimaxi.com/v1`
-- MiniMax 官方页面示例 profile 名是 `m21`，但 profile 名本身只是本地别名；本仓库统一用 `m27` 作为示例名
-- MiniMax 官方页面当前给出的 `codex-MiniMax-*` 模型名，在本地使用你提供的 key 实测并不能稳定通过 Codex CLI
-- 本地实测 DeepScientist 可稳定跑通的组合包括 `MiniMax-M2.7` + `m27` + Codex CLI `0.57.0`，以及 `MiniMax-M2.5` + `m25` + Codex CLI `0.57.0`
-- 当前最新版 `@openai/codex` 和 MiniMax 官方文档并不能稳定直接对齐
+- 你的 Ollama 版本只有 `/v1/chat/completions` 可用
+- 模型上下文很短，无法承载 DeepScientist 的长任务 prompt
+- 你只是想接 Gemini 这类远程 OpenAI-compatible provider；那通常优先走 OpenCode
 
-如果你现在要走最稳的 DeepScientist + MiniMax 路径，建议直接使用 Codex CLI `0.57.0`。
+### 1. 先安装和启动 Ollama
 
-### 需要准备什么
+```bash
+ollama --version
+ollama serve
+```
 
-- 已安装 Codex CLI `0.57.0`
-- 已创建 MiniMax `Coding Plan Key`
-- 在启动 Codex 和 DeepScientist 的 shell 中可见的 `MINIMAX_API_KEY`
-- 如果你要单独在终端里验证 `codex --profile <name>`，当前 shell 需要先清理 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`
-- `~/.codex/config.toml` 中已经配置好的 Codex profile
+另开一个终端，拉取并测试模型：
 
-### 安装 Codex CLI `0.57.0`
+```bash
+ollama pull gpt-oss:20b
+ollama run gpt-oss:20b "Reply with exactly HELLO."
+```
+
+如果你使用的是其他模型，把下面所有 `gpt-oss:20b` 替换成你实际准备使用的模型。
 
-最直接的方式是把全局 Codex 安装固定到 `0.57.0`：
+### 2. 先直接验证 Ollama 的 OpenAI-compatible API
 
 ```bash
-npm install -g @openai/codex@0.57.0
-codex --version
+curl http://localhost:11434/v1/models
 ```
 
-预期输出：
+再测 Responses API：
 
-```text
-codex-cli 0.57.0
+```bash
+curl http://localhost:11434/v1/responses \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-oss:20b",
+    "input": "Reply with exactly HELLO."
+  }'
 ```
 
-如果你还想保留另一个 Codex 版本，也可以单独写一个 wrapper 脚本，再把 `runners.codex.binary` 指向那个绝对路径。
+如果 `/v1/responses` 失败，先升级 Ollama 或换模型，不要直接进入 DeepScientist。
 
-现在如果 DeepScientist 在启动时检测到 MiniMax profile，但当前 `codex` 版本不是 `0.57.0`，在交互式终端里会主动提示是否自动安装 `@openai/codex@0.57.0`。
+### 3. 用 Ollama 官方 Codex 集成生成配置
 
-### Codex 侧配置
+Ollama 官方提供了面向 Codex 的启动命令。推荐先运行：
 
-请使用 `https://api.minimaxi.com/v1`，不要用 `https://api.minimax.io/v1`。
+```bash
+ollama launch codex --config
+```
 
-MiniMax 官方文档要求在配置前先清理 OpenAI 环境变量：
+它会引导你把 Ollama 配进 Codex。完成后，检查：
 
 ```bash
-unset OPENAI_API_KEY
-unset OPENAI_BASE_URL
-export MINIMAX_API_KEY="..."
+sed -n '1,220p' ~/.codex/config.toml
+codex --help
 ```
 
-如果你是在终端里单独验证 `codex --profile <name>`，就按上面的方式处理。
-如果你走的是 DeepScientist 路径，那么当所选 provider 明确写了 `requires_openai_auth = false` 时，DeepScientist 现在会在 startup probe 和真实 runner 执行时自动剥离 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`。
+如果你要让 DeepScientist 稳定复用这条路径，请确认 `~/.codex/config.toml` 里有一个命名 profile。形态可以类似这样：
 
-MiniMax 官方页面示例 profile 名是 `m21`。由于 profile 名只是本地别名，本仓库统一改写成 `m27`。
+```toml
+[model_providers.ollama-launch]
+name = "Ollama"
+base_url = "http://localhost:11434/v1"
+wire_api = "responses"
+requires_openai_auth = false
 
-先说明差异：
+[profiles.ollama-launch]
+model = "gpt-oss:20b"
+model_provider = "ollama-launch"
+```
 
-- 官方页面当前展示的是 `codex-MiniMax-M2.5`
-- 但本地实测里，直接请求 MiniMax API 能稳定跑通的是 `MiniMax-M2.7` 和 `MiniMax-M2.5`
-- 可复现的 DeepScientist 路径是：`MiniMax-M2.7` 配 `m27`，以及 `MiniMax-M2.5` 配 `m25`
-- 对 `m25` 这条路径，请使用 `MiniMax-M2.5`，不要写成 `codex-MiniMax-M2.5`
+注意：不要把自定义 provider 命名成 `ollama`，这个名字可能和 Codex 内置 provider 冲突。用 `ollama-launch`、`local_ollama` 这类别名更稳。
 
-因此，下面给的是当前 DeepScientist 推荐配置：
+### 4. 先直接验证 Codex
+
+```bash
+codex --profile ollama-launch
+codex exec --profile ollama-launch "Reply with exactly OK."
+```
+
+如果这里不通，先修 Ollama 或 Codex profile。
+
+### 5. 再映射到 DeepScientist
+
+一次性启动：
+
+```bash
+ds doctor --codex-profile ollama-launch
+ds --codex-profile ollama-launch
+```
+
+持久化到 `~/DeepScientist/config/runners.yaml`：
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: ollama-launch
+  model: inherit
+  model_reasoning_effort: high
+  approval_policy: never
+  sandbox_mode: workspace-write
+```
+
+如果 Ollama 端要求固定 token，可以在 Codex provider 里设置对应 `env_key`，然后把同名变量放到 `runners.codex.env`。默认本机 Ollama 通常不需要真实 API key。
+
+## Gemini
+
+Gemini 官方提供的是 OpenAI-compatible Chat Completions 路径，典型 base URL 是：
+
+```text
+https://generativelanguage.googleapis.com/v1beta/openai/
+```
+
+环境变量通常是：
+
+```bash
+export GEMINI_API_KEY="..."
+```
+
+但对 Codex + DeepScientist 来说，Gemini **不是首推路径**：
+
+- Gemini 官方 OpenAI compatibility 文档主打 Chat Completions
+- 最新 Codex provider 路线更偏向 Responses API
+- DeepScientist 的 Codex runner 依赖 Codex profile 稳定工作，不会替你在运行时改协议
+
+所以如果你想用 Gemini，优先看 [25 OpenCode 配置指南](./25_OPENCODE_PROVIDER_SETUP.md) 里的 Gemini 小节。
+
+如果你非常明确要试 Codex + Gemini，可以按“chat-only provider”的思路实验，但这不是推荐默认配置：
 
 ```toml
-[model_providers.minimax]
-name = "MiniMax Chat Completions API"
-base_url = "https://api.minimaxi.com/v1"
-env_key = "MINIMAX_API_KEY"
+[model_providers.gemini_chat]
+name = "Gemini OpenAI-compatible Chat"
+base_url = "https://generativelanguage.googleapis.com/v1beta/openai/"
 wire_api = "chat"
+env_key = "GEMINI_API_KEY"
 requires_openai_auth = false
-request_max_retries = 4
-stream_max_retries = 10
-stream_idle_timeout_ms = 300000
 
-[profiles.m27]
-model = "MiniMax-M2.7"
-model_provider = "minimax"
+[profiles.gemini]
+model = "gemini-3-flash-preview"
+model_provider = "gemini_chat"
 ```
 
-如果你想走同样的 DeepScientist 路径但使用 `m25`，保持上面的 provider 配置不变，再把 profile 写成：
+验证顺序仍然必须是：
 
-```toml
-[profiles.m25]
-model = "MiniMax-M2.5"
-model_provider = "minimax"
+```bash
+export GEMINI_API_KEY="..."
+codex exec --profile gemini "Reply with exactly OK."
+ds doctor --codex-profile gemini
 ```
 
-DeepScientist 现在对它的支持方式是：
+如果 `codex exec` 不通，就不要继续 `ds`。这时直接切到 OpenCode 通常更省时间。
 
-- 如果你使用的是这类 profile-only MiniMax 配置，再配合 Codex CLI `0.57.0`，DeepScientist 会在自己的 probe / 运行时临时 `config.toml` 副本里，把所选 profile 的 `model_provider` 和 `model` 自动提升到顶层
-- 对 provider-backed 的 MiniMax profile，DeepScientist 会强制使用 `model: inherit`，避免再被硬编码的 OpenAI 模型覆盖
-- 当 `requires_openai_auth = false` 时，DeepScientist 会自动移除冲突的 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`
-- 这意味着即使终端里原样执行 `codex --profile m27` 还会失败，DeepScientist 也可以先兼容跑起来
+## MiniMax
 
-如果你还希望终端里的 `codex --profile <name>` 也直接可用，请使用显式顶层兼容写法：
+官方文档：
 
-```toml
-model = "MiniMax-M2.7"
-model_provider = "minimax"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
+- <https://platform.minimaxi.com/docs/coding-plan/codex-cli>
+
+MiniMax 是最典型的 profile 模式。
+
+### 重要兼容性说明
+
+MiniMax 官方 Coding Plan 里的 `MiniMax-M2.7`，当前**并不能稳定作为 Codex 官方兼容路径使用**。
+
+如果你走 MiniMax 官方 Coding Plan + Codex 这条路径，建议直接改用：
+
+- `MiniMax-M2.5`
+- profile 别名例如 `m25`
+- 如果你想走当前最稳的 MiniMax Coding Plan 路径，建议使用 Codex CLI `0.57.0`
+
+如果你就是想用 `MiniMax-M2.7`，推荐做法是：
 
+- 不要把它当作官方 MiniMax Codex Coding Plan 默认路径
+- 而是把 M2.7 通过你本地的 OpenAI-compatible `vllm` 服务暴露出来
+- 然后在 `~/.codex/config.toml` 里把 Codex 指向这个本地 `vllm` endpoint
+
+### 推荐的官方 Coding Plan 路径
+
+官方 Coding Plan endpoint 继续使用：
+
+- Base URL：`https://api.minimaxi.com/v1`
+- API key 环境变量：`MINIMAX_API_KEY`
+- Model：`MiniMax-M2.5`
+
+推荐配置形态：
+
+```toml
 [model_providers.minimax]
 name = "MiniMax Chat Completions API"
 base_url = "https://api.minimaxi.com/v1"
@@ -222,79 +581,99 @@ request_max_retries = 4
 stream_max_retries = 10
 stream_idle_timeout_ms = 300000
 
-[profiles.m27]
-model = "MiniMax-M2.7"
+[profiles.m25]
+model = "MiniMax-M2.5"
 model_provider = "minimax"
 ```
 
-然后执行：
+验证顺序：
 
 ```bash
-codex --profile m27
+unset OPENAI_API_KEY
+unset OPENAI_BASE_URL
+export MINIMAX_API_KEY="..."
+codex --version
+codex --profile m25
+codex exec --profile m25 "Reply with exactly OK."
+ds doctor --codex-profile m25
+ds --codex-profile m25
 ```
 
-### DeepScientist 命令
+### 如果你坚持使用 MiniMax-M2.7
+
+推荐路径是：通过你本地的 OpenAI-compatible `vllm` 服务来暴露 M2.7。
+
+配置形态示例：
+
+```toml
+[model_providers.minimax_local_vllm]
+name = "MiniMax M2.7 via local vLLM"
+base_url = "http://127.0.0.1:8000/v1"
+wire_api = "chat"
+requires_openai_auth = false
+env_key = "OPENAI_API_KEY"
+
+[profiles.m27-local]
+model = "MiniMax-M2.7"
+model_provider = "minimax_local_vllm"
+```
+
+然后按同样顺序验证：
 
 ```bash
-ds doctor --codex-profile m27
-ds --codex-profile m27
+export OPENAI_API_KEY="dummy-or-local-token-if-needed"
+codex --profile m27-local
+codex exec --profile m27-local "Reply with exactly OK."
+ds doctor --codex-profile m27-local
+ds --codex-profile m27-local
 ```
 
 ### 持久化 runner 配置
 
+如果你走官方 Coding Plan 路径：
+
 ```yaml
 codex:
   enabled: true
-  binary: /tmp/codex057-wrapper
+  binary: codex
   config_dir: ~/.codex
-  profile: m27
+  profile: m25
   model: inherit
   model_reasoning_effort: high
 ```
 
-如果你已经把全局 `codex` 固定到 `0.57.0`，也可以把 `binary` 写回 `codex`。这里写绝对路径只是为了明确避免误用系统里其他版本的 Codex。
-
-如果你不想把这个路径持久化写进 `runners.yaml`，也可以保留 `binary: codex`，然后在启动时临时加：
+如果你走本地 vLLM 的 M2.7 路径：
 
-```bash
-ds --codex /absolute/path/to/codex --codex-profile m27
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: m27-local
+  model: inherit
+  model_reasoning_effort: high
 ```
 
-DeepScientist 现在会为 MiniMax 的 `0.57.0` 路径额外做两层兼容：
-
-- 当检测到旧版 Codex CLI 不支持 `xhigh` 时，自动把 `xhigh` 降级成 `high`
-- 当检测到 MiniMax 使用 profile-only 的 `model_provider` / `model` 配置形态时，在临时 DeepScientist Codex home 里自动补齐顶层字段
-- 当 provider 明确声明 `requires_openai_auth = false` 时，自动移除冲突的 `OPENAI_*` 认证环境变量
-
 ## GLM
 
-GLM 的官方文档把 Coding Plan 描述成 OpenAI-compatible 的 coding endpoint，而不是单独的 Codex 登录流程。
-
 官方文档：
 
 - <https://docs.bigmodel.cn/cn/coding-plan/tool/others>
 - <https://docs.bigmodel.cn/cn/coding-plan/faq>
 
-### 官方给出的 provider 关键值
+当前公开文档里的关键值：
 
 - Base URL：`https://open.bigmodel.cn/api/coding/paas/v4`
-- API Key：你的 GLM Coding Plan key
-- Model：文档中明确写了 `GLM-4.7`，部分场景也支持 `GLM-5`
+- Model：`GLM-4.7` 或其它当前 Coding Plan 支持模型
 
-### 推荐做法
-
-GLM 当前没有像 MiniMax 那样单独给出一篇 Codex CLI 专页。对 DeepScientist 来说，最稳的做法是：
-
-1. 在 `~/.codex/config.toml` 中创建一个指向上面 GLM coding endpoint 的 Codex profile
-2. 先确保 `codex --profile glm` 在终端里能工作
-3. 再让 DeepScientist 复用同一个 profile
-
-### DeepScientist 命令
+推荐流程：
 
-```bash
-ds doctor --codex-profile glm
-ds --codex-profile glm
-```
+1. 在 `~/.codex/config.toml` 里新增 GLM provider block
+2. 新增 `[profiles.glm]`
+3. 先跑 `codex --profile glm`
+4. 再跑 `codex exec --profile glm "Reply with exactly OK."`
+5. 再跑 `ds doctor --codex-profile glm`
+6. 最后跑 `ds --codex-profile glm`
 
 ### 持久化 runner 配置
 
@@ -309,29 +688,20 @@ codex:
 
 ## 火山方舟
 
-火山方舟的 Coding Plan 官方文档明确列出了 Codex CLI。
-
 官方文档：
 
 - <https://www.volcengine.com/docs/82379/1925114?lang=zh>
 
-### 官方给出的 provider 关键值
+当前公开文档里的关键值：
 
-- OpenAI-compatible Base URL：`https://ark.cn-beijing.volces.com/api/coding/v3`
-- 支持的 coding 模型：`doubao-seed-code-preview-latest`、`ark-code-latest`
-- 必须使用 Coding Plan 的 key 和对应的 Coding Plan endpoint
+- Base URL：`https://ark.cn-beijing.volces.com/api/coding/v3`
+- 模型：`doubao-seed-code-preview-latest`、`ark-code-latest`
 
-### 推荐做法
-
-先创建一个指向 Ark coding endpoint 的 Codex profile，并先验证：
+推荐流程：
 
 ```bash
 codex --profile ark
-```
-
-然后再启动 DeepScientist：
-
-```bash
+codex exec --profile ark "Reply with exactly OK."
 ds doctor --codex-profile ark
 ds --codex-profile ark
 ```
@@ -349,30 +719,26 @@ codex:
 
 ## 阿里百炼
 
-阿里百炼的 Coding Plan 官方文档也是 OpenAI-compatible endpoint 路径。它特别强调：必须使用 Coding Plan 专属 key 和 endpoint，而不是普通平台 endpoint。
-
 官方文档：
 
 - <https://help.aliyun.com/zh/model-studio/other-tools-coding-plan>
 - <https://help.aliyun.com/zh/model-studio/coding-plan-faq>
 
-### 官方给出的 provider 关键值
+这里最重要的一点：
 
-- OpenAI-compatible Base URL：`https://coding.dashscope.aliyuncs.com/v1`
-- API Key：Coding Plan 专属 key，通常形如 `sk-sp-...`
-- Model：请以当前百炼 Coding Plan 概览页支持的模型为准
+- 支持：百炼 **Coding Plan** endpoint 上的 Qwen
+- 不支持：普通百炼 / DashScope 平台的 Qwen API
 
-### 推荐做法
+当前公开文档里的关键值：
 
-先创建一个指向 Bailian Coding Plan endpoint 的 Codex profile，并先验证：
-
-```bash
-codex --profile bailian
-```
+- Base URL：`https://coding.dashscope.aliyuncs.com/v1`
+- key 形态：Coding Plan 专属 key，通常形如 `sk-sp-...`
 
-然后再启动 DeepScientist：
+推荐流程：
 
 ```bash
+codex --profile bailian
+codex exec --profile bailian "Reply with exactly OK."
 ds doctor --codex-profile bailian
 ds --codex-profile bailian
 ```
@@ -388,13 +754,18 @@ codex:
   model: inherit
 ```
 
-## 一份统一的排障清单
+## 一份统一排障清单
+
+如果 provider-backed profile 还是失败：
 
-如果 provider-backed profile 在 DeepScientist 里还是失败：
+1. 先检查 `which codex` 和 `codex --version`
+2. 检查 `~/.codex/config.toml`
+3. 确认 provider block 存在，profile 也确实指向了它
+4. 确认 API key 或 bearer token 在当前 shell 里真的可见
+5. 确认 Base URL 用的是 Coding Plan / Codex-compatible endpoint，而不是普通平台通用 API
+6. 先跑 `codex --profile <name>`
+7. 再跑 `codex exec --profile <name> "Reply with exactly OK."`
+8. 再跑 `ds doctor --codex-profile <name>`
+9. 最后再跑 `ds --codex-profile <name>`
 
-1. 先手动运行 `codex --profile <name>`
-2. 确认 provider API key 在同一个 shell 中可见
-3. 确认 Base URL 使用的是 Coding Plan endpoint，而不是普通通用 API endpoint
-4. DeepScientist 里优先保持 `model: inherit`
-5. 运行 `ds doctor --codex-profile <name>`
-6. 最后再运行 `ds --codex-profile <name>`
+如果 `codex --profile <name>` 还没通，就先修 Codex 自己，不要先怀疑 DeepScientist。