OpenAI Codex 从零安装到跑通第一条命令（CLI / IDE / 授权全流程）

适合人群：想把 OpenAI Codex 真正用起来的前端/后端/全栈开发者
覆盖内容：CLI 安装、IDE 插件、登录授权、环境变量、沙箱、模型切换、基础命令
预计阅读：10 分钟

---

一、Codex 是什么？

Codex 是 OpenAI 推出的命令行编码 Agent，也能通过 VS Code / Cursor 插件在编辑器里使用。

和普通 Chat 最大的区别是：它不只是“回答问题”，而是会：

• 读取你的项目文件
• 改代码、跑命令
• 在沙箱里验证结果
• 必要时继续迭代，直到任务完成

简单说：它更像一个能动手干活的编程助手，而不是只会聊天的问答框。

---

二、安装方式（三选一）

官方支持：macOS、Ubuntu/Debian、Windows WSL2。Windows 原生环境也能用 CLI，但企业场景更推荐 WSL2 或桌面端。

方式 1：npm 全局安装（最常用）

npm install -g @openai/codex

国内网络慢时，先切国内镜像，再安装，通常 1～2 分钟就能装好：

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

方式 2：Homebrew（macOS）

brew install codex

方式 3：桌面端 / 官网入口

可访问：

https://chatgpt.com/codex

从官网进入桌面端或相关入口完成安装。

安装验证

终端执行：

codex

如果能看到欢迎界面，说明安装成功。

---

三、IDE 插件安装（VS Code / Cursor）

Codex 提供原生 VS Code 插件，Cursor 也可直接使用。

在扩展市场搜索：

Codex - OpenAI's coding agent

发布者一般是 openai。

插件核心能力：

1. Pair with Codex：侧边栏对话、改代码、预览变更
2. Delegate to Codex in the cloud：把大任务丢到云端执行并跟踪进度
3. 需要登录 ChatGPT 账号（Plus / Pro / Business / Edu / Enterprise）

---

四、首次登录：三种授权方式

第一次运行 codex 时，会出现登录菜单，通常有：

1. Sign in with ChatGPT
   有 ChatGPT 订阅时最方便，直接走订阅额度。

2. Sign in with Device Code
   浏览器不好登录时的备选方案。

3. Provide your own API key
   走 API 按量计费，适合没有订阅、或想接自建/中转服务的场景。

登录成功后，认证信息会保存在：

~/.codex/auth.json

以后启动一般不用重复登录。

额度参考（会随官方调整）

根据 ChatGPT 套餐，Codex 消息额度大致为：

套餐	大致额度
Plus / Business / Enterprise / Edu	约 30～150 条 / 5 小时
Pro	约 300～1500 条 / 5 小时

更准确信息以官网为准：

https://chatgpt.com/zh-Hans-CN/pricing/

---

五、没有订阅怎么办？配置 API Key

如果你没有 ChatGPT 订阅，可以用 API Key 方式接入。常见路径：

1. OpenAI 官方 API（最标准）
   文档：https://platform.openai.com/docs/quickstart

2. Azure OpenAI（企业常用）

3. 兼容 OpenAI 协议的第三方服务（成本可能更低，但注意合规与稳定性）

Windows 环境变量（PowerShell）

setx OPENAI_BASE_URL "https://api.openai.com/v1"
setx OPENAI_API_KEY "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

注意：

• setx 生效后，需要重启终端 / IDE 才会读到新变量
• 如果你用的是中转服务，把 OPENAI_BASE_URL 改成对应地址即可

macOS / Linux

临时生效：

export OPENAI_BASE_URL='https://api.openai.com/v1'
export OPENAI_API_KEY='sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

想长期生效，写进 ~/.zshrc 或 ~/.bashrc：

echo 'export OPENAI_BASE_URL="https://api.openai.com/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

新版本里，环境变量 OPENAI_BASE_URL 可能提示 deprecated，建议逐步改到 ~/.codex/config.toml 的 openai_base_url。

---

六、进阶配置：config.toml

配置文件路径：

~/.codex/config.toml

示例：

model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
model_provider = "openrouter"

[model_providers.openrouter]
name = "Open Router"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "chat"
query_params = {}

除了 OpenAI，还可以接：

• OpenRouter
• Ollama
• Azure

