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

作者：袖梨 2026-07-29

今天介绍 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，再重新打开终端