15 Codex Provider 配置

May 12, 2026 · View on GitHub

DeepScientist 不会为 MiniMax、GLM、火山方舟、阿里百炼等 provider 额外维护一套独立适配层。

它复用的是你本机已经能正常工作的 Codex CLI。

正确的理解方式是：

先让 codex 自己能工作
再确认同一套配置在终端里可用
然后运行 ds doctor
最后再运行 ds 或 ds --codex-profile <name>

如果 Codex 本身还没工作，先修 DeepScientist 是错误顺序。

如果你要配置其他内建 runner，请同时参考：

官方文档先读哪些

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 配置指南

哪些文件最重要

Codex CLI 默认读取 ~/.codex/ 下面的本地状态。

最重要的文件是：

~/.codex/config.toml
- provider、model、profile、feature 等主要配置
~/.codex/auth.json
- 当你走标准 OpenAI 登录流时，codex login 通常会写这个文件
~/.codex/history.jsonl
- 本地会话历史，不是配置必需项

常用检查命令：

ls -la ~/.codex
sed -n '1,220p' ~/.codex/config.toml
codex --version
codex --help
codex exec --help

第一步：先确认 Codex binary

先检查当前实际在用哪个 Codex：

which codex
codex --version

如果你必须使用特定版本或特定路径的 Codex，可执行文件路径记下来，后续通过 --codex 传给 DeepScientist。

例如：

ds doctor --codex /absolute/path/to/codex --codex-profile glm
ds --codex /absolute/path/to/codex --codex-profile glm

第二步：理解 Codex 两种常见配置形态

A. OpenAI 登录形态

如果你的 Codex 走标准 OpenAI 登录流，通常用这一种。

典型流程：

codex login
codex

这种情况下，~/.codex/auth.json 往往已经存在，config.toml 可以很精简。

最小示例：

model = "gpt-5.4"
model_reasoning_effort = "high"

[projects."/absolute/path/to/your/project"]
trust_level = "trusted"

B. `config.toml` 显式 provider 形态

如果你要把 Codex 指向一个自定义 provider、代理或兼容网关，通常走这一种。

常见写法之一：

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：

[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 里导出环境变量：

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>] 下定义。

示例：

[profiles.glm]
model = "GLM-4.7"
model_provider = "glm"

然后可以这样调用：

codex --profile glm

项目信任

Codex 还会检查项目 trust。

例如：

[projects."/ssdwork/deepscientist/DeepScientist"]
trust_level = "trusted"

如果项目不在 trusted 状态，Codex 运行时可能还会再次确认。

第四步：一套最稳妥的 profile 工作流

4.1 编辑 `~/.codex/config.toml`

建议先备份原文件：

cp ~/.codex/config.toml ~/.codex/config.toml.bak
${EDITOR:-vim} ~/.codex/config.toml

4.2 新增 provider block

通用模板：

[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

[profiles.provider_alias]
model = "provider-model-id"
model_provider = "provider_name"

4.4 先直接验证 Codex

交互式验证：

codex --profile provider_alias

非交互式 smoke check：

codex exec --profile provider_alias "Reply with exactly OK."

如果这里都还不通，不要先怪 DeepScientist，先把 Codex 自己修通。为了尽量贴近 DeepScientist 的实际探测，优先再跑：

printf 'Reply with exactly HELLO.' | codex --search --profile provider_alias exec --json --cd /tmp --skip-git-repo-check -

第五步：把同一套配置映射给 DeepScientist

DeepScientist 推荐三种使用方式。

1. 默认 OpenAI 登录路径

codex login
ds doctor
ds

2. 临时使用某个 provider profile

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：

codex:
  enabled: true
  binary: codex
  config_dir: ~/.codex
  profile: glm
  model: inherit
  model_reasoning_effort: high
  approval_policy: on-request
  sandbox_mode: workspace-write

注意：

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。

例如：

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."

这很适合临时验证；但如果你希望 DeepScientist 稳定复用，还是推荐把 profile 写进 ~/.codex/config.toml。

OpenAI

需要准备什么

正常可用的 Codex CLI
已成功执行 codex login
能直接运行 codex 或 codex exec "Reply with exactly OK."

DeepScientist 命令

ds doctor
ds

持久化 runner 配置

codex:
  enabled: true
  binary: codex
  config_dir: ~/.codex
  profile: ""
  model: gpt-5.4

Ollama

Ollama 官方同时提供 OpenAI-compatible API 和 Codex 集成说明。对 DeepScientist 来说，推荐把它整理成一个 Codex profile，然后通过 ds doctor --codex-profile <name> 使用。

什么时候适合走 Codex + Ollama

适合：

你已经能在本机稳定运行 Ollama
目标模型能处理较长上下文、工具调用和代码修改
http://localhost:11434/v1/responses 能正常工作，或者你使用的是 Ollama 官方 Codex 集成生成的可用配置

不适合：

你的 Ollama 版本只有 /v1/chat/completions 可用
模型上下文很短，无法承载 DeepScientist 的长任务 prompt
你只是想接 Gemini 这类远程 OpenAI-compatible provider；那通常优先走 OpenCode

1. 先安装和启动 Ollama

ollama --version
ollama serve

另开一个终端，拉取并测试模型：

ollama pull gpt-oss:20b
ollama run gpt-oss:20b "Reply with exactly HELLO."

如果你使用的是其他模型，把下面所有 gpt-oss:20b 替换成你实际准备使用的模型。

2. 先直接验证 Ollama 的 OpenAI-compatible API

curl http://localhost:11434/v1/models

再测 Responses API：

curl http://localhost:11434/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss:20b",
    "input": "Reply with exactly HELLO."
  }'

