Codex 国内使用教程 2026：安装、配置、实跑 + 报错解决（Windows / Mac）
Codex 是 OpenAI 官方的编程智能体：不是聊天机器人，而是能直接读你的代码、改文件、跑命令、审查改动的“AI 程序员”。它有四种形态——CLI（终端里用）、IDE 插件（VS Code / Cursor）、桌面应用、云端版。这篇只讲最常用、也最省钱的 CLI 版，从安装到真正跑通一个任务。
国内用 Codex 的关键不在安装（三条命令的事），而在接哪家服务。官方接口在国内直连不通，所以要配一个中转地址。下面这套流程我用 Codex CLI 0.163.0 实机跑通过，包括“让它真去改代码”这一步——文中有完整实测记录。
一、准备：两样环境
- Node.js 22 或更高（用 npm 安装需要）。去官网 nodejs.org 下 LTS 版，一路下一步。
- Git（强烈建议）。Codex 要求你在 Git 仓库里工作，不是 Git 仓库它会拒绝执行。
二、Windows 用户先看这一步
Codex 在 Windows 上能直接装，但它执行命令时依赖 Linux 那套工具，所以强烈建议用 WSL2（Windows 自带的 Linux 子系统，一次配好长期省事）。管理员身份打开终端，依次执行：
wsl --install
wsl --set-default-version 2
wsl --install -d Ubuntu-22.04装完重启电脑，从开始菜单打开 Ubuntu，设个用户名密码。之后所有 Codex 操作都在这个 Ubuntu 窗口里做（里面的命令和 Mac/Linux 完全一样）。
懒得弄 WSL2 也行：装个 Git Bash，在 Git Bash 里执行同样的命令。但遇到怪问题时，WSL2 的坑最少。
三、安装：三条命令（选一条）
打开终端（Windows 用刚装好的 Ubuntu 窗口 / Mac 用 Terminal），执行其中一条：
方式一：npm（跨平台，推荐）
npm install -g @openai/codex方式二：官方脚本
# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh方式三：包管理器
# macOS
brew install --cask codex四、验证：确认真的装上了
codex --version
codex doctor正常会输出 codex-cli 0.163.0（版本号会随更新变化，有输出就是装好了）；codex doctor 会体检环境、配置和登录状态。
五、国内接入：改一个配置文件（关键一步）
Codex 默认连 OpenAI 官方，国内会一直超时。解决办法是告诉它“走哪个地址”。新建（或编辑）这个文件：
- Mac / Linux / WSL2：
~/.codex/config.toml
接口地址和密钥在 LONG AI 注册后获取：注册 → 「API 密钥」建一个 → 模型名从 模型广场 里复制。
然后把密钥放进环境变量（不要写进配置文件，避免泄露）：
# 临时生效（当前窗口）
export OPENAI_API_KEY="你的sk密钥"
# 永久生效（写入 shell 配置）
echo 'export OPENAI_API_KEY="你的sk密钥"' >> ~/.zshrc
source ~/.zshrc三个必须知道的坑：
①wire_api只能写responses。写chat或chat_completions会直接报config could not be loaded — invalid data，这是 0.163 版实测结果，很多老教程还是错的。
②base_url末尾一定要带/v1，且不要再拼/chat/completions。
③ 不是所有模型都能干活：有的中转/模型只转聊天、不转工具调用，Codex 会回你“我无法访问工作区”。换一个支持工具调用的模型即可（本文实测 glm-5.3 正常，gpt-6-luna 只能聊天）。
六、实测：让它真的修一个 bug
光说没用，我拿一个真实的 bug 试了一次。准备一个斐波那契函数，基准条件写错了（fib(0) 会无限递归），另有一个测试文件。然后让它干活：
cd 你的项目目录
codex exec "运行 python test_fib.py，找出失败原因，修复 fib.py 里的 bug，然后重新运行测试确认全部通过。不要修改测试文件。"它自己运行测试、定位到基准条件写错、改了 4 行代码、又跑了一遍测试。下面是真实截图（节选）：
整个任务消耗 2,610 tokens。这就是 Codex 和普通聊天 AI 的区别：它不是告诉你“你应该这样改”，而是直接改完并验证给你看。
建议：第一次先让它做这种“小、可验证”的任务（修个 bug、补个注释）。确认靠谱之后，再交给它更大的活。
七、四个高频命令（记住就够）
codex—— 交互模式，边聊边改，最适合日常开发codex exec "任务描述"—— 一次性执行，跑完退出，适合批量改、接脚本codex review—— 代码审查，让它对着你的改动找问题codex resume --last—— 接着上次的会话继续聊
八、安全设置（大白话版）
配置里那两个参数决定它“能干什么”和“要不要问你”：
sandbox_mode：read-only只看不改（安全）／workspace-write只能在项目目录里改（推荐）／danger-full-access全盘可写（危险，别用）approval_policy：untrusted每步都问／on-request越界才问（推荐）／never不问直接干（慎用）
日常开发用workspace-write+on-request最稳。改完一定用git diff核对，不满意git checkout .一键撤销。
九、大概要花多少钱
Codex 本身免费开源，花钱的是模型调用——按 token 计费，用多少算多少。参考上面那次实测：让它修一个 bug、改 4 行、跑两次测试，一共 2,610 tokens。按中转站常见的模型价格算，这种任务一次通常就是几分钱量级；具体以 模型广场 的实时价格为准。
日常写代码一天用下来，多数人一个月几十块足够；重度使用可以选便宜模型（比如 deepseek 系列）干重复活，复杂任务再切强模型。
十、常见报错对照表
- config could not be loaded / invalid data：
wire_api写错了，改成responses - “我无法访问工作区 / 没有执行工具”：当前模型不支持工具调用，换模型
- not in a git repository：当前目录不是 Git 仓库，先
git init或进到项目目录 - 401 Unauthorized：密钥没生效。确认环境变量已设置，或重开终端
- 404 / 一直转圈：
base_url写错了，确认末尾是/v1，没有多余斜杠 - npm 安装报 EACCES：别用 sudo，改用 nvm 管理 Node
- Windows 报 'sh' is not recognized：装 Git Bash 或改用 WSL2
十一、视频教程
说明：抖音不允许其他网站内嵌播放它的视频，所以做成卡片，点一下跳过去看。