Codex CLI 入门指南：从安装到你的第一个 AI 编程任务
入门15 分钟阅读

Codex CLI 入门指南：从安装到你的第一个 AI 编程任务

CATAITO Team2026-08-06
你的操作系统:

本教程能教你什么

Codex CLI 是 OpenAI 推出的终端编码智能体。它能检查你的项目、修改文件、运行命令、自动化重复工作——全部在命令行中完成。学完本教程，你将能够在 Windows、macOS 或 Linux 上安装 Codex CLI，完成登录，并运行你的第一个 AI 辅助编程任务。

所需时间： 15–20 分钟

难度： 入门

开始前你需要准备

项目要求
操作系统Windows 10 及以上、macOS 或 Linux
账号ChatGPT 账号（订阅制）或 OpenAI API key（按量付费）
Node.js仅使用 npm 安装方式时需要（18 及以上版本）
终端PowerShell（Windows）、终端（macOS）或 Linux 终端
费用ChatGPT 订阅，或按 API 用量计费

什么是终端？ 终端（也叫命令行）是一个让你输入命令而不是点击按钮的窗口。Windows 上叫 PowerShell，macOS 上叫 终端（Terminal）。本教程中的 codex 命令，就是在这个窗口里输入、然后按回车执行。

什么是 Node.js？ Node.js 是一个免费程序，让你能用 npm 命令安装工具。只有当你选择下面的 npm 安装方式时才需要它。如果你还没有安装，请到 nodejs.org 下载（选择 LTS 长期支持版）。

什么是 API key？ API key 是一串密钥代码，按用量付费时用来识别你的账号。你只需要在 platform.openai.com 的 API keys 页面生成一次。请像保管密码一样保管它，不要告诉任何人。

如何打开终端（手把手教学）

如果你不确定怎么打开终端，请按下面你所在系统的步骤操作。本教程的所有命令都在这个窗口里执行。

Windows — 打开 PowerShell

  1. 1点击屏幕左下角的开始按钮（Windows 图标）。
  2. 2直接输入 PowerShell——不用先点任何东西，直接打字即可。
  3. 3在列表中出现后，点击 Windows PowerShell 或 终端 应用。
  • Windows 11 显示的是终端，Windows 10 显示的是 Windows PowerShell，两个都可以用。
  1. 1如果弹出蓝色的用户账户控制窗口，点击是。

怎么粘贴命令： 在 PowerShell 窗口内任意位置右键单击即可粘贴（或按 Ctrl + V）。

下载与安装

选择你的版本

版本适合谁说明
稳定版（官方安装器）大多数用户经过完整测试，推荐
npm 包已安装 Node.js 的用户更新方便
Homebrew（macOS）使用 Homebrew 的 macOS 用户与应用统一管理

什么是 Homebrew？ Homebrew 是 macOS 的免费软件包管理器。用 brew install 就能安装程序，相当于命令行的应用商店。只有你已经在用 Homebrew 时才选这个选项。

按系统安装

在下方面板选择你的系统，每个标签页包含该系统的完整步骤。

Windows 安装

  1. 1打开 PowerShell：点击开始按钮（Windows 图标），输入 PowerShell，然后点击 Windows PowerShell 或 终端。
  2. 2复制下面的命令，粘贴到 PowerShell 窗口，按回车：
powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
  1. 1等待安装完成。当你能重新输入时，复制并运行下面命令验证安装：
powershell
codex --version

如果看到版本号（例如 v1.x.x），说明安装成功。

升级 Codex（想升级到最新版时，复制并运行这条命令）：

powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

首次登录

  1. 1打开终端，进入你的项目文件夹（把 path/to/your/project 换成你自己的路径）：
bash
cd path/to/your/project
  1. 1启动 Codex：
bash
codex
  1. 1首次运行，选择登录方式：
  • 使用 ChatGPT 登录 — 使用你的 ChatGPT 账号（订阅制）。浏览器会打开授权窗口，登录后凭证会自动返回给 Codex。
  • 使用 API key 登录 — 按提示粘贴你在 platform.openai.com 生成的密钥。
  1. 1登录完成后，你会看到 Codex 的输入提示符，准备开始你的第一个任务。