如果 /v1/responses 失败，先升级 Ollama 或换模型，不要直接进入 DeepScientist。

3. 用 Ollama 官方 Codex 集成生成配置

Ollama 官方提供了面向 Codex 的启动命令。推荐先运行：

ollama launch codex --config

它会引导你把 Ollama 配进 Codex。完成后，检查：

sed -n '1,220p' ~/.codex/config.toml
codex --help

如果你要让 DeepScientist 稳定复用这条路径，请确认 ~/.codex/config.toml 里有一个命名 profile。形态可以类似这样：

[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"

注意：不要把自定义 provider 命名成 ollama，这个名字可能和 Codex 内置 provider 冲突。用 ollama-launch、local_ollama 这类别名更稳。

4. 先直接验证 Codex

codex --profile ollama-launch
codex exec --profile ollama-launch "Reply with exactly OK."

如果这里不通，先修 Ollama 或 Codex profile。

5. 再映射到 DeepScientist

一次性启动：

ds doctor --codex-profile ollama-launch
ds --codex-profile ollama-launch

持久化到 ~/DeepScientist/config/runners.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 是：

https://generativelanguage.googleapis.com/v1beta/openai/

环境变量通常是：

export GEMINI_API_KEY="..."

但对 Codex + DeepScientist 来说，Gemini 不是首推路径：

Gemini 官方 OpenAI compatibility 文档主打 Chat Completions
最新 Codex provider 路线更偏向 Responses API
DeepScientist 的 Codex runner 依赖 Codex profile 稳定工作，不会替你在运行时改协议

所以如果你想用 Gemini，优先看 25 OpenCode 配置指南里的 Gemini 小节。

如果你非常明确要试 Codex + Gemini，可以按“chat-only provider”的思路实验，但这不是推荐默认配置：

[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

[profiles.gemini]
model = "gemini-3-flash-preview"
model_provider = "gemini_chat"

验证顺序仍然必须是：

export GEMINI_API_KEY="..."
codex exec --profile gemini "Reply with exactly OK."
ds doctor --codex-profile gemini

如果 codex exec 不通，就不要继续 ds。这时直接切到 OpenCode 通常更省时间。

MiniMax

官方文档：

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

如果你坚持使用 MiniMax-M2.7

推荐路径是：通过你本地的 OpenAI-compatible vllm 服务来暴露 M2.7。

配置形态示例：

[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"

然后按同样顺序验证：

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 路径：

codex:
  enabled: true
  binary: codex
  config_dir: ~/.codex
  profile: m25
  model: inherit
  model_reasoning_effort: high

如果你走本地 vLLM 的 M2.7 路径：

codex:
  enabled: true
  binary: codex
  config_dir: ~/.codex
  profile: m27-local
  model: inherit
  model_reasoning_effort: high

GLM

官方文档：

当前公开文档里的关键值：

Base URL：https://open.bigmodel.cn/api/coding/paas/v4
Model：GLM-4.7 或其它当前 Coding Plan 支持模型

推荐流程：

在 ~/.codex/config.toml 里新增 GLM provider block
新增 [profiles.glm]
先跑 codex --profile glm
再跑 codex exec --profile glm "Reply with exactly OK."
再跑 ds doctor --codex-profile glm
最后跑 ds --codex-profile glm

持久化 runner 配置

codex:
  enabled: true
  binary: codex
  config_dir: ~/.codex
  profile: glm
  model: inherit

火山方舟

官方文档：

https://www.volcengine.com/docs/82379/1925114?lang=zh

当前公开文档里的关键值：

Base URL：https://ark.cn-beijing.volces.com/api/coding/v3
模型：doubao-seed-code-preview-latest、ark-code-latest

推荐流程：

codex --profile ark
codex exec --profile ark "Reply with exactly OK."
ds doctor --codex-profile ark
ds --codex-profile ark

持久化 runner 配置

codex:
  enabled: true
  binary: codex
  config_dir: ~/.codex
  profile: ark
  model: inherit

阿里百炼

官方文档：

这里最重要的一点：

支持：百炼 Coding Plan endpoint 上的 Qwen
不支持：普通百炼 / DashScope 平台的 Qwen API

当前公开文档里的关键值：

Base URL：https://coding.dashscope.aliyuncs.com/v1
key 形态：Coding Plan 专属 key，通常形如 sk-sp-...

推荐流程：

codex --profile bailian
codex exec --profile bailian "Reply with exactly OK."
ds doctor --codex-profile bailian
ds --codex-profile bailian

持久化 runner 配置

codex:
  enabled: true
  binary: codex
  config_dir: ~/.codex
  profile: bailian
  model: inherit

一份统一排障清单

如果 provider-backed profile 还是失败：

先检查 which codex 和 codex --version
检查 ~/.codex/config.toml
确认 provider block 存在，profile 也确实指向了它
确认 API key 或 bearer token 在当前 shell 里真的可见
确认 Base URL 用的是 Coding Plan / Codex-compatible endpoint，而不是普通平台通用 API
先跑 codex --profile <name>
再跑 codex exec --profile <name> "Reply with exactly OK."
再跑 ds doctor --codex-profile <name>
最后再跑 ds --codex-profile <name>

如果 codex --profile <name> 还没通，就先修 Codex 自己，不要先怀疑 DeepScientist。

官方文档先读哪些

哪些文件最重要

推荐配置顺序

顶层字段

项目信任

需要准备什么

重要兼容性说明

火山方舟

阿里百炼

一份统一排障清单