# Codex CLI 接入指南

https://modelportal.ai/docs/integrations/codex?lang=zh

> OpenAI 的终端编程代理，走 Responses 协议接入。

## 适用场景

适合在终端里让代理读项目、改文件、跑测试。Codex CLI 走 Responses 协议（`wire_api = "responses"`），密钥从环境变量读取，不写进配置文件。

## 使用建议

编程代理一次任务会连续发出很多请求，输入也长，建议选上下文较长、支持工具调用的模型，并给密钥设置每日消费上限。

## 推理档位

Codex CLI 把 `config.toml` 里的 `model_reasoning_effort` 作为 `reasoning.effort` 发出。平台按模型实际走的线路能接受的档位处理：上游不收请求的档位时改用更高一档，高过最高档时取最高档；模型不能关闭思考时，要求关闭会返回 400 `unsupported_parameter`。每个模型的对照表见[模型目录](/catalog)里该模型的「推理档位」一节；发生改写的调用，用量明细里会显示「推理档位改写」。

## 连不通时检查

1. `base_url` 填 `https://modelportal.ai/v1`，不要多写 `/responses`。
2. 密钥以 `mp-`（早期的为 `key_`）开头且没有被暂停或撤销，错误码 `invalid_api_key` 表示密钥不可用。
3. 模型 ID 与[模型目录](/catalog)一致，并且在这把密钥的可用模型里。
4. 余额不足会返回 `insufficient_balance`，更多错误见[常见错误](/docs/errors)。

## 配置步骤

1. 安装：npm install -g @openai/codex。
2. 在 shell 配置里导出密钥：export MODELPORTAL_API_KEY=<上面的 API 密钥>。
3. 把下面这段写进 ~/.codex/config.toml 的最前面，再在项目目录执行 codex。

## 配置参数

- API 地址：`https://modelportal.ai/v1`
- API 密钥：`YOUR_API_KEY`
- 模型：`MODEL_ID`

> 平台对 Codex CLI 的兼容性验收仍在进行，遇到问题请提交工单并附上请求 ID。

```toml
model = "MODEL_ID"
model_provider = "modelportal"

[model_providers.modelportal]
name = "ModelPortal.AI"
base_url = "https://modelportal.ai/v1"
env_key = "MODELPORTAL_API_KEY"
wire_api = "responses"
```

## 常见问题

### 为什么 model 和 model_provider 要放在文件最前面？

TOML 里写在某个表头之后的键会归到那个表。放在最前面才是顶层设置，Codex 才会用它们。

### 可以把密钥直接写进 config.toml 吗？

不建议。env_key 让 Codex 从环境变量读密钥，配置文件可以放心同步或备份。