前置条件

1已安装 Node.js 18+（npm 安装方式）或可运行官方安装脚本
2已注册 OpenAI 账号并拥有 ChatGPT 订阅或 OpenAI API Key
3支持 macOS 12+ / Linux / Windows（推荐 WSL2）

腾讯智能体开发平台 ADP

新客首月专属价，最高直降 880 元，构建/分发/治理企业级 Agent

Codex CLI 终端编程指南

Codex CLI 是 OpenAI 在 2025 年开源、2026 年持续升级的终端 AI 编程 Agent（Apache-2.0 协议）。它把 ChatGPT 级别的推理能力直接搬进终端：可以读写文件、执行 Shell 命令、跑测试、搜索代码、抓取网页，并按你的审批策略自主完成完整的工程任务。

Codex CLI 本身就是「终端工具」，用 codex 命令启动；本教程聚焦于如何安装它、并接入合适的 AI 模型供应商（OpenAI 默认，也支持 OpenRouter / Gemini / Ollama / DeepSeek 等）。

前置准备

1. 获取 OpenAI 凭据

Codex 支持两种登录方式，按需选一种：

方式	凭据来源	计费	适合场景
Sign in with ChatGPT	ChatGPT Plus / Pro / Business / Edu / Enterprise 订阅	订阅额度内，无额外按量	个人开发者日常使用
API Key	OpenAI Dashboard（platform.openai.com/api-keys）	按 API 标准费率	CI/CD、编程化调用

警告

⚠️ ~/.codex/auth.json 里的凭据等同密码，不要提交到 Git，也不要分享截图。

2. 系统要求

依赖	版本要求	说明
Node.js	18+	npm 安装方式需要
Git	任意版本	推荐在 Git 仓库内使用，保留回滚能力

操作系统与沙箱机制：

macOS 12+：命令被 Apple Seatbelt（sandbox-exec）包裹，只读 jail + 默认禁网
Linux：默认无沙箱，推荐用 Docker 容器沙箱（仓库内 run_in_container.sh）
Windows：支持 npm/二进制安装，推荐 WSL2 获得完整体验

分步安装指南

方式一：官方安装脚本（推荐，无需 Node.js）

macOS / Linux：

bash

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

Windows（PowerShell）：

powershell

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

脚本自动下载最新版、校验 checksum，并把 codex 加入 PATH。

方式二：npm 安装（已有 Node 环境）

bash

1# 全局安装
2npm install -g @openai/codex
3
4# 升级到最新版
5npm install -g @openai/codex@latest
6
7# 验证安装
8codex --version

中国大陆用户（使用 npm 镜像加速）：

bash

1npm config set registry https://registry.npmmirror.com
2npm install -g @openai/codex

方式三：Homebrew（macOS）

bash

1brew install --cask codex

方式四：二进制直接下载

从 GitHub Releases 下载对应平台的压缩包：

平台	文件名
macOS Apple Silicon	`codex-aarch64-apple-darwin.tar.gz`
macOS x86_64	`codex-x86_64-apple-darwin.tar.gz`
Linux x86_64	`codex-x86_64-unknown-linux-musl.tar.gz`
Linux arm64	`codex-aarch64-unknown-linux-musl.tar.gz`

解压后将可执行文件重命名为 codex 并放入 PATH 即可。

配置 API Key 与登录

bash

1# 启动浏览器 OAuth 授权
2codex login
3
4# 查看登录状态
5codex login status
6
7# 退出登录
8codex logout

凭据缓存在 ~/.codex/auth.json，CLI 与 IDE 扩展共享缓存。

无头设备（服务器 / CI）：

bash

1# 设备码流程（beta，需在设置中启用）
2codex login --device-auth
3
4# 或将本地 auth.json 复制到远程机器
5# 也可通过 SSH 转发 localhost:1455 回调端口完成授权

方法二：API Key 登录（按量计费）

从 OpenAI Dashboard 获取 sk- 开头的 API Key 后：

bash

1# 推荐方式（不暴露密钥到 shell history）
2printenv OPENAI_API_KEY | codex login --with-api-key
3
4# 或直接传入（注意 shell history 泄露风险）
5echo "sk-xxxxx" | codex login --with-api-key

企业 Access Token：

bash

1printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

方法三：环境变量（适合自动化脚本）

bash

1# 临时设置
2export OPENAI_API_KEY="sk-your-api-key-here"
3
4# 持久化（zsh）
5echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.zshrc
6source ~/.zshrc

也可在项目根目录放置 .env，CLI 会自动加载：

OPENAI_API_KEY=your-api-key-here

高级配置：自定义模型供应商

通过 ~/.codex/config.toml 或 --provider 标志切换非 OpenAI 供应商。内置支持：openai（默认）、openrouter、gemini、ollama、mistral、deepseek、xai、groq。

bash

1# 切换为 DeepSeek
2codex --provider deepseek
3
4# 切换为本地 Ollama
5codex --provider ollama

非 OpenAI 供应商需设置对应环境变量：

bash

1export DEEPSEEK_API_KEY="your-deepseek-key"
2export GEMINI_API_KEY="your-gemini-key"

