Codex CLI安装与使用：终端命令、Windows配置与国内模型接入全流程【2026年8月】

最后更新：2026-08-12

国内 Codex 与多模型 API 开发工具推荐

国内进行 Codex、代码、脚本或多模型 API 开发时，可以按任务选择以下第三方工具：

• 💻 Codex/编程训练（ZeoGPT）：zeogpt.comCodex、代码、长文本和开发任务。
• 🔌 API/脚本接入（ZeoAPI）：zeoapi.com多模型 API 接入、脚本和原型测试。

以上均为邀请链接。ZeoGPT 与 ZeoAPI 均为第三方服务，不是相关模型厂商的官方网站或官方产品；所列型号与能力来自平台标称，具体功能与可用性以登录后的实际页面为准。请勿上传账号密码、API Key、合同或其他敏感资料。

本站为独立教程博客，并非 OpenAI 或 Codex 官方网站，也不提供 AI 模型对话功能。文中所有安装与运行都在你自己的电脑或官方产品里完成。

先给结论：Codex CLI 三步就能跑通

Codex CLI 是 OpenAI 官方的终端编程代理，安装到本地后可以在你指定的目录里读代码、改文件、跑命令。要跑通它，核心就三步：装（npm install -g @openai/codex 或官方安装包）、登（用 ChatGPT 账号或 API Key）、跑（进项目目录输入 codex）。Windows 用户额外要处理 PATH 生效，国内用户则可以在 config.toml 里配置 base_url 与 wire_api 改走兼容网关。

先完成安装并确认 PATH 生效，再登录并进入目标项目运行 Codex CLI。

这篇是终端 CLI 的完整上手链路，专注装好、登进去、跑第一个项目。如果你要的是图形客户端下载，看 Codex 官网入口与下载指南；要的是版本升级与卸载，看 Codex CLI 怎么更新。

Codex CLI 是什么：和桌面 App、IDE 插件怎么选

Codex 不是单一产品，而是 OpenAI 一组编程入口的统称。根据 OpenAI Codex CLI 官方文档，Codex CLI 是可以直接从终端运行的开源编程代理，能读取、修改并运行你所选目录里的代码。它的开源仓库地址是 github.com/openai/codex。

同一套 Codex 能力有三种主要形态，用途不同：

形态	运行位置	适合谁	典型场景
Codex CLI	终端 / PowerShell / WSL	习惯命令行、要脚本化的人	本地项目分析、批量改代码、跑构建
Codex 桌面 App	图形界面	想点选项目、看任务列表的人	并行管理多个项目与会话
IDE 插件	VS Code 等编辑器内	边写边用的人	在编辑器里选中代码直接对话

如果你更习惯在编辑器里用，参考 Codex VS Code 插件与 API 使用指南；桌面版和沙箱能力看 Codex Windows 桌面版与 Sandbox 指南。本文只讲 CLI。

安装前准备：Node.js/npm 版本与系统核对

用 npm 方式安装前，先确认本机环境，避免装到一半报错：

node -v
npm -v

准备清单：

• Node.js：装较新的 LTS 版本更稳妥，太旧的 Node 可能不被支持。
• npm：随 Node 一起安装，确认能正常输出版本号。
• 操作系统：官方支持 macOS、Linux，以及 Windows（原生或通过 WSL）。具体最低运行环境以官方仓库 README 为准。
• 磁盘与网络：留出安装空间，登录环节需要能打开浏览器完成授权。

如果不想装 Node 环境，可以跳过 npm，直接用官方独立安装包，见下一节的两种方式。

Windows 安装：npm 全局安装与官方安装包两种方式

Windows 用户是这篇的重点。两种方式二选一即可，装出来都是同一个 codex 命令。

方式一，npm 全局安装（已有 Node 环境时最快）：

npm install -g @openai/codex
codex --version

方式二，官方安装包/脚本（不想碰 Node 时用）：到 github.com/openai/codex 的 Releases 页面下载对应 Windows 的安装包，或按 README 提供的安装脚本执行。安装完同样用 codex --version 验证。

Windows 三个高频卡点：

