国内如何使用 Codex CLI：API 登录、base_url 配置和常见报错

国内使用 Codex CLI，要先把问题拆成四层：安装是否成功、登录方式是否合适、API 入口是否可达、Codex 权限和网络配置是否允许当前任务。很多“Codex 用不了”的问题，其实不是 Codex 本身坏了，而是登录回调、API key、base_url、终端代理或沙箱网络访问其中一层没有对齐。

先判断你卡在哪一层

国内用户常见问题可以先按下面这张表定位。

现象 可能原因 优先动作 codex 命令不存在 没安装或 PATH 没生效 重新安装，检查 codex --version 浏览器登录打不开或回调失败 本地回调、网络、远程服务器限制 改用 codex login --device-auth API key 登录后请求失败 Key、组织、计费或 API 入口问题 检查 key 来源和 provider 配置 能聊天但命令不能联网 Codex 沙箱默认限制命令网络 通过批准或配置开启网络 配了 base_url 仍失败 /v1、wire API、鉴权字段不匹配 回到当前后台模板核对

这个顺序很重要：先确认 CLI 可用，再看登录，再看 API，再看权限。

第一步：安装并诊断 Codex CLI

macOS / Linux 可用官方 standalone 安装脚本：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

Windows PowerShell：

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

安装后先跑：

codex --version codex doctor

codex doctor 会检查本地安装、配置、认证、运行环境、Git、终端和线程状态。国内环境里，如果它提示认证、网络或终端异常，先修这些基础问题，再动 config.toml。

第二步：选择合适的登录方式

Codex CLI 支持 ChatGPT 登录和 API key 登录。国内用户不要把这两种方式混成一个问题。

登录方式 适合谁 国内常见问题 ChatGPT 登录 有 ChatGPT 账号，主要做本地交互开发 浏览器登录、设备码、回调地址可能受网络影响 API key 登录 自动化、脚本、本地 CLI、需要按 API 计费 Key 来源、base_url、计费组织和 provider 字段要一致 设备码登录 远程服务器、无浏览器、回调失败 需要账号侧允许 device code flow

常规登录：

codex login

设备码登录：

codex login --device-auth

登录缓存可能在：

~/.codex/auth.json

如果你切换账号、切换 API key 或改 provider 后仍异常，可以先退出再重新登录：

codex logout codex login

第三步：理解 config.toml 应该写在哪里

Codex 用户级配置文件默认是：

~/.codex/config.toml

项目也可以有：

.codex/config.toml

但 OpenAI manual 说明，项目级 .codex/config.toml 不能覆盖 provider、model provider、base URL、认证等敏感设置；这些应放在用户级 ~/.codex/config.toml 或 profile 配置中。

常见的本地开发配置可以先保持简单：

approval_policy = "on-request" sandbox_mode = "workspace-write"

如果命令确实需要联网，例如安装依赖或访问测试服务，可以在理解风险后开启：

[sandbox_workspace_write] network_access = true

不要为了省事直接长期使用 danger-full-access。它适合受控环境里的短任务，不适合作为日常默认值。

第四步：API 网关和 base_url 怎么配

如果你使用的是 OpenAI-compatible API 或 LLM proxy，核心是让 Codex 知道三个信息：模型名、provider、鉴权方式。

下面是一个通用 provider 写法，字段来自 Codex custom model providers 文档；实际发布前应以你所用平台后台模板为准。

# ~/.codex/config.toml model_provider = "gateway" model = "后台显示的模型名" [model_providers.gateway] name = "OpenAI-compatible gateway" base_url = "https://api.fenno.ai" wire_api = "responses" env_key = "FENNO_API_KEY"

然后在当前 shell 中设置 key：

export FENNO_API_KEY="sk-你的-API-Key" codex "解释这个仓库的目录结构，不要修改文件"

如果后台模板使用 requires_openai_auth = true，就不要再同时写 env_key。这类模板通常要求你通过 Codex 的 API key 登录流程保存凭据。两种鉴权方式混用，是国内用户配置失败的高频原因。

第五步：/v1 到底要不要写

base_url 是否带 /v1，取决于 provider 实现和后台模板。

工具或场景 常见写法 判断依据 Codex custom provider 可能是根域名，也可能是 /v1 以当前后台模板为准 OpenAI-compatible SDK 通常是 /v1 SDK 文档和平台模板 内部 LLM proxy 由代理服务定义 代理路由规则

不要看到 OpenCode、Python SDK 或别人的旧配置用了 /v1，就直接复制到 Codex。Codex 的 wire_api、provider、鉴权方式和当前版本都会影响最终请求路径。

第六步：常见报错排查表

报错或现象 优先检查 处理方式 401 / unauthorized key 是否来自当前 provider 重新设置环境变量或重新登录 404 / model not found model 名称是否存在 用后台显示的模型名，不要凭记忆写 连接超时 终端网络或 base_url curl 测试 endpoint，检查代理 一直请求批准 sandbox 或网络权限 明确设置 workspace-write + on-request 配置不生效 写到了项目级配置 provider 相关字段放到 ~/.codex/config.toml app 和 CLI 不一致 版本或配置层不同 分别跑版本检查，确认使用同一 CODEX_HOME

如果你刚改过 provider，建议用一个只读 prompt 测试：

codex --sandbox read-only "只解释当前目录结构，不要修改文件"

只读任务能先验证模型连接，避免把 API 配置问题和文件修改权限问题搅在一起。

FAQ

Q：国内使用 Codex 一定要配置 API 网关吗？
不一定。能稳定完成 ChatGPT 登录和官方 API 访问时，按官方默认路径使用即可。只有在 API 入口、计费、团队 Key 管理或网络环境需要额外处理时，才考虑 OpenAI-compatible provider。

Q：API key 登录和 ChatGPT 登录有什么区别？
ChatGPT 登录跟随 ChatGPT 工作区权限和计划；API key 登录走 OpenAI Platform 或对应 provider 的计费和数据策略。Codex cloud 需要 ChatGPT 登录，本地 CLI 和 IDE extension 支持两者。

Q：我可以把 API key 写进 config.toml 吗？
不建议。更合适的做法是使用 env_key 指向环境变量，或使用 Codex 登录缓存/系统 credential store。配置文件可能被同步、备份或误提交，直接写 key 风险很高。

Q：为什么配了 base_url 还是请求官方地址？
常见原因是配置写错位置、provider 没被 model_provider 选中、字段名不被当前 Codex 版本识别，或项目未被信任导致项目级 .codex/config.toml 被跳过。provider 相关设置优先放在用户级配置里。

Q：应该用哪个模型名？
用当前 provider 后台显示的模型名，不要照搬旧文章里的模型名。Codex 和各类 API 网关的模型目录变化很快，未核实模型名最容易导致 model not found。

参考资料与时效性

本文基于 2026-07-02 抓取的 OpenAI Codex manual，以及本地 Fenno API 配置材料整理。重点参考 Authentication、Config basics、Custom model providers、Agent approvals & security、CLI command reference 等章节。Codex CLI、模型名称、provider 字段和第三方后台模板都可能更新，正式配置前应重新核对官方文档和当前后台模板。