Codex 新手完全指南：从安装到第一次让 AI 改代码

发布日期：2026年7月13日

Codex CLI 是 OpenAI 推出的开源终端编程智能体，用 Rust 编写，可在本地终端中读取、修改并运行代码，目前 GitHub 星标已超 9.7 万、Fork 数超 1.4 万，最新版本迭代至 rust-v0.144.3（截至 2026 年 7 月）。它与 Claude Code 定位相似，核心差异在于原生支持 ChatGPT Plus/Pro/Business/Edu/Enterprise 订阅直接登录使用，无需单独付费 API。本文按照安装、登录、首次运行、安全模式、常用命令五个环节，说明一个从未用过 AI 编程智能体的开发者该怎样上手 Codex，并指出新手最容易踩的权限配置坑。

Codex CLI 是什么，和 Codex App、Codex Web 有什么区别

Codex 有三种形态，新手容易混淆：

Codex CLI：运行在本地终端，本文的主角，也是最适合理解 Codex 工作方式的入口——能直接看到它读了哪些文件、跑了哪些命令、改了哪些 diff
Codex App：桌面客户端，运行 codex app 或访问 chatgpt.com/codex 的应用页启动，与 CLI 共享同一份配置文件
Codex Web（云端版）：托管在 chatgpt.com/codex，任务在云端沙箱运行，适合后台并行处理多个独立任务

三者共享认证和大部分配置，新手从 CLI 入手最容易理解底层逻辑。

第一步：安装

macOS / Linux 用**安装脚本：

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

Windows 用 PowerShell：

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

也可以用包管理器安装：

# npm 方式
npm install -g @openai/codex

# Homebrew 方式（macOS）
brew install --cask codex

安装完成后运行 codex doctor 检查环境是否正常，再运行 codex --version 确认版本号。

第二步：登录

Codex 支持三种登录方式，新手直接选第一种即可：

登录方式	适用场景
ChatGPT 账号登录	新手首选，覆盖日常开发、IDE、App、云端任务
API Key	CI/CD、脚本自动化，按 API 用量计费
Access Token	企业受控自动化场景

运行 codex login，若在无浏览器环境下可用 codex login --device-auth。登录凭据会缓存在 ~/.codex/auth.json，这份文件要像密码一样保护，绝对不要提交到代码仓库。

第三步：第一次运行，别一上来就重构整个项目

新手最常犯的错误是直接让 Codex 处理复杂任务。正确的第一次运行步骤：

进入一个 Git 仓库，先执行 git status 确认工作区干净
运行 codex 启动交互界面
先让它只解释项目结构，明确要求不修改文件：codex "解释这个代码库的主要模块，不要修改文件"
再给一个小的具体修改任务，要求跑测试或 lint
用 git diff 审查它改了什么，确认无误后再提交

其他常用启动方式：

codex --cd /path/to/project   # 指定工作目录启动
codex exec "fix the CI failure"  # 非交互式单次执行
codex resume --last            # 恢复上一次会话

第四步：理解安全模式，这是新手最容易踩的坑

Codex 用两层机制控制风险：Sandbox（沙箱）决定它技术上能做什么，Approval Policy（批准策略）决定什么时候必须先问你。

Sandbox 三种模式：

模式	能力范围	适用场景
read-only	只能读文件、解释代码，不能修改	了解陌生项目
workspace-write	工作区内可读写、运行常规命令，越界操作需批准	日常开发首选
danger-full-access	取消大部分边界，含更广的文件和网络访问	仅限可信环境短时使用

新手推荐的组合是：

codex --sandbox workspace-write --ask-for-approval on-request

Codex 默认关闭命令级网络访问，需要联网或写出工作区范围时会主动触发审批流程询问你，不会静默执行危险操作。

第五步：常用斜杠命令速查

交互模式下可以用斜杠命令控制会话和查看功能：

会话管理：/clear 清空对话、/compact 压缩历史、/new 新建会话、/resume 恢复会话
模型与权限：/model 切换模型、/permissions 设置审批模式、/plan 进入只规划不执行模式
代码相关：/review 代码审查、/diff 显示 Git 差异、/init 生成 AGENTS.md、/status 查看会话状态
工具扩展：/mcp 查看 MCP 工具、/skills 浏览技能包、/plugins 管理插件

AGENTS.md：让 Codex 记住项目规矩

AGENTS.md 是放在仓库根目录的说明文件，用来存放项目约定、测试命令、目录规则、PR 要求等。不需要一开始就写得面面俱到——比较合理的做法是：当 Codex 反复忘记同一条规则时，再把它沉淀进 AGENTS.md。放在根目录后 Codex 每次启动都会读取，深层目录也可以放 AGENTS.md 或 AGENTS.override.md 来覆盖上层规则，运行 /init 命令可以让 Codex 自动生成初版。

想接入第三方模型该注意什么

Codex 原生支持 OpenAI 自家模型、Ollama、LM Studio、Amazon Bedrock 等，也可以自定义接入其他大模型服务。需要注意的是，Codex 使用 Responses API 而非行业更常见的 Chat Completions API，只提供 Chat Completions 端点的第三方模型服务无法直接接入，需要额外的协议转换层。对于新手，如果只是想低成本体验多种模型效果，可以优先选择本身就兼容 Responses 协议的聚合服务，省去自建转换层的麻烦；国内可直接访问的 AI 编程工具配置教程通常会给出对应的接入步骤。

常见问题

Q：Codex 和 Claude Code 应该选哪个？
两者定位相似，都是终端 AI 编程智能体。Codex 的优势是原生绑定 ChatGPT 订阅，不用单独申请 API Key 就能用；具体选择更多取决于你已有的订阅和对模型效果的偏好，不妨都试用后再定。

Q：第一次用 Codex 会不会把我的代码改坏？
按照本文步骤，先用 read-only 模式了解项目，再用 workspace-write 配合 on-request 审批策略执行小任务，每一步改动都可以用 git diff 审查，不会出现未经确认就大规模改代码的情况。

Q：danger-full-access 到底有多危险，什么时候能用？
它会取消大部分文件和网络访问限制，只应该在完全隔离、可随时重置的环境（如临时容器或沙箱虚拟机）里短暂使用，日常开发不建议开启。

Q：AGENTS.md 是必须要写的吗？
不是必须的。新手可以先不写，等发现 Codex 反复忘记某条项目规则（比如"这个仓库测试要用 pytest -x"）时再补充进去，比一开始就写一份完整文档更实际。

Q：Codex 能不能接入其他大模型，不只用 OpenAI 自家的？
可以，Codex 原生支持部分本地和第三方模型provider，但受限于它只支持 Responses API 协议，接入前需确认目标服务是否提供该协议的兼容端点。

结语

Codex CLI 上手的核心逻辑并不复杂：安装、用 ChatGPT 账号登录、从只读模式的小任务开始、理解 sandbox 与审批策略这两层安全边界，剩下的斜杠命令都是锦上添花。据 GitHub 公开数据，截至 2026 年 7 月该项目星标已超 9.7 万，说明其社区活跃度和迭代速度都很快，建议关注**文档以获取最新变更。