Codex CLI 使用教程：安装部署与终端命令实战指南

一、引言

亲爱的朋友们，创作不容易，若对您有帮助的话，请点赞收藏加关注哦，您的关注是我持续创作的动力，谢谢大家！有问题请私信或联系邮箱：jasonai.fn@gmail.com

同样是终端里跑 AI 编程助手，很多人卡在第一步——装错包名、认证方式选错、沙箱权限配置不对，导致工具一会儿什么都不敢做、一会儿又权限开太大。OpenAI 的 Codex CLI 作为终端优先（terminal-first）的编码 Agent，安装本身很简单，但真正决定使用体验的是后面这些配置细节：config.toml怎么写、沙箱模式怎么选、AGENTS.md 怎么发挥作用。

本文聚焦工程落地：从安装部署、身份认证，到核心配置文件、终端命令速查、沙箱与审批模式详解，给出一套可以直接照做的使用指南。

二、Codex CLI 是什么

Codex CLI 是 OpenAI 推出的终端优先编码 Agent，直接在命令行里运行，可以读写本地文件、执行 shell 命令、跑测试，核心定位类似"住在你终端里的编程搭档"。它支持交互式 TUI（终端界面）对话模式，也支持非交互模式用于脚本和 CI 场景，同时原生支持 MCP（Model Context Protocol）协议扩展外部工具能力。

三、安装部署

3.1 环境要求

# 检查环境版本node--versionnpm--version

3.2 安装方式

方式一：npm 全局安装（推荐）

npminstall-g@openai/codex

踩坑提醒：包名必须是@openai/codex（带 scope），而不是codex——后者是 2012 年就存在的一个无关 npm 包，装错包会导致命令完全不可用。

方式二：Homebrew（Mac 用户）

brewinstallcodex

方式三：国内网络环境优化

若 npm 安装速度慢，可切换淘宝镜像源：

npminstall-g@openai/codex--registry=https://registry.npmmirror.com

3.3 验证安装

codex--version

能正常输出版本号即安装成功。

3.4 身份认证

Codex CLI 支持两种认证方式：

# 方式一：浏览器登录 ChatGPT 账号（推荐个人用户）codex auth# 方式二：使用 API Key（推荐脚本/CI 场景）exportOPENAI_API_KEY="sk-your-api-key"

两种方式二选一即可，codex auth会打开浏览器完成 OAuth 登录，登录态会保存在本地配置目录，不需要每次都重新认证。

四、快速上手：第一次运行

4.1 进入项目目录启动

cdyour-project codex

首次运行会进入交互式 TUI 界面，直接用自然语言描述需求即可，例如：

> 帮我看看这个项目的目录结构，并总结主要模块

4.2 让 Codex 理解项目上下文：AGENTS.md

在项目根目录创建AGENTS.md文件，写清楚项目背景、技术栈、编码规范，Codex 每次启动都会读取它作为项目指令——作用类似其他编码 Agent 里的项目说明文件：

# AGENTS.md ## 项目说明 这是一个基于 FastAPI 的后端服务，使用 PostgreSQL 数据库。 ## 编码规范 - 使用 Python 类型注解 - 所有接口需要编写对应的 pytest 测试用例 - 禁止直接修改 migrations/ 目录下的历史迁移文件 ## 常用命令 - 运行测试：`pytest tests/` - 启动服务：`uvicorn main:app --reload`

五、核心配置：config.toml

5.1 配置文件位置

Codex CLI 的全局配置文件默认位于：

~/.codex/config.toml

5.2 基础配置示例

# ~/.codex/config.toml # 默认模型 model = "gpt-5.3-codex" # 沙箱模式：控制文件系统与网络访问权限 sandbox_mode = "workspace-write" # 审批策略：控制何时需要人工确认 approval_policy = "on-request"

5.3 Profile：多套配置一键切换

一个config.toml可以声明多个 profile，把模型、沙箱、审批策略打包成一套预设，通过--profile参数或环境变量切换，适合"个人电脑随便跑"和"生产项目严格审批"两种场景来回切换：

[profiles.relaxed] model = "gpt-5.3-codex" sandbox_mode = "workspace-write" approval_policy = "never" [profiles.strict] model = "gpt-5.3-codex" sandbox_mode = "read-only" approval_policy = "untrusted"

# 使用指定 profile 启动codex--profilestrict# 或用环境变量指定exportCODEX_PROFILE=strict codex

5.4 MCP 服务器配置

通过[mcp_servers.NAME]声明外部工具服务器，支持 STDIO 和 HTTP 两种接入方式：

# STDIO 类型 MCP 服务器 [mcp_servers.filesystem] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"] # HTTP 类型 MCP 服务器 [mcp_servers.internal_api] url = "https://internal.example.com/mcp" bearer_token_env_var = "INTERNAL_MCP_TOKEN"

配置完成后，Codex 启动时会自动加载这些外部工具服务器，扩展其可调用的能力边界。

六、终端命令大全

6.1 基础命令

6.2 非交互模式：脚本与 CI 场景

codex exec用于不打开 TUI 界面直接执行任务，运行过程中进度信息输出到 stderr，最终结果输出到 stdout，方便脚本采集：

# 执行一次性任务codexexec"审查这次改动是否存在竞态条件"# 基于上一次 exec 会话继续追问codexexecresume--last"修复你刚才发现的竞态条件问题"

这个模式特别适合接入 CI 流水线，比如在 PR 提交后自动跑一次代码审查。

6.3 TUI 内部斜杠命令

进入交互式界面后，输入/触发内置命令菜单：

七、沙箱与审批模式详解

Codex CLI 的安全模型由两个维度共同决定：沙箱模式控制"能碰什么"，审批策略控制"什么时候要问你"。

7.1 沙箱模式（sandbox_mode）

7.2 审批策略（approval_policy）

实用建议：日常个人项目用workspace-write+on-request组合，兼顾效率和安全；涉及生产环境或重要代码库时，切到read-only+untrusted组合，先看它想做什么，再决定要不要放权。

八、进阶实战

8.1 用 Profile 区分"个人沙盒"与"生产项目"

结合第五章的 profile 配置，实际使用中可以这样划分：

# 个人练习项目，效率优先codex--profilerelaxed# 涉及生产代码的项目，安全优先codex--profilestrict

8.2 自定义斜杠命令

除了内置的斜杠命令，Codex 支持团队或个人自定义可复用的提示词命令，把高频重复的指令（比如"按团队规范生成 PR 描述"）固化成一个命令，输入/加命令名即可触发，不需要每次重新描述完整要求。

8.3 结合 MCP 扩展能力边界

通过 MCP 协议接入的外部工具服务器（如文件系统访问、内部 API），可以让 Codex 在原生文件读写和命令执行能力之外，进一步对接企业内部系统，这是把 Codex 从"通用编码助手"变成"贴合具体工作流的 Agent"的关键手段。

九、常见问题速查表

十、总结

Codex CLI 的安装本身只是几行命令的事，真正拉开使用体验差距的是配置习惯——按项目风险等级用好 profile 和沙箱/审批组合，把 AGENTS.md 写扎实，把高频操作沉淀成自定义命令，才能让它从"一个能跑的工具"变成真正提效的终端搭档。

参考资料：

1. CLI – Codex | OpenAI Developers
2. Quickstart – Codex | OpenAI Developers
3. Configuration Reference – Codex | OpenAI Developers
4. Command line options – Codex CLI | OpenAI Developers
5. Slash commands in Codex CLI | OpenAI Developers
6. Non-interactive mode – Codex | OpenAI Developers
7. @openai/codex - npm