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

今天介绍 Codex CLI 的安装与配置方法。

内容涵盖 Windows、macOS、Linux 的安装流程，以及 API 配置、初次启动、常用命令和故障排查。若要自行运行 Codex，依照下列顺序操作即可。

整理本文的日期为 2026 年 7 月 20 日。鉴于模型列表变化较快，后台实际展示的模型 ID 才是核对依据。

一、安装前准备

Codex 的常见使用形态包括 CLI、IDE 扩展、云端及桌面客户端，本文重点介绍 Codex CLI，读取文件、运行测试和修改代码等操作，都能由它进入项目后直接完成。

安装之前需要备好：

• 主流 Linux、macOS，以及 Windows 10/11；
• Node.js LTS 版本；
• 安装 Node.js 的过程会同时装入 npm；
• 一个用来测试的项目目录。

二、安装 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 的正常执行来证明；模型要真正被调用，还必须具备接口协议、模型名、API Key 与 Base URL。

支持 Responses API 的 OpenAI 兼容接口，也可在官方链路使用不便时作为选择。配置示例采用 https://kkflow.org 提供的接口：应先从后台创建 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

首次使用时，建议先发送一项只读任务：

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

安装、模型、Base URL 和 API Key 是否全部跑通，可以通过 Codex 能否读取项目并作出正常回答来判断。

随后再让它完成一个小任务：

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

第一次使用时不要直接要求它重构整个项目。先分析、再规划，获得确认后再修改，结果会更容易控制。

六、常用命令

当前版本可用的命令，会在进入 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 或持续重试	接口是不是 responses，以及 Base URL 中有没有 /v1
修改配置后没有变化	彻底退出 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，通常原因很快便能定位。