国内如何使用 Codex：个人开发者从安装到第一个任务
在国内使用 Codex，真正容易混淆的不是安装命令，而是四个彼此独立的问题：页面能否访问、账号是否符合服务条件、认证能否完成、客户端能否连接服务。其中任何一项失败，都可能表现为“Codex 用不了”。
本文不提供绕过地区限制的方法，也不承诺第三方账号、网络或中转服务可用。请先确认自己的账号、所在地区、付款方式和使用方式符合所在地法律法规及 OpenAI 当前服务条款，再按本文排查。
IMPORTANT
本文于 2026 年 7 月 27 日校对。CLI 命令已使用本机 codex --help 与 codex login --help 核对。产品入口和登录方式更新较快，如界面不同，请以官方页面和本机帮助为准。
一、先判断你需要哪一种 Codex
Codex 有多个使用入口，不需要全部安装。
| 入口 | 适合场景 | 本机要求 |
|---|---|---|
| 桌面端中的 Codex | 图形化管理任务、查看改动、处理多个项目 | macOS 或 Windows 客户端 |
| Codex CLI | 终端开发、脚本化、精确控制工作目录和权限 | Git；npm 安装时还需要 Node.js |
| IDE 扩展 | 在编辑器内结合当前文件和选区工作 | 受支持的编辑器 |
| Codex 云端 | 把任务交给托管环境执行 | 账号和工作区具备对应能力 |
新手可以优先尝试桌面端；熟悉终端或主要使用 Linux 的开发者，可以直接从 CLI 开始。本文重点讲跨平台、更容易诊断的 CLI 路线。
二、开始前确认四件事
1. 服务可用范围
先阅读 OpenAI 当前支持地区和服务条款。能下载软件不等于账号一定能使用，网络可达也不等于具备服务资格。不要购买来源不明的共享账号，也不要伪造账号资料。
2. 认证与计费方式
Codex CLI 当前可通过界面支持的 ChatGPT 登录流程或 API Key 登录。两者不是同一套计费体系：ChatGPT 套餐权益不等同于 API 余额，API 充值也不会自动改变 ChatGPT 套餐。
3. 网络出口
个人网络、公司网络和校园网的 DNS、防火墙、TLS 检查与代理策略可能不同。公司设备上应优先咨询管理员，不要自行关闭终端安全软件或导入来源不明的根证书。
4. 一个安全的练习仓库
第一次使用请选择已纳入 Git、可以本地运行、允许丢弃改动的小项目。不要从生产数据库、线上服务器或保存有客户数据的目录开始。
三、安装 Codex CLI
先检查基础工具：
git --version
node --version
npm --version通过 npm 安装：
npm install -g @openai/codex
codex --versionmacOS 和 Linux 也可以使用官方安装脚本。执行在线脚本前，应先确认来源并根据自己的安全要求审查内容：
curl -fsSL https://chatgpt.com/codex/install.sh | sh如果已经安装，不要在多个包管理器之间反复重装。先确认实际执行的是哪一个版本：
# macOS / Linux
command -v codex
# Windows PowerShell
Get-Command codex四、登录并确认状态
账号登录
在项目目录运行：
codex首次启动后按终端和浏览器提示完成登录。如果浏览器回调没有返回客户端，先不要重复注册账号，转到后文的分层排障。
API Key 登录
先查看当前版本支持的选项：
codex login --helpmacOS 或 Linux：
export OPENAI_API_KEY="你的_API_Key"
printenv OPENAI_API_KEY | codex login --with-api-keyWindows PowerShell：
$env:OPENAI_API_KEY="你的_API_Key"
$env:OPENAI_API_KEY | codex login --with-api-key确认状态：
codex login statusCAUTION
API Key 等同于密码。不要把它写进提示词、Git 仓库、AGENTS.md、截图或公开 Issue。长期使用应交给系统钥匙串、密码管理器或受控的环境变量管理工具。
五、使用第三方接口前必须知道的风险
有些教程会要求填写第三方 Base URL 或把 API Key 交给中转平台。这样做意味着你的请求内容、代码片段和凭据可能经过第三方系统，而且其模型兼容性、日志保留、计费与稳定性均不由 OpenAI 保证。
至少先回答下面几个问题：
- 服务运营主体是谁，隐私政策和数据保留期限是什么；
- 是否会记录完整提示词、源代码、响应和身份信息；
- 使用的是你自己的上游凭据，还是平台提供的共享凭据；
- 是否完整兼容 Codex 所需的模型、流式响应和工具调用；
- 发生误扣费、密钥泄露或服务中断时如何处理；
- 你的仓库许可证、客户合同和公司制度是否允许代码经过该服务。
个人练习也应使用独立、限额、可撤销的 Key，不要把拥有其他生产权限的凭据复用给开发工具。公司代码则不应在未经安全和法务评估时发往第三方接口。
六、从安全默认值启动
日常开发推荐从工作区写入和按需审批开始：
codex --sandbox workspace-write --ask-for-approval on-request只想理解陌生仓库时使用只读模式：
codex --sandbox read-only --ask-for-approval on-request不要把 --dangerously-bypass-approvals-and-sandbox 当作网络或登录问题的修复方式。它不会解决账号和连接问题，只会移除本地的重要安全边界。
七、完成第一个可验证任务
进入练习仓库并确认现有改动：
cd /path/to/your-project
git status --short
codex第一条任务先让 Codex 调查：
先不要修改文件。
请阅读 README、项目清单文件和测试目录，然后回答：
1. 项目如何安装、启动、测试和构建；
2. 主要入口文件在哪里；
3. 当前工作区是否有未提交改动；
4. 适合第一次练习的最小任务是什么。
请引用真实文件；不确定的地方明确说明。确认它理解仓库后，再交付一个小改动：
把首页主按钮文案改为“开始体验”。
要求：
- 只修改按钮及直接相关的测试；
- 不改变布局，不新增依赖；
- 完成后运行相关测试和构建；
- 最后列出修改文件、验证结果和未验证项。Codex 报告完成后，自己检查：
git status --short
git diff --stat
git diff八、国内网络环境下的分层排障
不要把所有错误都归因于“网络”。按层检查，能更快找到真实原因。
第 1 层：安装
codex --version
codex --help如果命令不存在，检查 npm 全局目录、PATH 和是否装了多个版本。安装问题与账号无关。
第 2 层：认证
codex login --help
codex login status检查系统日期和时区、浏览器 Cookie、登录回调是否被公司防火墙阻止，以及账号是否符合当前服务条件。
第 3 层：配置
codex --strict-config --version如果严格校验报错，先移除最近新增的配置，再逐项恢复。不要从旧文章复制已经失效的模型名或配置字段。
第 4 层：运行时
codex doctor诊断信息可能包含用户名、本机路径、代理地址、认证摘要和外部服务配置。发到公开平台前必须脱敏。
第 5 层：项目权限
Codex 能登录但不能写文件，通常与沙箱、工作区根目录或文件权限有关；能改代码但不能安装依赖，则可能是工作区网络权限或公司出口策略。先确认任务真正需要什么权限，再只开放对应范围。
九、最短检查清单
- [ ] 账号、地区和付款方式符合当前服务条件；
- [ ] 客户端来自 OpenAI 官方页面或可信软件仓库；
- [ ]
codex --version和codex login status正常； - [ ] API Key 未进入仓库、截图和聊天记录；
- [ ] 第一次任务使用可恢复的 Git 仓库；
- [ ] 默认使用
workspace-write与按需审批； - [ ] 每次交付都检查 diff 和实际测试结果；
- [ ] 第三方接口经过隐私、计费和兼容性评估。
官方资料
最后校对：2026 年 7 月 27 日