Codex CLI 是 OpenAI 推出的本地终端轻量级编程智能体，可通过自然语言指令协助完成代码生成、调试、文件操作等开发任务，以下为快速上手指南。
一、环境准备与安装
需先确认系统满足要求，再通过推荐方式完成安装。
1.1 系统要求
| 要求 | 官方详细说明 |
|---|---|
| 操作系统 | macOS 12+, Ubuntu 20.04+ / Debian 10+, 或 Windows 11（必须通过 WSL2 运行）。 |
| Node.js | 版本 22 或更高（强烈推荐使用 LTS 版本）。 |
| Git (可选，但推荐) | 版本 2.23+，用于内置的 PR 辅助功能。 |
| 内存 (RAM) | 4 GB 最低要求（8 GB 或更多推荐）。 |
1.2 安装步骤
使用 NPM 安装（推荐）
- 打开终端，执行安装命令：
npm install -g @openai/codex
- 安装完成后，验证是否成功：
codex --version
1.3 登录与认证
安装成功后需完成身份认证，根据 OpenAI 账户类型选择对应登录方式：
方式一：适用于 ChatGPT Plus/Pro/Enterprise 用户
已订阅 ChatGPT 付费计划的用户，推荐此便捷方式：
- 终端执行命令，按提示打开浏览器完成 OAuth 授权：
codex login
- 授权成功后，认证信息自动保存至
~/.codex/auth.json文件； - 检查当前登录状态：
codex login status
方式二：适用于 OpenAI API 用户
拥有 API 密钥的用户，通过设置环境变量认证：
临时设置（仅当前终端会话生效）
export OPENAI_API_KEY="你的API密钥"
永久设置（长期生效，需配置 shell 文件）
- 将密钥写入 shell 配置文件（如
~/.zshrc或~/.bashrc）：
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.zshrc
- 使配置立即生效：
source ~/.zshrc
- 基本使用方式
完成认证后即可使用，核心使用场景如下：
二、常用指令
2.1 启动交互式对话
终端直接输入命令，进入连续对话模式，可反复提出编程需求：
codex
2.2 直接执行单次任务
若仅需处理单一任务，可在命令后直接追加需求：
codex "请帮我创建一个Python函数，用于计算列表的移动平均值"
2.3 常用命令速查
在交互式会话中，以下一些内置命令可以帮助你更好地管理任务：
| 命令 | 功能说明 |
|---|---|
| /status | 查看当前会话的配置、模型和API Token消耗情况。 |
| /model | 切换使用的模型（例如GPT-4或GPT-5）或调整推理强度。 |
| /approvals | 设置Codex在执行文件修改等操作前是否需要你的手动批准。 |
| /init | 在当前目录生成一个 AGENTS.md 文件，用于定义项目特定的配置和规范。 |
2.4 进阶配置（可选）
为提升 Codex 的理解能力与执行效率，推荐进行以下配置：
项目级上下文配置（AGENTS.md）
在项目根目录创建 AGENTS.md 文件，提供持久化上下文信息，例如：
- 项目编码规范
- 依赖关系说明
- 测试命令与流程
三、国内用户
Codex目前需付费，未付费的用户可暂用网关的方式接入体验，基于 Codex 官方配置逻辑，仅需 2 步即可接入：
步骤一：获取密钥
使用Github登录，地址：agentrouter.org/register?af…
注册账号 → 控制台 → 进入「API 令牌」页面 → 生成并复制令牌（格式：sk-xxx）；
步骤二：修改 Codex 配置：
- 先取消原有 OpenAI 认证
codex logout
- 配置环境变量与配置文件
需同时设置环境变量与本地配置文件，步骤如下 （macOS 为例） ：
- 设置环境变量
# 设置环境变量（变量名固定为AGENT_ROUTER_TOKEN，值为上边步骤复制的API令牌）
export AGENT_ROUTER_TOKEN=sk-xxx
# 或者永久设置
echo 'export AGENT_ROUTER_TOKEN="sk-xxx"' >> ~/.zshrc
source ~/.zshrc
- 创建配置文件
新建~/.codex目录（若已存在可跳过）：
mkdir -p ~/.codex
在该目录下创建config.toml文件，添加以下内容：
model = "gpt-5"
model_provider = "openai-chat-completions"
preferred_auth_method = "apikey"
[model_providers.openai-chat-completions]
name = "OpenAI using Chat Completions"
base_url = "https://agentrouter.org/v1"
env_key = "AGENT_ROUTER_TOKEN"
wire_api = "chat"
query_params = {}
在同一目录下创建auth.json文件，添加以下内容（替成你的令牌）：
{
"OPENAI_API_KEY": "sk-xxx"
}
设置完成，输入命令启动：
codex
