HopBase 文档Codex CLI
配置 Codex CLI 使用 HopBase 的 OpenAI Responses 兼容接口。
Codex CLI 是 OpenAI 的官方编程代理。首次接入建议使用控制台「一键接入」；手动接入需要配置 config.toml 和 OPENAI_API_KEY。
推荐：控制台一键接入
选择 Codex 分组密钥
登录控制台，在「API 密钥」找到 Codex Plus 或 Codex Pro 分组的密钥。
生成接入命令
点密钥旁的「一键接入」，选择 Codex CLI，确认系统是 macOS / Linux 还是 Windows PowerShell，再点「生成接入命令」并复制。
偏好图形界面时，按CC Switch 指南从密钥菜单点「导入 CCS」，再选择 Codex CLI。
原文件先备份为 config.toml.bak.时间戳；新配置写入 model = "gpt-6-astra"、model_reasoning_effort = "xhigh" 和 requires_openai_auth = true，密钥写进 ~/.codex/auth.json，不设置环境变量。xhigh 是最高推理档位，token 消耗最多，日常可改成 high 或 medium。
推理档位与分组
| 设置 | 说明 |
|---|---|
model_reasoning_effort | 可选 low / medium / high / xhigh；档位越高思考越久、token 消耗越多 |
| Codex Plus / Codex Pro 分组 | 两组可用模型相同：gpt-6-astra、gpt-6-sol、gpt-6-luna、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5；以当前密钥调 GET /v1/models 的返回为准 |
| 生成图片 | Codex 分组不提供 gpt-image-*。生图请给密钥加上 GPT Image 全系 分组，见图片生成 API |
手动配置
| 系统 | config.toml 位置 |
|---|---|
| macOS / Linux | ~/.codex/config.toml |
| Windows | C:\Users\你的用户名\.codex\config.toml |
如果文件不存在，请创建文件并填入以下内容：
# config.toml
model_provider = "hopbase"
model = "gpt-5.6-sol"
[model_providers.hopbase]
name = "HopBase"
base_url = "https://api.hop-base.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"手动配置用 env_key 从环境变量读密钥；一键接入用的是 requires_openai_auth = true 加 auth.json。不要把 requires_openai_auth = true 和环境变量写法混在同一份配置里：Codex 0.153 实测这种组合不发送密钥，网关返回 401 missing_api_key。
设置 OPENAI_API_KEY 后启动 Codex：
临时设置：只在当前终端窗口有效。
export OPENAI_API_KEY=sk-你的密钥
codex永久设置：写入 shell 启动文件，之后新开终端即可使用。
# zsh（macOS 默认）
echo 'export OPENAI_API_KEY=sk-你的密钥' >> ~/.zshrc
source ~/.zshrc
# bash（Linux 常见；与上面 zsh 二选一）
echo 'export OPENAI_API_KEY=sk-你的密钥' >> ~/.bashrc
source ~/.bashrcCodex 的联网搜索会请求 /v1/alpha/search，远程上下文压缩会请求 /v1/responses/compact，这两个接口目前都不支持，会返回 404。联网搜索的 404 不影响普通对话；不想看到这条报错，在 Codex 中关闭联网搜索即可。
下一步
- CC Switch：Codex App 接入，或在多把密钥之间切换
- OpenAI SDK：在自己的程序里调用同一批 GPT 模型
- 报错速查：按报错原文排查