Codex配置使用教程：安装、国内API接入与常见报错

今天来聊聊 Codex CLI 的安装和配置，把流程掰开揉碎了讲一遍，从系统准备到跑通第一个任务，尽量让新手也能一次搞定。

这里会覆盖 Windows、macOS、Linux 三大平台的安装方法，以及 API 配置、首次启动、常用命令和常见报错排查。想自己把 Codex 跑起来，按下面的顺序操作就行。

说明一下：本文整理于 2026 年 7 月 20 日，模型列表更新比较快，模型 ID 以后台实际显示为准。

一、安装前准备

Codex 的使用方式有好几种：CLI、IDE 扩展、云端和桌面客户端。这里重点讲

，它的好处是能直接进入项目目录，读取文件、修改代码、运行测试，一条龙搞定。

安装前需要确认环境满足条件：

• Windows 10/11、macOS 或主流 Linux 系统
• Node.js LTS 版本
• npm（安装 Node.js 时会一并装上）
• 一个用于测试的项目目录

这些齐了，就往下走。

二、安装 Codex CLI

Windows

先从 Node.js 官网下载安装 LTS 版本：

https://nodejs.org/

安装后重新打开 PowerShell，检查环境：

node -v
npm -v

然后安装 Codex：

npm install -g @openai/codex@latest
codex --version

正常返回版本号，说明安装成功。

macOS / Linux

先安装 Node.js LTS 版本，再执行：

node -v
npm -v
npm install -g @openai/codex@latest
codex --version

macOS 也可以用 Homebrew 安装 Node.js：

brew install node

如果安装完成后提示找不到 codex，先关闭旧终端重新打开，再检查 npm 全局目录是否已加入 PATH。

三、安装完成后为什么还要配置 API

codex --version 能跑通，只说明本地程序装好了，离真正调用模型还差几步。Base URL、API Key、模型名和接口协议，一个都不能少。

如果官方链路使用不方便，选择支持 Responses API 的 OpenAI 兼容接口也一样。下面以 kkflow 提供的接口作为配置示例，先在后台创建 API Key，并确认当前可用的模型 ID。

需要提醒的是，文章、截图和 Git 仓库中不要出现真实 Key，本文统一用 sk-你的API密钥 代替。

四、配置 Codex

Codex 的配置目录在不同系统上路径不一样：

系统	路径
Windows	%USERPROFILE%.codex
macOS / Linux	~/.codex/

需要准备两个文件：

.codex/
├── config.toml
└── auth.json

1. 配置 config.toml

Windows 用户执行：

New-Item -ItemType Directory -Force "$env:USERPROFILE.codex" | Out-Null
notepad "$env:USERPROFILE.codexconfig.toml"

macOS / Linux 用户执行：

mkdir -p ~/.codex
nano ~/.codex/config.toml

写入下面的配置：

model_provider = "kkflow"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"

disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true

model_context_window = 400000
model_auto_compact_token_limit = 360000

[model_providers.kkflow]
name = "KKFlow"
base_url = "https://kkflow.org/v1"
wire_api = "responses"
requires_openai_auth = true

注意，这里的 gpt-5.6-sol 是示例模型。如果出现 model not found，需要根据接口后台的实际模型 ID，同时修改 model 和 review_model。

上下文窗口和自动压缩阈值也要与模型实际能力匹配，如果实际上下文不足 400000 Token，需要相应调低这两个数值。

还有一点要特别留意：model_provider 必须和下面的 Provider 配置名称对应，base_url 末尾不要漏掉 /v1。

2. 配置 auth.json

Windows 打开文件：

notepad "$env:USERPROFILE.codexauth.json"

macOS / Linux：

nano ~/.codex/auth.json

写入：

{
  "OPENAI_API_KEY": "sk-你的API密钥"
}

保存后不要把 auth.json 上传到 Git，也不要在教程截图中展示真实内容。

五、启动并验证

先进入项目目录：

cd your-project-folder
codex

第一次使用，建议先发一条只读任务：

先不要修改文件，请分析当前项目的目录结构、技术栈和主要模块。

如果 Codex 能读取项目并正常回答，说明安装、API Key、Base URL 和模型已经跑通。

接着再让它执行一个小任务：

先给出修改计划，等我确认后再动手。修改完成后运行现有测试，并汇总实际结果。

不要第一次使用就让它重构整个项目。先分析、再计划、确认后修改，更容易控制结果。

六、常用命令

进入 Codex 后输入 /，可以查看当前版本支持的命令。常用的有：

命令	用途
/model	切换模型和推理等级
/approvals	调整文件和命令授权方式
/new	开启新会话
/init	初始化 AGENTS.md
/compact	压缩较长的上下文
/diff	查看代码修改差异
/status	查看当前模型和会话状态

AGENTS.md 可以记录项目技术栈、启动命令、测试命令和修改边界。比如：

# AGENTS.md

## 常用命令

- 安装依赖：pnpm install
- 本地启动：pnpm dev
- 运行测试：pnpm test

## 修改要求

- 不要修改 node_modules 和构建产物。
- 新增业务逻辑时补充测试。
- 修改完成后运行测试和类型检查。

说明越具体，Codex 越容易按项目真实规则执行。

七、常见报错排查

报错或现象	优先检查
找不到 node、npm 或 codex	是否安装成功、是否重开终端、PATH 是否生效
401 Unauthorized	Key 是否正确，前后是否多了空格
403 Forbidden	Key 是否有当前模型的访问权限
model not found	模型 ID 是否和后台完全一致
404 或一直重试	Base URL 是否包含 /v1，接口是否为 responses
改配置后没变化	完全退出 Codex 并重新打开终端

如果不确定模型名称，直接回接口后台核对模型列表，再检查 config.toml 中的模型 ID 是否存在。

八、最后几个使用建议

正式修改项目前，先执行：

git status

确认当前工作区状态，重要修改先创建 Git 检查点。Codex 完成任务后，还要查看：

git diff

最后确认测试、类型检查或构建命令是否真的执行成功。AI 的总结不能代替实际验证结果，这一点在实践中尤其重要。

整个配置流程可以压缩成一句话：安装 Node.js 和 Codex CLI，配置 config.toml 与 auth.json，重开终端，再进入项目运行 codex。

先把最小配置跑通，再逐步增加复杂任务。遇到问题时按 Node.js、Codex 版本、Base URL、API Key、模型 ID 的顺序排查，通常很快就能找到原因。