1. 终端选择混乱。PowerShell 可以直接用；WSL 里则相当于在 Linux 环境操作，路径和权限都按 Linux 走。二选一，别混着来。
2. PATH 未生效。npm 全局安装后如果提示 codex 不是可识别命令，多半是全局 bin 目录没进 PATH，或者没重开终端。
3. 项目目录权限不清。不确定 Codex 能改哪些文件时，先在小项目里试，别一上来对着生产仓库跑。

关于 PATH 与 ChatGPT 登录的更细排错，看 OpenAI Codex CLI：Windows 安装、ChatGPT 登录、PATH 与首次运行排错。

macOS / Linux 安装与升级方式

macOS 常见两种：

## 方式一：npm
npm install -g @openai/codex

## 方式二：Homebrew
brew install codex

Linux 通常走 npm 全局安装，或使用官方 Releases 提供的对应架构安装包。装完统一验证：

codex --version

升级思路：npm 装的用 npm install -g @openai/codex@latest 更新，Homebrew 装的用 brew upgrade codex。版本检查、升级失败与降级卸载的完整流程，单独整理在 Codex CLI 怎么更新，这里不重复展开。

登录方式对比：ChatGPT 账号 vs API Key

Codex CLI 当前支持两种登录方式，按你的账号情况选：

登录方式	怎么用	适合谁	注意点
ChatGPT 账号登录	运行 codex 后按提示在浏览器完成授权	已有包含 Codex 的 ChatGPT 计划的人	需要浏览器能正常打开授权页
API Key	在配置里填入 OpenAI API Key	想按调用计费、脚本化接入的人	Key 属敏感信息，别写进提示词或提交到仓库

具体哪些 ChatGPT 计划包含 Codex、额度如何，以登录后的官方页面为准，本文不做承诺。如果你要基于 API Key 做更细的配置和 MCP 接入，看 Codex API Key、config.toml 与 MCP 配置指南。

常用命令与斜杠命令速查

装好登进去后，基础操作就这些：

codex              # 在当前目录启动交互式会话
codex --version    # 查看版本
codex --help       # 查看命令与参数

进入会话后，常用斜杠命令用于管理上下文和审查（以你当前版本 /help 输出为准）：

• 会话管理：新建、清空当前上下文
• 恢复会话：继续上一次未完成的任务
• 代码审查：让 Codex 说明它打算改哪些文件、改动理由
• 审批控制：切换只读、需确认、可写等模式

命令会随版本变化，最可靠的做法是进会话后先敲一次帮助命令看当前支持项。完整的斜杠命令清单，参考 Codex CLI 常用命令大全。

国内网络与模型接入：base_url、wire_api 与国产模型

Codex CLI 从设计上支持自定义网关。核心是编辑配置文件 config.toml（通常在用户目录下的 .codex 目录里），把请求改向 OpenAI 兼容网关：

## 示意，具体字段与写法以官方文档和你使用的网关为准
[model_providers.custom]
base_url = "https://你的兼容网关地址/v1"
wire_api = "responses"   # 或 chat，取决于网关支持的协议

要点说明：

• base_url 指向兼容 OpenAI 协议的网关地址。
• wire_api 决定用哪种接口协议，填错会导致请求格式不匹配。
• 接入国产模型（如 DeepSeek 系列）时，需要目标服务提供 OpenAI 兼容接口，再把 base_url 指过去。
• 配置前，先用官方默认方式确认 CLI 本身能跑通，再改网关，出问题时好定位。

base_url / wire_api 是否在你当前版本仍然有效，以官方仓库文档为准。接入 DeepSeek 与国产模型的完整思路，看 Codex 接入 DeepSeek 与国内模型指南。如果你只是想在国内高频跑中文编程任务、不想折腾网关，也可以直接用第三方平台 ZeoGPT 处理 Codex 类任务，用 ZeoAPI 做多模型 API 接入——两者都是第三方服务，不是官方产品，能力以登录后页面为准。

首次运行项目：权限、沙箱与审批

第一次在真实项目里跑，别急着让它大改。推荐这个顺序：

1. 进入项目根目录，先运行 codex 启动会话。
2. 让它只读分析，不改文件：先摸清项目结构。
3. 指定一个很小的目标，比如改一个函数、加一段测试。
4. 要求它先说明打算改哪些文件、为什么。
5. 确认后再放开写入，执行改动。
6. 跑构建或测试，人工 review 后进下一步。

只读分析提示词示例：