完整 config.toml 示例（接入第三方 OpenAI 兼容端点）：

toml

1model = "gpt-5"
2model_provider = "openai"
3
4# 自定义 OpenAI 兼容端点（如反向代理 / 私有镜像）
5[model_providers.openai]
6base_url = "https://your-custom-endpoint.com/v1"

凭据存储位置控制

toml

1# ~/.codex/config.toml
2# file = 存到 ~/.codex/auth.json
3# keyring = 存到系统凭据库
4# auto = 优先系统凭据库，回退文件
5cli_auth_credentials_store = "keyring"

快速开始

1. 进入项目目录

bash

1cd /path/to/your/project

2. 启动 TUI 交互界面

bash

1codex

3. 一次性带 Prompt 启动

bash

1# 解释当前代码库
2codex "explain this codebase to me"
3
4# 在 Full Auto 模式下创建一个 todo-list 应用
5codex --approval-mode full-auto "create the fanciest todo-list app"

4. 交互要点

在 TUI 界面中你可以：

提问：直接输入自然语言，如"这个模块是做什么的？"
切模式：通过 --approval-mode 选择审批策略
多模态输入：粘贴截图、设计稿，让 Codex 据此实现功能

核心功能与使用模式

三种审批模式

模式	Agent 可自主执行	仍需审批
Suggest（默认）	读取仓库内任意文件	所有文件写入 / 补丁；任意 Shell 命令
Auto Edit	读取文件 + apply-patch 写入	所有 Shell 命令
Full Auto	读写文件 + 执行 Shell（禁网、目录沙箱）	—

切换方式：

bash

1codex --approval-mode suggest
2codex --approval-mode auto-edit
3codex --approval-mode full-auto

警告

💡 Full Auto 下每条命令都在禁网、目录沙箱内执行；若当前目录未被 Git 跟踪，启动时会有警告。

常用命令

bash

1codex                              # 启动交互 TUI
2codex "<prompt>"                   # 带 prompt 启动
3codex --provider deepseek          # 切换供应商
4codex --model gpt-5                # 指定模型
5codex login                        # ChatGPT OAuth 登录
6codex login --with-api-key         # API Key 登录
7codex login status                 # 查看登录状态
8codex logout                       # 退出登录
9codex --version                    # 查看版本

配置文件结构

Codex 首次运行会自动创建配置目录 ~/.codex/（可用环境变量 CODEX_HOME 覆盖）：

text

1~/.codex/
2├── config.toml      # 主配置文件（模型、供应商、审批策略、自定义端点）
3├── auth.json        # 登录凭据缓存（等同密码，勿提交 Git）
4├── sessions/        # 会话历史与检查点
5├── tasks/          # 后台任务存储
6└── audit.log       # 凭证 / 审批 / 提权审计日志

项目级配置：AGENTS.md

在项目根目录放置 AGENTS.md，Codex 会读取其中的项目规范、技术栈说明、编码约定，作为每次任务的上下文。建议提交到 Git，让团队成员共享。

场景应用示例

场景一：代码库理解与重构

text

1你：帮我分析这个项目的架构，找出可以优化的地方
2
3Codex 会：
41. 读取项目核心文件与依赖清单
52. 分析模块边界与调用关系
63. 给出可执行的优化建议

场景二：从设计稿实现功能

text

1你：[粘贴 UI 截图] 按这张设计稿实现一个登录页
2
3Codex 会：
41. 识别截图中的布局与组件
52. 生成对应的 HTML/CSS/React 代码
63. 在 Auto Edit 模式下直接写入文件

场景三：自动化工程任务

text

1你：跑一下测试，修复所有失败的用例
2
3Codex 会（Full Auto 模式）：
41. 执行测试命令（禁网沙箱内）
52. 定位失败用例的根因
63. 修改源码并重跑验证
74. 全程无需人工确认

最佳实践

安全建议

陌生代码库先用 Suggest 模式：只读分析，避免误改
重要操作用 Auto Edit：文件写入自主，但 Shell 命令仍需确认
Full Auto 仅在 Git 仓库内使用：始终保留回滚能力
定期检查审计日志：查看 ~/.codex/audit.log
凭据存进 keyring：cli_auth_credentials_store = "keyring"

性能优化

范围读取：避免一次性读大文件，减少 Token 消耗
合理选模型：简单问答用轻量模型，复杂推理用 gpt-5
多供应商分流：本地模型走 Ollama，推理任务走 OpenAI

故障排查

问题	解决方案
`codex login` 浏览器无响应	改用 API Key 登录，或复制本地 `auth.json` 到远程
401 Unauthorized	Key 过期 / 含空格，重新生成并去除首尾空格
429 Too Many Requests	触发速率限制，降低请求频率或切换供应商
Full Auto 下命令失败	检查是否触发了禁网策略（如 `curl` 被拦截）
Windows 原生报错	改用 WSL2，或确保 PATH 包含 npm 全局 bin 目录
`auth.json` 误提交到 Git	立即 `codex logout` 并在 OpenAI 控制台吊销 Key

bash

