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

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

本文涵盖 Windows、macOS、Linux 的安装方法，以及 API 配置、首次启动、常用命令和报错排查。按照下文顺序操作，即可自行运行 Codex。

整理日期为 2026 年 7 月 20 日；由于模型列表更新较快，请按后台实际显示确定模型 ID。

一、安装前准备

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

执行前，请先装好当前 LTS 版本的 Node.js：

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。若官方链路不方便使用，可改选兼容 OpenAI 且支持 Responses API 的接口；以下配置示例采用 https://kkflow.org 提供的接口。

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

四、Codex 的配置

配置目录所在位置（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 后输入 / 查看，其中常用项有：

项目的技术栈、启动命令、测试命令和修改边界，都可以记录在 AGENTS.md 中。例如：

# AGENTS.md

## 常用命令

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

## 修改要求

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

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，通常能很快定位原因。