请先阅读当前项目结构，不要修改任何文件。
输出：主要目录作用、构建命令、以及新增一篇文档需要改哪些文件。

确认无误后再执行改动：

现在只新增一篇文章文件，并把链接加入目录顶部。
不要覆盖已有文件，完成后运行构建命令验证。

Codex 默认带审批与沙箱机制，会在你授权的范围内操作。首次运行时保持较严格的审批模式，熟悉后再放宽。跨平台的环境要求与验证方法，见 Codex 跨平台安装环境指南。

常见报错排查清单

先按错误现象定位 PATH、授权、网络或 wire_api，每次只调整一个变量。

装完跑不起来时，先对照这几条：

• 输入 codex 提示找不到命令：PATH 未生效。运行 npm config get prefix 找到全局 bin 目录，确认它在 PATH 里，然后重开终端。
• 登录授权反复循环：浏览器没完成授权，或授权页被网络拦截。换用能正常打开授权页的环境，或改用 API Key 方式。
• 请求超时 / 连接失败：网络到默认接口不通。检查网络，或按上文配置兼容网关的 base_url。
• wire_api 相关报错：协议填错。核对网关支持的是 responses 还是 chat，改成匹配的值。
• npm 全局安装报权限错误：Windows 用管理员终端重试；类 Unix 系统避免用 sudo 强装，优先修正 npm 全局目录权限。
• 版本过旧导致命令不存在：先 codex --version 看版本，再按官方 Releases 升级。

安全提示：只用官方渠道

避坑清单：

• 只从 github.com/openai/codex 和 openai.com/codex 等官方渠道获取安装包，不要用第三方下载站的所谓“完整版”“绿色版”“破解版”。
• API Key、账号密码不要写进提示词，也不要提交到代码仓库。
• 首次在陌生项目里跑保持只读，确认审批模式后再放开写入。
• 配置国产模型网关时，先在测试目录验证，别直接对生产仓库操作。

事实边界：本文中的包名、命令和配置字段基于官方仓库与文档整理，版本号、可用登录计划、base_url/wire_api 的具体行为都会随 Codex 版本更新变化，请以 openai/codex 仓库 和 官方 CLI 文档 的当前内容为准。本站是独立教程博客，不代表 OpenAI 官方立场。

常见问题

Codex CLI 官方 npm 包名是什么？

目前官方在 GitHub 仓库 openai/codex 中提供的全局安装命令为 npm install -g @openai/codex，包名为 @openai/codex。最新版本号会随 Releases 更新，安装前建议先到官方仓库 Releases 页面核对。

Codex CLI 一定要用 npm 装吗？

不是。官方同时提供 npm 全局安装和独立安装包/脚本，macOS 也可通过 Homebrew 安装。没有 Node 环境或不想引入 npm 的用户可以直接用官方安装包，两种方式装出来的都是同一个 codex 命令。

Codex CLI 支持哪些登录方式？

当前支持两种：一是用包含 Codex 的 ChatGPT 计划账号登录（运行 codex 后按提示在浏览器完成授权），二是配置 OpenAI API Key。具体可用的计划与额度以登录后的官方页面为准。

国内网络下 Codex CLI 怎么接入模型？

Codex CLI 支持在 config.toml 里自定义 base_url 与 wire_api，把请求指向 OpenAI 兼容网关或国产模型的兼容接口。是否生效以你使用的网关文档和 Codex 当前版本为准，配置前建议先用官方默认方式确认 CLI 本身能跑通。

安装完输入 codex 提示找不到命令怎么办？

多数是 PATH 未生效。npm 全局目录没加入环境变量，或安装后没重开终端都会导致这个问题。先运行 npm config get prefix 找到全局 bin 目录，确认它在 PATH 中，然后关闭并重新打开终端。

Codex CLI 会不会自动改我的代码？

会在你授权的目录内读取和修改文件、运行命令，但默认带审批与沙箱机制。首次在陌生项目里运行时建议先让它只读分析，确认审批模式后再逐步放开写入权限。

相关文章

• Codex 官网入口与下载指南 2026
• OpenAI Codex CLI：Windows 安装、ChatGPT 登录、PATH 与首次运行排错
• Codex CLI 常用命令大全
• Codex 接入 DeepSeek 与国内模型指南 2026
• Codex API Key、config.toml 与 MCP 配置指南 2026