2026 Codex CLI 使用教程：Windows / Mac 安装、API Key 配置、模型切换与常见报错

不讲一堆概念，这篇只做一件事：从一台还没配好的电脑开始，把 Codex CLI 真正跑起来。

网上的 Codex 教程已经很多了，但最麻烦的地方也正是在这里：有的还在讲旧登录方式，有的 Base URL 已经变了，有的只贴一段配置，出了 401、404 就没下文。

如果你只是想知道 Codex 是什么，官方文档已经够看。可如果你的目标是“我今天就想把它装好，而且出错时知道该查哪里”，那就继续往下。

这篇走的是 API Key / 自定义接口这条路线。我会用 AI Code With 作为实际示例，因为后面的 API Key、Codex 专用 Base URL、模型和调用记录，本来就需要一个真实平台来完成。

01｜先确认：你其实有两条登录路线

Codex CLI 现在既可以用 ChatGPT 账号登录，也可以走 API Key。第一次运行 `codex` 时，官方支持 ChatGPT OAuth；CLI 也支持 API Key 认证。

• 只想先体验 Codex：直接用 ChatGPT 登录，最省事。
• 想自己配置 API、Base URL、模型，或者后面需要切不同模型：走 API Key 路线。

这篇文章重点讲第二条。不是因为 Codex 必须买 API Key，而是因为我们要把“第三方 API 怎么配置、怎么验证、怎么排错”这条最容易出问题的链路讲清楚。

02｜开始前只准备

Node.js 18+（这篇采用 npm 安装路线；如果你已经装好可以直接跳过）。

一个你愿意拿来测试的小文件夹，不要一开始就指向公司机密或重要原始资料。

先检查 Node.js：

node --version

能看到类似 `v20.x`、`v22.x` 或更高版本，就可以继续。AI Code With 当前 Codex 文档要求 Node.js 18+。

03｜Windows：把 Codex CLI 装起来

1. 打开 PowerShell

按 Win 键，搜索 PowerShell，打开即可。先不用急着以管理员身份运行，正常安装如果没有权限问题就够了。

2. 安装 Codex CLI

npm install -g @openai/codex

安装完成后，直接查版本：

codex --version

能正常显示 Codex 版本号，就说明 CLI 已经进系统了。

如果提示“在此系统上禁止运行脚本”

先别直接把 PowerShell 改成 Unrestricted。Microsoft 把执行策略视为安全边界的一部分，更稳妥的做法是先查看当前策略：

Get-ExecutionPolicy -List

如果确实是当前用户策略拦住了脚本，可以只对当前用户改成 RemoteSigned：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

改完重新开一个 PowerShell，再执行安装命令。公司电脑如果被组策略锁定，不要强改，直接找 IT。

04｜macOS：同样三步

1. 确认 Node.js

node --version

如果没有 Node.js，可以用 Homebrew 安装：

brew install node

没有 Homebrew 的话，也可以直接从 Node.js 官网安装 LTS 版本。

2. 安装 Codex CLI

npm install -g @openai/codex

如果 npm 下载很慢，AI Code With 当前文档也给了国内镜像安装方式；但如果默认 npm 能装，优先用官方默认源，变量越少越好。

3. 检查版本

codex --version

05｜为什么这篇用 AI Code With 来配 API Key

到了这里，Codex 已经装好了。下一步才是这篇教程和普通“安装教程”真正分开的地方：我们要把自定义 API 路线跑通。

我这里用 AI Code With 做示例。它更像一个统一的 AI 编程模型入口：一份额度可以在平台支持的多个模型之间使用，同时能看到 API 调用记录。对这篇教程来说，最重要的不是“平台介绍”，而是后面三样东西都能直接拿到：API Key、Codex 专用端点、调用记录。

创建 API Key

打开 AI Code With，创建一个新的 API Key。创建后马上复制到安全位置。

06｜配置 auth.json 和 config.toml

Codex 的用户级配置放在 `.codex` 目录里。Windows 通常是 `%USERPROFILE%\.codex`，macOS 通常是 `~/.codex`。

Windows：先把目录建出来

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"

然后分别打开两个文件：

notepad $env:USERPROFILE\.codex\auth.jsonnotepad $env:USERPROFILE\.codex\config.toml

如果记事本提示文件不存在，选择创建即可。注意文件名必须真的是 `auth.json` 和 `config.toml`，不要变成 `auth.json.txt`。

macOS：建目录并打开文件

mkdir -p ~/.codexnano ~/.codex/auth.json

写完 auth.json 后，用 Ctrl + O 保存、Enter 确认、Ctrl + X 退出，再打开 config.toml：

nano ~/.codex/config.toml

auth.json：只放你的 API Key

{ "OPENAI_API_KEY": "在这里替换成你的 AI Code With API Key"}

config.toml：最关键的是 provider、模型和 Base URL

model_provider = "aicodewith"model = "gpt-5.5"model_reasoning_effort = "high"[model_providers.aicodewith]name = "AI Code With"base_url = "https://api.aicodewith.ai/chatgpt/v1"wire_api = "responses"requires_openai_auth = true

示例里的 `gpt-5.5` 是 AI Code With 当前 Codex 文档给出的模型值。模型上线、下线和命名都会变化，所以真正配置时，以你账号里当前可用的模型 ID 为准。

07｜别看到模型名就以为成功：一定要做两次验证

第一层：Codex 自己有没有读到配置

先进入你准备用来测试的文件夹，再启动 Codex：

codex