1# 查看当前配置与登录状态
2codex login status
3
4# 查看详细日志
5cat ~/.codex/audit.log

扩展与进阶

接入 MCP 服务器

Codex 支持通过 MCP（Model Context Protocol）扩展工具能力，可在 config.toml 中配置 MCP 服务器。

配合 IDE 扩展

Codex 还提供 VS Code 扩展和桌面应用，与 CLI 共享 ~/.codex/ 配置与登录凭据，可在不同形态间无缝切换。

官方资源

🌐 官网：chatgpt.com/codex
📖 官方文档：developers.openai.com/codex
💻 GitHub 仓库：github.com/openai/codex
🔑 获取 API Key：platform.openai.com/api-keys
📦 npm 包：@openai/codex

总结

Codex CLI 把 OpenAI 最强的推理模型能力直接带进终端，通过 Suggest / Auto Edit / Full Auto 三档审批策略，在自主性与安全性之间灵活平衡。无论是代码理解、从设计稿实现功能，还是全自动跑测试修 Bug，它都能成为你终端里的得力编程 Agent。

立即安装，体验「住在终端里的 ChatGPT 级编程智能体」吧！

常见问题

QCodex CLI 和 ChatGPT 网页版有什么区别？

Codex CLI 是运行在终端里的编程 Agent，可以直接读写本地文件、执行 Shell 命令、跑测试，受沙箱保护；ChatGPT 网页版只能对话。两者可共用同一个 ChatGPT 订阅额度。

Q必须有 ChatGPT 订阅才能用吗？

不是。用 `codex login --with-api-key` 走 OpenAI API Key 按量计费也可以，适合 CI/CD 等编程化场景；订阅用户则用 `codex login` 走 OAuth，无额外按量计费。

Q国内网络无法完成 `codex login` 怎么办？

OAuth 回调需要连接 OpenAI 服务器。可改用 API Key 方式，或把本地 `~/.codex/auth.json` 复制到远程机器，也可在 `config.toml` 中配置 OpenAI 兼容的第三方端点。

Q如何切换到其他模型供应商？

用 `--provider` 标志，内置支持 openai（默认）、openrouter、gemini、ollama、mistral、deepseek、xai、groq；或在 `~/.codex/config.toml` 中通过 `model_provider` 配置。

QWindows 原生支持吗？

支持 npm 与二进制安装，但 macOS 12+ 才有 Apple Seatbelt 沙箱；Linux 推荐用 Docker 做沙箱；Windows 建议使用 WSL2 获得更完整体验。

QFull Auto 模式安全吗？

Full Auto 下每条命令都在禁网、目录沙箱内执行，写入仅限当前工作目录与临时文件。若目录未纳入 Git，启动时会有警告提示，建议始终在 Git 仓库内使用。

阿里云推广

读完想动手？新用户首单 8 折上云

服务器 + 大模型 API + 对象存储，新用户首购享 20% 补贴

首单 8 折云服务器大模型 API对象存储

立即领取查看更多优惠

新用户首购享 20% 补贴（8 折）· 本次推广支持本站持续运营

腾讯云推广

腾讯智能体开发平台 ADP

新客首月专属价，最高直降 880 元，构建/分发/治理企业级 Agent

智能体Agent首月直降 880一站式

立即查看查看更多优惠

腾讯云新用户专享 · 本次推广支持本站持续运营

Codex CLI 终端编程指南

前置条件

Codex CLI 终端编程指南

前置准备

1. 获取 OpenAI 凭据

2. 系统要求

分步安装指南

方式一：官方安装脚本（推荐，无需 Node.js）

方式二：npm 安装（已有 Node 环境）

方式三：Homebrew（macOS）

方式四：二进制直接下载

配置 API Key 与登录

方法一：Sign in with ChatGPT（订阅用户默认）

方法二：API Key 登录（按量计费）

方法三：环境变量（适合自动化脚本）

高级配置：自定义模型供应商

凭据存储位置控制

快速开始

1. 进入项目目录

2. 启动 TUI 交互界面

3. 一次性带 Prompt 启动

4. 交互要点

核心功能与使用模式

三种审批模式

常用命令

配置文件结构

项目级配置：AGENTS.md

场景应用示例

场景一：代码库理解与重构

场景二：从设计稿实现功能

场景三：自动化工程任务

最佳实践

安全建议

性能优化

故障排查

扩展与进阶

接入 MCP 服务器

配合 IDE 扩展

官方资源

总结

常见问题

QCodex CLI 和 ChatGPT 网页版有什么区别？

Q必须有 ChatGPT 订阅才能用吗？

Q国内网络无法完成 `codex login` 怎么办？

Q如何切换到其他模型供应商？

QWindows 原生支持吗？

QFull Auto 模式安全吗？

读完想动手？新用户首单 8 折上云

腾讯智能体开发平台 ADP

订阅每日 AI 日报

相关推荐

Gemini CLI 终端编程指南

OpenCode 终端 AI 编程工具使用指南

Aider 终端 AI 编程助手使用指南

如何接入 DeepSeek-TUI 到终端

好物推荐 · 广告合作