安装常见错误排查

报错现象原因解决方法
codex: command not found安装目录不在 PATH 中看下面针对你系统的详细修复步骤
npm: command not found未安装 Node.js到 nodejs.org 安装（LTS 版），关闭并重新打开终端，再重试 npm 安装
登录页面无法打开网络限制或代理检查网络，确保能访问 chatgpt.com，再试一次。如果用 VPN 或代理，尝试关闭或切换节点
codex: Permission denied（macOS/Linux）脚本无法写入安装目录打开终端，先运行一次 chmod +x ~/.local/bin/codex，再重新运行安装命令

"codex: command not found" 修复 — Windows：

  1. 1按 Windows 键，输入 环境变量，点击编辑系统环境变量。
  2. 2点击环境变量(N)... 按钮。
  3. 3在下方（系统变量）列表中找到 Path，选中后点击编辑(I)...。
  4. 4点击新建，添加 Codex 的安装目录（默认是 C:\Users\<你的用户名>\.local\bin），然后每个窗口都点确定。
  5. 5完全关闭 PowerShell 再重新打开，然后运行 codex --version。

"codex: command not found" 修复 — macOS/Linux：

  1. 1打开终端，复制并运行这条命令：
bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
  1. 1重新加载配置：
bash
source ~/.zshrc
  1. 1如果你用的是 Bash 而不是 Zsh，把上面两条命令里的 ~/.zshrc 换成 ~/.bashrc。
  2. 2运行 codex --version 确认。

你的第一个任务

第一步：打开项目

进入你想让 Codex 处理的项目文件夹（把路径换成你自己的）：

bash
cd path/to/your/project

第二步：启动 Codex

bash
codex

第三步：提出你的第一个问题

输入下面的请求并按回车：

text
Tell me about this project

Codex 会读取项目文件并解释它的发现。再试试这些：

  • Explain the main function in this file — 解释这个文件的主函数
  • Find the bug in this code — 找出这段代码的 bug
  • Add a comment header to every file — 给每个文件添加注释头

第四步：批准 Codex 要做的操作

当 Codex 想修改文件或运行命令时，它会先请求你的许可，这是正常的。输入 y 按回车表示批准，输入 n 表示拒绝。逐项审查更改，始终掌控你机器上发生的一切。

第五步：退出 Codex

完成后，输入 /exit 按回车，或者连按两次 Ctrl + C。

常用命令速查

命令作用
codex启动交互式会话
codex exec "任务描述"非交互式执行任务（适合脚本和 CI）
codex resume恢复最近的会话
codex --image <文件>在提示中加入截图或图表
codex --search为当前任务开启联网搜索
codex mcp通过 MCP 服务器连接外部工具
codex completion为你的终端生成命令补全
/permissions在会话中调整 Codex 无需询问即可执行的操作
/exit退出 Codex

常见问题

需要付费订阅吗？

你需要 ChatGPT 订阅或 OpenAI API key。免费版 ChatGPT 不包含 Codex CLI 访问权限。当前选项请查看官方定价页。

Codex 必须在 git 仓库里运行吗？

Codex 在 git 项目内效果最佳。如果是从零开始，先创建仓库：

bash
git init

Codex 能运行我的代码吗？

可以，但需要你的许可。Codex 可以在你的机器上执行命令和测试，并且在询问之前总是先展示它要运行什么。你可以用权限设置控制它无需询问就能做什么。

我的代码会发送给 OpenAI 吗？

使用 OpenAI 模型时，你的提示和文件内容会按你账号类型（订阅或 API 组织设置）的数据控制条款由 OpenAI 处理。详情请查阅官方数据控制文档。

下一步做什么

  • 添加项目指引： 在仓库中创建 AGENTS.md 文件，给 Codex 提供关于项目的持久指令。
  • 用脚本自动化： 在 CI 流水线和重复工作流中使用 codex exec。
  • 用 MCP 连接工具： 使用 codex mcp 让 Codex 访问外部数据和服务。
  • 试试 Codex cloud： 把耗时的任务交给云端，稍后回到终端取结果。
#Codex#AI Coding#Terminal#OpenAI
返回教程