进入交互界面后输入：

/status

重点看当前模型、工作目录等信息。如果模型已经是你配置的值，说明 config.toml 至少被读取到了。

第二层：真的发一次请求

我建议第一条测试不要让它改任何文件，只读就够：

请只读取当前文件夹，不要修改、删除或移动任何文件。告诉我这里主要有哪些内容，并列出最重要的 3 个文件。

如果 Codex 正常回复，再回到 AI Code With 后台查看使用记录。只有“Codex 有回复 + 平台出现对应调用记录”两边都能对上，我才会把它算作真正接通。

08｜模型怎么切？别每次都去改一堆配置

Codex 当前支持 `/model` 在会话里选择模型，切完以后可以再用 `/status` 验证。

/model

这里有一个细节：你走的是自定义 provider，所以 `/model` 里最终能出现哪些模型，取决于当前 provider 和平台的模型配置，不要拿官方 OpenAI 列表硬套。

如果你需要的模型没有出现在列表里，最稳妥的做法是先去 AI Code With 看当前模型 ID，再把 `config.toml` 里的 `model = "..."` 改成对应 ID，重开一个 Codex 会话。

真正开始高频用以后，你会发现“一直用同一个模型”并不一定最顺。整理文件、查找信息、改固定格式和复杂分析，对模型能力的要求不一样。AI Code With 在这里的价值也更自然：不是为了多一个网站，而是你想换模型时不用重新搭一整套支付和 Key。

09｜第一次跑通以后，普通人先拿它干这三件事

1. 整理一堆资料

请阅读这个文件夹里的资料，先不要修改原文件。先告诉我你准备怎么组织信息，等我确认后再生成：1. 一份 1500 字以内的摘要；2. 一张信息汇总表；3. 一份 8 页以内的汇报大纲。关键结论标注来源文件名，拿不准的地方不要猜。

2. 清洗表格副本

请检查这个 Excel/CSV，但不要改原文件。先列出重复值、空值、日期格式和异常值问题。我确认后再复制一份副本，在副本里完成清洗，并新增一张“清洗说明”。

3. 陪你写一篇文章或报告

我要写一篇关于「{主题}」的文章。先阅读素材文件夹，不要直接写正文。先给我 3 个标题、一份大纲，以及每一节准备引用哪些资料。我确认后再写第一版初稿。资料里没有依据的结论标记“待补证据”。

这三类任务有一个共同点：先给范围、再给目标、最后给验收标准。你会发现，这比背“万能提示词”重要得多。

10｜一个文件夹反复用，就写一份 AGENTS.md

如果同一个工作目录以后会反复让 Codex 处理，每次都说“别删原文件、先给计划、结果放这里”会很烦。Codex 会读取相关的 AGENTS.md 作为工作说明。

# AGENTS.md## 这个文件夹是做什么的用于市场调研、长文写作和周报整理。## 工作规则- 默认先阅读，再提出计划，不要直接大范围修改。- 不要删除或覆盖“原始资料”目录。- 结论尽量注明来源文件名。- 不确定的信息必须标出来。## 输出位置- 正式结果：/输出- 临时草稿：/草稿- 原始资料：/原始资料（只读）

把它理解成“写给 Codex 的文件夹说明书”就行，不用写成技术文档。

11｜最常见的 7 个问题，我建议按这个顺序排

1. `codex` 提示不是命令

先关闭终端重新打开，再执行 `codex --version`。如果仍然找不到，优先检查 npm 是否真的全局安装成功，以及 npm 全局目录有没有加入 PATH。

2. PowerShell 提示禁止运行脚本

先用 `Get-ExecutionPolicy -List` 看清楚是哪一层策略在生效。个人电脑可以考虑只对 CurrentUser 使用 RemoteSigned；公司电脑受组策略控制时不要硬改。

3. 出现 401

优先查 API Key：有没有复制完整、auth.json 是否放对目录、JSON 有没有引号/逗号问题、Key 是否已经被删除或失效。

4. 出现 404

先查 Base URL。AI Code With 的 Codex CLI 要用平台当前给出的 Codex 专用端点，不要混用通用 API `/v1`。

5. `model not found`

模型名不是你自己起的。回 AI Code With 当前模型列表核对准确的 model ID，空格、大小写、旧模型名都可能导致识别失败。

6. `/status` 正常，但 AI Code With 没有调用记录

`/status` 只能说明配置被 Codex 读到了，不等于请求真的到达平台。再跑一次实际任务；如果仍然没有记录，再查 Key、endpoint 和网络。

7. Windows 明明建了 auth.json，还是读不到

很常见的原因是系统隐藏了扩展名，实际文件叫 `auth.json.txt`。在资源管理器里打开“显示文件扩展名”，确认真实文件名。

12｜最后用这张清单验收，不要靠“感觉能用了”

结语

如果你只是第一次碰 Codex，没必要先研究十几个模型，也没必要一上来就做复杂自动化。先把“安装 → 配置 → 真实调用”这条链跑通。

如果你只想体验，ChatGPT 登录已经够用；如果你后面开始关心 API Key、自定义模型、不同模型之间怎么切，AI Code With 这类统一入口才真正开始有价值。

这篇用到的 AI Code With 入口：AI Code With 官网 ｜ 创建 API Key ｜ Codex（终端）配置文档

我更建议你把这篇教程收藏到“第一次能跑通”为止。等真正开始高频使用以后，再去研究模型分工和成本控制，那时候你会更知道自己到底需要什么。