← 返回文章目录

Codex / 2026-09-12

Codex 安装与使用教程

面向普通用户的 Codex 桌面端、命令行安装、登录与项目协作指南。

整理 / Whiskey

Codex 是 OpenAI 面向真实工作目录的智能体产品。你可以在桌面端管理多个项目和长任务，也可以在终端里用 Codex CLI 读取代码、修改文件、运行命令并验证结果。

想比较另一种终端智能体？可以阅读 Claude Code 最新版安装教程。

本文更新于 2026 年 9 月。产品入口、套餐权限和可用模型会调整，请以文末 OpenAI 官方文档为准。

本文要点#

适合谁

  • 第一次使用 Codex 桌面端或 CLI 的用户
  • 希望 AI 能直接理解和处理本地项目的人
  • 想区分 ChatGPT 登录与 API Key 计费方式的人

你会完成

  • 选择桌面端或命令行版本
  • 安装并登录 Codex
  • 打开项目，发起第一项可验证的任务
  • 理解本地任务、权限与长任务的基本边界

目录#

  1. 选择桌面端还是 CLI
  2. 安装 Codex
  3. 登录与计费方式
  4. 第一次使用
  5. Codex 的工作方式
  6. 常见问题与安全建议

1. 选择桌面端还是 CLI#

两种入口使用同一类智能体能力，但工作体验不同。

入口更适合特点
Codex 桌面端新手、视觉化管理多个任务项目、文件、终端、浏览器与长任务集中在一个界面
Codex CLI熟悉终端的开发者启动快，适合脚本、远程环境和纯键盘工作流

如果你还不确定，从桌面端开始会更直观；如果你已经习惯在仓库里运行命令，可以直接安装 CLI。

2. 安装 Codex#

桌面端#

从 OpenAI 官方桌面端页面 下载与你系统匹配的版本。安装后打开应用，登录账户，再选择一个本地文件夹作为工作位置。

不要从来源不明的网盘或镜像站安装应用。若公司网络限制官方下载，请让管理员提供经过校验的安装包或部署方式。

Codex CLI#

macOS、Linux 或 WSL 可以使用官方独立安装器：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装完成后验证：

codex --version

然后进入项目并启动：

cd path/to/your-project
codex

如果你在 Windows 上使用 CLI，请优先查看官方 CLI 页面当前显示的 Windows 安装选项，因为 Windows 支持方式可能随版本变化。

3. 登录与计费方式#

Codex 本地客户端通常提供两种个人登录方式：

使用 ChatGPT 账户#

运行 Codex 后选择“使用 ChatGPT 登录”，浏览器会打开授权页面。完成登录后，Codex 的可用范围跟随你的 ChatGPT 工作区、套餐和管理员设置。

CLI 也可以主动发起登录：

codex login

使用 OpenAI API Key#

API Key 方式按 OpenAI Platform 的 API 用量计费，不会使用 ChatGPT 套餐内的使用额度。请从 OpenAI Platform 创建密钥，并通过安全的本地环境变量或标准输入传递，避免把密钥写进仓库。

macOS / Linux 示例：

printenv OPENAI_API_KEY | codex login --with-api-key

在 Windows PowerShell 中，不要把真实密钥直接粘贴到可被记录的脚本或聊天中。先在本机安全设置环境变量，再根据当前官方 CLI 提示完成登录。

检查当前登录状态：

codex login status

退出并清除当前凭据：

codex logout

ChatGPT 订阅和 OpenAI API 是两套计费体系。是否能用某个模型、功能或插件，以你登录后的界面和官方功能表为准，不要依赖网上流传的固定 Token 表格。

4. 第一次使用#

在桌面端打开项目#

  1. 新建一个任务；
  2. 选择项目或本地文件夹；
  3. 在输入框说明目标、限制和完成标准；
  4. 查看 Codex 的文件修改与命令输出；
  5. 在接受结果前检查 diff，并运行项目自己的测试。

一个好的第一次请求可以这样写：

先阅读 AGENTS.md、README 和 package.json。
告诉我这个项目的技术栈、本地启动方式和最重要的三个目录。
本轮只读，不要修改任何文件。

确认上下文正确后，再发实施请求：

为登录表单补充加载状态和错误提示。
保持现有组件风格，不改认证协议。
完成后运行类型检查和相关测试，并列出仍需人工验证的交互。

在 CLI 中工作#

进入项目目录运行 codex。首次启动时选择登录方式，随后直接描述任务。工作目录非常重要：它决定 Codex 优先读取哪些文件，也影响项目指引和历史上下文。

5. Codex 的工作方式#

项目与任务#

把不同代码库分成不同项目，相关工作则保留在同一任务中。这样 Codex 更容易延续上下文，也能减少把一个项目的假设带到另一个项目。

文件、终端与浏览器#

Codex 可以把代码修改、终端输出和浏览器验证放在同一条工作链里。但“构建通过”不等于“页面体验正确”：涉及视觉或交互时，应明确要求浏览器检查；涉及生产环境时，还要单独验证真实域名和线上配置。

长任务#

对于迁移、审计或大量重复工作，先给清楚的目标、允许范围与停止条件。例如：

目标：把 tests/unit 下的旧断言迁移到新 API。
范围：只改 tests/unit，不改产品代码。
完成条件：相关测试和类型检查通过，且没有跳过用例。
遇到需要删除数据、改远端配置或无法判断的产品行为时停止并告诉我。

权限与审查#

Codex 能执行命令并修改文件，因此要像对待一位能操作电脑的协作者一样管理权限：

  • 密钥放在本地且不提交到 Git；
  • 删除、部署、发消息和修改线上数据前确认范围；
  • 保留并审查 diff；
  • 让测试、浏览器检查和真实环境验证各自提供证据。

6. 常见问题与安全建议#

ChatGPT 能用，为什么 API Key 仍然收费？#

因为 ChatGPT 订阅和 OpenAI Platform API 是独立计费。选择 API Key 登录时，Codex 会按 API 标准费率计费。

为什么别人有的功能我没有？#

功能可能受系统、客户端版本、套餐、地区、工作区策略或灰度发布影响。先更新客户端，再查看登录账户和工作区是否正确。

可以接入第三方中转站吗？#

第三方网关会接触你的请求内容和密钥，稳定性、模型真实性、日志策略与售后都不由 OpenAI 保证。确需使用时，使用独立且限额的密钥，不要传入私有仓库、客户数据或生产凭据。

桌面端不稳定怎么办？#

先更新应用并重新打开任务；长时间纯代码工作也可以切换到 CLI。若问题可复现，记录系统版本、客户端版本和最小复现步骤，再对照官方故障排查页面。

官方资料#

— Whiskey