Codex配置实用教程：安装、国内API接入与报错排查

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

若要自行把 Codex 运行起来，可按下文顺序完成操作。涉及内容涵盖 API 配置与 Windows、macOS、Linux 的安装方法，以及报错排查、常用命令和第一次启动。

模型 ID 应以后台实际显示为准，因为模型列表更新较快；本文的整理日期为 2026 年 7 月 20 日。

一、安装前准备

在 CLI、IDE 扩展、云端和桌面客户端这些 Codex 常见使用方式中，本文主要介绍 Codex CLI，进入项目后，它能运行测试、修改代码并读取文件。

开始安装所需准备如下：

• 主流 Linux、macOS 或 Windows 10/11；
• LTS 版本的 Node.js；
• 随 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。

先在后台创建 API Key，并核实当前可用的模型 ID。若官方链路使用不便，可改选支持 Responses API 的 OpenAI 兼容接口；下文以 https://kkflow.org 提供的接口演示配置。

文章、截图和 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 的总结取代；最后需检查测试、类型检查或构建命令，确认其确实执行成功。

一句话即可概括整个配置流程：先装好 Codex CLI 和 Node.js，再设置 auth.json、config.toml，随后重开终端，进入项目后运行 codex。

先确保最小配置能够运行，再逐步增加任务复杂度。出现问题时，依次检查 Node.js、Codex 版本、Base URL、API Key 和模型 ID，通常可以很快定位原因。