改完配置后，重新启动：

codex

也可以启动时临时指定模型：

codex -m openai/gpt-5
# 或
codex --model gpt-5.3-codex -c model_reasoning_effort="medium"

---

七、远程服务器怎么登录？

很多服务器没有浏览器，没法直接完成 ChatGPT 登录。推荐做法：

1. 本机先完成登录，生成 ~/.codex/auth.json
2. 用 scp 拷到远程机器

# 本地机器先完成认证，然后复制认证文件
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

# 然后在远程服务器上就可以通过 ChatGPT 认证使用 Codex 了

这个设计很实用，特别适合 SSH 开发场景。

---

八、第一次启动：先把沙箱配好

首次进入时，可能会提示设置沙箱（Sandbox）：

1. Set up default sandbox（需要管理员权限） —— 推荐默认选这个
2. Use non-admin sandbox（更高风险）
3. Quit

沙箱的作用是限制 Agent 对文件和网络的访问，降低“提示词注入 / 误操作”风险。
一般建议：先用默认沙箱，等熟悉后再考虑放开权限。

Windows 相关说明可参考：

https://developers.openai.com/codex/windows

---

九、模型怎么选？怎么切？

交互里输入：

/model

常见可选模型（以你当前版本菜单为准）：

• gpt-5.3-codex：偏 Agent 编程的前沿模型
• gpt-5.4：综合能力更强
• gpt-5.1-codex-max：偏深度推理
• gpt-5.1-codex-mini：更快更便宜，能力稍弱

选择建议：

场景	建议
复杂重构、跨文件改动	高端模型（如 gpt-5.4 / gpt-5.3-codex）
简单生成、解释、文档	mini / nano 更省钱
日常开发默认	medium 推理强度通常够用

---

十、跑通第一条“有用”的命令

1）交互模式

codex

进去后再下任务。

2）启动时直接给任务

codex "fix lint errors"

3）非交互自动化（适合脚本）

codex exec "explain utils.ts"

4）自动执行（沙箱内）

codex --full-auto "create the fanciest todo-list app"

5）高风险模式（不推荐新手）

codex --dangerously-bypass-approvals-and-sandbox "create the fanciest todo-list app"

这个模式会绕过审批和沙箱，只在你非常确定环境安全时再用。

实战示例

codex exec "帮我写一个坦克大战的游戏开发需求文档，要求500字" --skip-git-repo-check

启动后你会看到类似信息：

• 当前模型
• provider
• approval / sandbox 状态
• reasoning effort
• MCP 是否就绪

---

十一、常用提示词模板（直接抄）

codex "Refactor the Dashboard component to React Hooks"
codex "Generate SQL migrations for adding a users table"
codex "Write unit tests for utils/date.ts"
codex "Bulk-rename *.jpeg -> *.jpg with git mv"
codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"
codex "Carefully review this repo, and propose 3 high impact well-scoped PRs"

这些提示词的共同点是：

• 目标明确
• 可验证（测试 / diff / 迁移）
• 范围可控

---

十二、新手最容易踩的坑

1. 装完不重启终端/IDE
   环境变量不生效，最常见。

2. 项目目录不对
   先 cd 到项目根目录再跑 codex，否则 Agent 找不到代码。

3. 一上来就 Full Access
   建议先用默认授权 + 沙箱，熟悉后再放开。

4. 模型选太贵
   简单任务用 mini/nano，复杂任务再上旗舰模型。

5. 忽略废弃警告
   看到 OPENAI_BASE_URL is deprecated，尽快迁移到 config.toml。

---

十三、本文速查清单

# 安装
npm install -g @openai/codex

# 启动
codex

# 指定任务
codex "fix lint errors"

# 非交互
codex exec "explain utils.ts"

# 切模型
/model

# 配置文件
~/.codex/config.toml

# 认证文件
~/.codex/auth.json

---

写在最后

如果你是第一次接触 Codex，建议按这个顺序来：

1. 装 CLI
2. ChatGPT 登录或配 API Key
3. 在一个小项目里跑 codex "解释一下这个项目结构"
4. 再试一次真正的改代码任务（比如修 lint / 写单测）

下一篇：快捷命令、授权模式、AGENTS.md、MCP、Skills 企业级玩法，把 Codex 从“能用”提升到“好用且可控”。