跳到主要内容
机场博客
使用教程Codex 教程 AI 工具指南CodexAI 编程工具

Codex CLI 安装与基础使用教程

Codex CLI 使用教程：从 npm 安装、账号登录、基本命令到代理环境变量配置，再到常见错误处理。面向第一次在终端使用 Codex 的开发者，所有命令可直接复制执行。

发布于 约 4 分钟 · 1490 字进阶
Codex CLI 安装与基础使用教程

Codex CLI 是在终端里运行的 AI 编程助手，可以读取项目文件、执行命令、修改代码。这篇教程面向第一次使用它的开发者，按「安装 → 登录 → 基本命令 → 代理配置 → 常见错误」的顺序展开，所有命令都可以直接复制。在中国大陆环境下，最常见的失败原因不是安装本身，而是终端没有走代理，所以代理一节请务必阅读。网络层面的深入分析见 Codex 稳定机场与网络环境分析。

准备工作

项目要求检查命令
Node.js18 或更高版本（推荐 20 LTS）node -v
npm随 Node 安装npm -v
操作系统macOS、Linux、Windows（推荐 WSL）—
账号ChatGPT 账号或 API Key—
网络终端可通过代理访问 OpenAI 服务见下文

如果 Node 版本过低，建议用 nvm 安装 20 LTS，避免与系统 Node 冲突。

第一步：安装

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

看到版本号说明安装成功。如果提示权限错误，不要用 sudo 强行安装，而是把 npm 的全局目录改到用户目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

国内网络下 npm 安装慢，可以先让终端走代理（见第三步），或者临时使用镜像源安装，安装完成后再切回。

第二步：配置代理

这一步在登录之前做。图形客户端的系统代理不会自动作用于终端，需要导出环境变量，端口以客户端实际配置为准：

# macOS / Linux
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
# Windows PowerShell
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"

验证代理是否生效：

curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" https://api.openai.com/v1/models

返回 401（未带密钥，属于正常）且耗时一两秒，说明代理已生效；超时则没有生效。想要永久生效，把 export 行写入 ~/.zshrc 或 ~/.bashrc。另一种方式是在客户端开启 TUN 模式接管所有流量，此时不需要环境变量，但两种方式不要同时使用。

⚠️ 注意

不要把 API Key 写在公开的配置文件或仓库里。如果使用 API Key 登录，建议通过环境变量 OPENAI_API_KEY 在当前会话注入，而不是写入项目文件。

第三步：登录

在项目目录下运行：

codex

首次运行会提示登录方式。选择用 ChatGPT 账号登录时，终端会打开浏览器完成授权；浏览器与终端需要使用同一个代理出口，否则授权回调可能失败。选择 API Key 登录时，按提示粘贴或预先设置环境变量：

export OPENAI_API_KEY=sk-...
codex

登录成功后会进入交互界面，可以直接输入自然语言任务。

第四步：基本命令与用法

用法命令说明
交互模式codex进入对话式界面，逐步下达任务
单次任务codex "为这个项目添加单元测试"直接执行一条指令
指定审批模式codex --ask-for-approval on-request控制何时需要你确认操作
指定模型codex -m <model>使用特定模型
查看帮助codex --help列出全部参数
非交互执行codex exec "..."适合脚本或 CI

审批模式是新手最该了解的参数。默认情况下 Codex 在修改文件或执行命令前会请求确认；熟悉之后可以放宽，但在不熟悉的项目里建议保持确认。

推荐的第一个任务

在一个小项目里试试：

codex "阅读这个项目的 README，总结它的结构，并指出三个可以改进的地方"

这个任务只读不写，可以安全地观察 Codex 的工作方式：它会列出读取的文件、给出分析，然后等待你的下一步指令。

第五步：常见错误对照

错误或现象原因处理
command not found: codex全局 bin 目录不在 PATH把 npm config get prefix 的 bin 目录加入 PATH
EACCES 权限错误npm 全局目录需要 root改用用户目录作为 prefix
登录时浏览器无法打开回调浏览器与终端代理出口不一致统一使用同一节点，重新登录
fetch failed / ETIMEDOUT终端未走代理导出 HTTPS_PROXY 或开启 TUN
任务中途断开节点长连接不稳或并发受限换节点，见网络环境分析
Unsupported Node versionNode 版本过低升级到 20 LTS
输出很慢且整段出现线路缓冲了流式响应换线路类型的节点
速率限制提示账号配额用尽等待重置或切换登录方式

其中 fetch failed 和任务中途断开是网络相关问题，排查思路与 Claude Code 一致，可以对照 Claude 无法连接怎么办中的终端代理一节。延迟和稳定性对终端工具的影响见 AI 工具延迟与稳定性分析。

💡 提示

把代理变量和 OPENAI_API_KEY 写进一个单独的 shell 脚本，例如 ~/.codex-env.sh，需要时 source 一下。这样既不会污染全局环境，也方便在多台机器之间同步。

结论

Codex CLI 的安装只需要一条 npm 命令，真正的门槛在于让终端正确走代理并保持连接稳定。按本文顺序完成安装、代理配置、登录和第一个只读任务，就能开始日常使用。工具版本更新较快，参数变化可以关注AI 工具与客户端更新动态，更多 Codex 使用说明见 Codex 专题页。

总结

  • Codex CLI 通过 npm 全局安装，需要 Node.js 18 以上版本。
  • 终端必须单独配置代理，否则登录和请求都会失败。
  • 常见错误大多是代理未生效、Node 版本过低或权限问题，可按对照表处理。

常见问题

QCodex CLI 支持 Windows 吗？

支持，但官方推荐在 WSL 中运行以获得完整体验。直接在 PowerShell 中也可以安装使用，需要注意代理变量的写法与 bash 不同。

QCodex CLI 需要付费账号吗？

需要登录 ChatGPT 账号并满足对应的订阅要求，或者使用 API Key 按量计费。具体资格以官方说明为准。

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

通常是 npm 全局 bin 目录没有加入 PATH。运行 npm bin -g 或 npm config get prefix 查看路径，把对应的 bin 目录加入环境变量后重开终端。

参考资料与信息来源

  • OpenAI Codex CLI 文档 · 安装方式、命令与参数以官方文档为准，本文基于 2026 年 10 月的版本整理。
CodexCodex CLI安装教程终端AI 编程

相关 AI 工具专题

Codex 专题AI 编程工具 专题

相关文章

返回使用教程