Codex CLI 是 OpenAI 的终端编程代理，能读代码、改文件、执行命令。很多团队希望把它接到自建网关或第三方 OpenAI 兼容入口上，用统一的 Key、账单和额度管理。所谓“接入自定义 API”，落到配置上只有三处：请求发往哪里（Base URL）、用什么身份认证（Key）、调用哪个模型（模型名）；真正容易出错的，是鉴权方式、协议匹配和权限边界。
本文以 2026 年 10 月的常见版本为例，按安装、鉴权、配置、验证、沙箱审批、团队落地和安全的顺序走一遍。Codex 版本迭代较快，命令与配置项请以 codex --help 和官方文档为准。
说明：OpenAI、Codex、ChatGPT 是 OpenAI 的商标或注册商标，本文仅作技术接入说明，与 OpenAI 无隶属关系。接口要求、模型标识和计费方式可能随版本调整，请以官方文档和站内模型价格为准。
一、先确认协议与鉴权方式
Codex CLI 的自定义 provider 走 Responses 协议，wire_api 当前只接受 responses；旧版 chat 写法已弃用，并在不少版本中直接报错。网关至少要满足两点：提供兼容的 /v1/responses 入口；支持流式输出，并能返回终止事件 response.completed。只有 Chat Completions 的入口，需要中间层做协议转换，不能直接把地址填进来。
鉴权有三条路，选一条即可：
| 方式 | 典型命令或配置 | 适合场景 | 注意 |
|---|---|---|---|
| ChatGPT 账号登录 | codex login |
个人试用、临时使用 | 走账号额度，不适合 CI |
| API Key 登录 | codex login --with-api-key（从 stdin 读 Key） |
个人按量使用 | 凭证会存入 auth.json 或系统钥匙串 |
| 自定义 provider | env_key 指向环境变量 |
团队网关、统一计费 | Key 不写进 TOML，便于限额与吊销 |
查看当前登录状态用 codex login status，清除本地登录凭证用 codex logout。如果同时存在多种凭证，先确认实际生效的是哪一种，再排查配置。
二、安装 Codex CLI
按系统选一种方式，安装后确认版本：
# macOS / Linux 官方安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 也可以使用包管理器，具体以官方文档当前说明为准
npm install -g @openai/codex
brew install --cask codex
codex --version
第一次启动建议在一个空的测试仓库里进行，不要直接在含生产密钥、客户数据或未脱敏配置的目录里做试验。Codex 会读取当前目录的上下文，目录越干净，排错越简单。
三、配置 Base URL、Key 与模型
用户级配置在 ~/.codex/config.toml，Windows 对应 %USERPROFILE%\.codex\config.toml。有一个高频坑：顶层键必须写在第一个表头之前；如果把 model、model_provider 写在 [model_providers.xxx] 后面，它们会被当成该表的字段，表现为“配置没生效”。
# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"
web_search = "disabled"
[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_API_KEY"
字段含义：
model：填 API 标识，不是网页上的展示名；必须和站内价格页完全一致。model_provider：与下面的 provider ID 一致；不要用openai、ollama、lmstudio这些保留名称。base_url：包含 API 路径，通常以/v1结尾，不要重复拼接。wire_api：填responses。env_key：写环境变量名，不是 Key 本身。web_search：网关不支持联网搜索时先设为disabled，避免请求走向未开通的能力。
然后在启动 Codex 的同一个 shell 里导出 Key：
export ZSQH_API_KEY="sk-你的密钥"
Windows PowerShell 用 $env:ZSQH_API_KEY="sk-你的密钥"。要让变量长期生效，应写入 shell 配置文件或系统环境变量，并确认图形界面启动的编辑器也能读到。
如果网关要求自定义请求头，可以改用 env_http_headers = { "X-API-Key" = "ZSQH_API_KEY" }；这种方式不走远程目录发现，需要同时提供本地模型目录 model_catalog_json。如果 Key 由密钥管理工具动态签发，可以用 [model_providers.zsqh.auth] 的 command 从外部程序取令牌，但它不能与 env_key 同时使用。模型别名较多时，再考虑 model_catalog_url 或本地 model_catalog_json；没有这些需求就不必增加复杂度。
另外要记住：受信任项目会加载 .codex/config.toml，但其中的 model_provider、model_providers 和 profile 定义会被忽略。provider 一定要写在用户级配置里。
四、验证接入是否真的生效
按顺序做，能快速区分“工具没配好”和“网关没走通”：
- 执行
codex login status，确认当前认证方式；再确认env_key指向的变量在启动环境里非空。不要在共享终端完整打印 Key。 - 执行
codex doctor，检查配置文件位置、环境变量和常见配置冲突。 - 在测试仓库执行
codex exec "Reply with exactly: gateway-ok"，返回gateway-ok说明基本链路通了。codex exec默认是只读沙箱，适合做冒烟测试。 - 进入交互模式执行
/status，核对当前模型与 provider 是否为你配置的值。 - 到网关控制台查看请求日志，确认用户、模型别名和上游路由。只看客户端有回复还不够，回复可能来自缓存或旧配置。
- 若仍失败，先核对 Base URL 的
/v1与/responses路径，再检查代理是否改写或剥离了Authorization头。
五、沙箱与审批：两个独立开关
很多人把“自动执行”和“能改哪些文件”混为一谈。Codex 把它们拆成两个控制：审批策略决定什么时候停下来问你，沙箱决定进程能碰哪些文件和网络。
当前版本的 approval_policy 常用值是 on-request，适合大多数日常开发；never 只建议放在隔离的自动化环境里。旧的 untrusted 已不再支持，on-failure 也已弃用，照抄旧教程容易直接报配置错误。
sandbox_mode 有三个值：read-only、workspace-write、danger-full-access。默认从只读开始；需要改代码时用 workspace-write，并用 sandbox_workspace_write.writable_roots 限定可写目录；danger-full-access 只应出现在容器或一次性 runner 里。需要联网时，单独打开 sandbox_workspace_write.network_access，不要顺手放宽全部权限。
非交互模式可以用 codex exec --sandbox workspace-write 指定沙箱；如果组织允许自动审查，可加 --approve-for-me。注意 --full-auto 已不再支持，旧脚本里的这个参数需要改掉。交互模式下可以用 /permissions 查看和调整当前权限。
六、团队落地：先小范围，再统一配置
建议先找两三个人、一个非核心仓库做试点，跑通后再推广。落地时重点不是“装了多少人”，而是配置能否复制、故障能否定位。
- 一人一把 Key，按项目或环境再拆分；不要全组共用一把。
- 在网关侧设置预算、并发和模型白名单，防止 Agent 循环消耗额度。
- 用企业托管配置统一
approval_policy、sandbox_mode和cli_auth_credentials_store；requirements.toml可以禁止never和danger-full-access这类高风险组合。 - 需要强制登录方式时，用
forced_login_method = "chatgpt"或"api"，避免成员混用凭证。 - 维护一份不含密钥的配置模板，写清 Base URL、模型标识和排查命令。
- 每月核对网关用量，按人、项目、模型三个维度看异常。
七、安全清单
- Key 只放环境变量、系统钥匙串或密钥管理服务，不写进
config.toml和 Git。配置里的experimental_bearer_token虽然存在，但官方不推荐。 - Codex 使用独立 Key，便于设置额度、过期时间和单独吊销。
- 默认只读沙箱；需要写入时限定到具体仓库目录，任务结束就收回权限。
- 不要把
.env、auth.json、生产配置、客户数据放进上下文；大仓库先排除构建产物和依赖目录。 - 审查 Codex 生成的命令和补丁，尤其是删除、网络请求、权限提升类操作。
- 团队镜像固定 Codex 版本，升级前先在测试环境验证配置兼容性。
- 开启网关用量告警，发现异常调用先停 Key，再查日志。
常见问题
Codex CLI 必须用 Responses 协议吗？
当前自定义 provider 的 wire_api 只接受 responses，旧 chat 写法已弃用。网关若只提供 Chat Completions，需要协议转换层，或改用支持 Responses 的入口。
配置写好了，为什么请求还是走默认地址？
先确认改的是 ~/.codex/config.toml，再确认顶层键写在表头之前、model_provider 与 provider ID 完全一致。项目级配置里的 provider 定义会被忽略，这是常见原因。
可以在 config.toml 里直接写 Key 吗？
不建议。用 env_key 引用环境变量，或通过 [model_providers.xxx.auth] 调用外部取令牌命令。明文 Key 容易随配置备份、截图或仓库泄露。
ChatGPT 登录和 API Key 计费一样吗？
不一样。ChatGPT 登录走账号体系，API Key 走接口按量计费，两者的额度、账单和权限范围不同，团队采购时要分开核算。
团队可以共用一把 Key 吗？
不建议。共用 Key 无法定位是谁在调用，也无法在单人泄露或离职时单独吊销。按人、按环境发 Key，配合额度和过期时间更可控。
下一步
Codex 接入的难点不在安装，而在协议匹配和权限边界：先确认网关支持 Responses 与流式终止事件，再配置 Base URL、Key 和模型，最后用只读沙箱做冒烟测试。需要统一入口和用量管理，可以注册中商起航 AI 网关，模型与接口范围以模型价格页为准。
相关阅读：
