【Codex】Codex CLI 安装、常用命令与沙箱权限配置完全指南

本文从Codex CLI安装、登录、常用命令，到 Sandbox / Approval 权限机制，再到 config.toml 的永久配置，按照实际使用流程进行整理。 适合人群： 第一次使用 Codex CLI，或者已经安装但不知道“命令怎么用、权限怎么配”的用户。 本文目标： 按照「安装 → 登录 → 基础使用 → 常用命令 → 权限理解 → config.toml 固化配置 → 排错」一步一步完成配置。

一、什么是 Codex CLI？

Codex CLI 是运行在终端里的 AI 编程助手，可以把它理解成：

“一个可以直接进入你的项目文件夹、看代码、改代码、运行命令，并按照你的要求完成编程任务的 AI。”

它主要可以做：

• 读取并修改代码文件：理解项目结构，支持跨文件重构
• 执行终端命令：运行测试、git 操作、构建脚本等
• 多步骤自主完成任务：拆解任务并逐步执行，遇到不确定操作时会暂停等待确认
• 支持 MCP（Model Context Protocol）：可以接入第三方工具与上下文

项目开源在 GitHub：https://github.com/openai/codex

二、安装环境要求

三、安装方法

Codex CLI 提供多种安装方式，任选其一即可。

方法一：通过 npm 安装（跨平台，最常用）

重要：如果使用 npm 安装 Codex CLI，需要先安装 Node.js 和 npm。

本节按照 Windows、macOS、Linux 三个平台分别说明 Node.js 的安装方法。安装完成后，请务必使用 node -v 和 npm -v 验证环境。

3.1 Windows 安装

# 确认 Node 版本 >= 22
node -v
npm -v

如果能够正常输出版本号，例如：

v22.x.x
10.x.x

说明 Node.js 和 npm 已经安装成功。

如果提示“node 不是内部或外部命令”，通常是 PATH 没有配置成功。此时可以重新打开 PowerShell。如果仍然无法识别，再检查 Node.js 是否正确加入系统 PATH。

3.2 macOS 安装

同样也是访问 Node.js 官网：https://nodejs.org/，下载 macOS 对应的 LTS 版本，然后运行 .pkg 安装程序。安装完成后打开 Terminal，执行：

node -v
npm -v

如果能够看到版本号，则安装成功。

3.3 Linux 安装

更新软件源，然后安装 Node.js 和 npm，安装完成后验证：

sudo apt update
sudo apt install -y nodejs npm
node -v
npm -v

如果能够正常输出版本号，说明安装完成。

3.4 nvm管理(Linux)

非常推荐使用 nvm 管理 Node.js：不同项目要求不同 Node.js 版本，不用反复卸载、重新安装，而是可以直接切换。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# 命令二选一即可
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

source ~/.bashrc

nvm -v

安装 nvm 后，可以使用以下命令安装和使用/切换，以Node.js 20为例：

# 查看可安装的 Node.js 版本
nvm ls-remote
# 安装 Node.js 20
nvm install 20
# 使用 Node.js 20
nvm use 20
# 设置默认版本
nvm alias default 20

安装完Node.js后，才能npm全局安装Codex CLI：

# 全局安装 Codex CLI
npm install -g @openai/codex
# 验证安装
codex –version

如果在国内访问 npm 官方源较慢，可以切换淘宝镜像：

npm install -g @openai/codex –registry=https://registry.npmmirror.com

方法二：通过 Homebrew 安装（macOS / Linux）

brew install codex
# 或者使用 cask 版本
brew install –cask codex

方法三：下载预编译二进制文件

访问 GitHub Releases 页面：https://github.com/openai/codex/releases，下载对应平台的二进制文件，解压后加入 PATH 环境变量即可。

方法四：从源码构建（适合开发者/贡献者）

git clone https://github.com/openai/codex.git
cd codex/codex-rs

# 安装 Rust 工具链（如未安装）
curl –proto '=https' –tlsv1.2 -sSf https://sh.rustup.rs | sh -s — -y
source "$HOME/.cargo/env"
rustup component add rustfmt
rustup component add clippy

# 构建
cargo build

# 运行
cargo run –bin codex — "explain this codebase to me"

四、登录 Codex

安装成功以后执行：

codex login

一般推荐：

Sign in with ChatGPT

浏览器会打开登录页面，完成 授权即可。

4.1 使用 API Key 登录

如果你使用 API Key，可以：

printenv OPENAI_API_KEY | codex login –with-api-key

注意：旧版 –api-key 参数已废弃，使用它会直接报错并提示改用 –with-api-key，这样密钥就不会残留在 shell 历史记录里。

也可以：

codex login –with-api-key < my_key.txt

不建议直接把 API Key 写在命令行参数中，以免进入 shell 历史记录。

五、常用的 Codex 命令

5.1 codex：进入聊天式编程界面

codex

接下来，你就可以和codex畅所欲言了。

5.2 codex "…"：打开 Codex 后直接给任务

例如：

codex "帮我分析这个项目的目录结构"

它相当于：

打开 Codex + 进入项目 + 直接告诉 AI 第一件事情是什么。

5.3 codex exec "…"：让 Codex 自动执行一个任务

codex exec "统计一下这个项目的代码总行数"

它与普通 codex 最大的区别是：

六、常用参数

6.1 –model / -m

作用：指定使用哪个模型，可以切换想用的模型。

codex -m <model>

6.2 –sandbox / -s

作用：限制 Codex “能动哪些东西”。

例如：

codex -s read-only

意思是：

“你可以看看，但不要修改。”

而：

codex -s workspace-write

意思是：

“你可以修改当前项目里的文件。”

6.3 –ask-for-approval / -a

作用：决定 Codex 做危险操作前要不要问你。

例如：

codex -a on-request

意思是：

“正常操作你自己做；如果需要越权，就先问我。”

6.4 –full-auto

这是日常开发中非常实用的快捷方式：

codex –full-auto

它相当于：

–sandbox workspace-write
–ask-for-approval on-failure

简单理解：

Auto = 让 Codex 在当前项目里尽量自己完成任务，只有遇到沙箱限制导致失败时再询问。

6.5 –cd / -C

如果你不想先：

cd /path/to/project

可以直接：

codex –cd /path/to/project

然后 Codex 就会把这个目录当成当前项目。

七、TUI 里的 / 命令

进入 codex 后，可以使用很多 / 开头的命令。

最推荐记住三个

/init
/status
/diff

尤其是：

/status

当你怀疑“为什么它不能改文件？”、“为什么它一直问我？”时，先看 /status。

八、恢复之前的会话

最近会话列表

codex resume

直接恢复最近一次会话

codex resume –last

根据会话 ID 恢复

codex resume 7f9f9a2e-1b3c-4c7a-9b0e-123456789abc

九、给 Codex 提供图片

例如：

codex -i screenshot.png "根据这张截图实现对应的界面"

多张图片：

codex –image img1.png,img2.jpg "总结这些图表"

交互界面中也可以直接使用：

Ctrl + V

或 macOS：

Cmd + V

粘贴图片。

十、codex exec：自动化模式详解

10.1 只读分析

codex exec "统计一下这个项目的代码总行数"

适合：

分析项目
查看代码
统计信息
代码审查

10.2 自动修改代码

codex exec –full-auto "补充缺失的单元测试并跑通"

适合：

补测试
修 Bug
重构
批量修改

10.3 允许联网并修改文件

codex exec –sandbox danger-full-access "安装依赖并跑一次数据库迁移"

这会明显扩大 Codex 的权限范围。

不要把它当成日常默认配置。

十一、输出结果到文件

把最终回答保存到文件：

codex exec "提取这个项目的信息" -o result.txt

也可以使用：

codex exec "提取这个项目的信息" –output-last-message result.txt

如果需要机器读取，可以使用：

codex exec –json "检查这个项目"

–json 会以 JSON Lines 形式输出事件，适合脚本和 CI/CD 处理。

十二、AGENTS.md：让 Codex “记住”项目规则

AGENTS.md 可以理解成：

写给 Codex 的项目说明书。

例如可以告诉 Codex：

这个项目使用 Python 3.11。
所有代码必须通过 ruff。
测试使用 pytest。
不要修改 data/ 目录。
新增 API 必须补充测试。

Codex 会按照层级读取：

~/.codex/AGENTS.md
↓
项目根目录/AGENTS.md
↓
当前子目录/AGENTS.md

也可以直接进入 Codex 后执行：

/init

让 Codex 帮你生成初始的 AGENTS.md。

十三、沙箱和审批到底是什么？

很多人第一次配置 Codex 时最容易把这两个概念混在一起。

可以用一句话理解：

Sandbox = “Codex 最多能做什么？” Approval = “Codex 做之前需不需要问我？”

也就是说：

Codex 要执行一个操作
│
┌─────────┴─────────┐
↓ ↓
Sandbox 检查 Approval 检查
“能不能做？” “要不要问？”

十四、Sandbox：限制 Codex 能做什么

推荐记忆方式

read-only
= 只看不改

workspace-write
= 可以改当前项目

danger-full-access
= 基本放开

十五、Approval：什么时候需要问你？

十六、最推荐的权限组合

日常开发建议：

workspace-write
+
on-request
↓
可以修改当前项目
+
需要越权时再问你

十七、重点：如何在 config.toml 中永久保存配置？

这一节建议完整照着做。

如果你不想每次启动 Codex 都输入：

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

可以把配置写进：

~/.codex/config.toml

以后启动 Codex 就会自动读取。

第一步：确认配置目录

Linux / macOS：

echo $HOME

通常配置文件位置是：

~/.codex/config.toml

Windows / WSL2 中通常对应：

%USERPROFILE%\\.codex\\config.toml

如果 .codex 目录不存在，可以创建：

mkdir -p ~/.codex

第二步：创建 / 打开 config.toml

最简单的方法：

nano ~/.codex/config.toml

如果你使用 VS Code：

code ~/.codex/config.toml

如果文件不存在，编辑器会创建它。

第三步：写入日常开发配置

如果你的目标是：

让 Codex 可以正常修改当前项目，同时遇到需要额外权限的操作时询问我。

把下面内容完整复制进去：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

保存。

如果使用 nano：

Ctrl + O 保存
Enter 确认文件名
Ctrl + X 退出

第四步：如果希望 workspace-write 可以联网

默认情况下：

workspace-write

并不代表可以联网。

如果你希望 Codex 能够执行：

安装依赖
访问网络资源
下载需要的文件
运行需要联网的命令

可以继续加入：

[sandbox_workspace_write]
network_access = true

因此完整配置为：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

注意

开启：

network_access = true

意味着 Codex 在 workspace-write 沙箱中可以联网。

只有确实需要联网时再开启。

十八、配置完成后怎么确认真的生效？

不要只看 config.toml。

最可靠的方法是启动 Codex 后检查实际状态。

进入项目：

cd /path/to/your/project

启动：

codex

然后执行：

/status

重点查看：

Sandbox
Approval
Model
Working directory

确认是否类似：

Sandbox: workspace-write
Approval: on-request

如果是，就说明配置已经生效。

十九、配置没有生效怎么办？

按照下面顺序排查。

① 先检查文件是否真的存在

ls -la ~/.codex/

应该能看到：

config.toml

② 打开配置文件确认内容

cat ~/.codex/config.toml

应该类似：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

③ 检查有没有 CODEX_HOME

如果设置了：

echo $CODEX_HOME

那么需要确认 Codex 实际使用的配置目录与你编辑的是同一个位置。

④ 检查有没有命令行参数覆盖

例如你的 config.toml 写的是：

sandbox_mode = "workspace-write"

但是启动时又执行：

codex –sandbox read-only

那么命令行参数会覆盖配置文件中的设置。

同理：

codex -a never

也会覆盖审批配置。

⑤ 检查有没有使用 profile

例如：

codex –profile readonly_quiet

那么 profile 中的配置可能会覆盖普通配置。

⑥ 最后使用 /status 确认

进入 Codex：

codex

然后：

/status

以实际状态为准。

二十、推荐：用 Profile 保存多套权限

如果你经常在不同场景之间切换，可以在：

~/.codex/config.toml

里定义不同 profile。

例如：

# ============================
# 默认：日常开发
# ============================

[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# ============================
# 只读：代码分析
# ============================

[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode = "read-only"

然后：

日常开发

codex –profile full_auto

只读分析

codex –profile readonly_quiet

这样就不用反复修改 config.toml。

二十一、临时修改配置：-c

如果只是临时需要某个配置，不想改文件，可以：

codex -c 'sandbox_workspace_write.network_access=true'

例如：

codex \\
-a never \\
-s workspace-write \\
-c 'sandbox_workspace_write.network_access=true' \\
"安装依赖并跑一次数据库迁移"

这种方式适合：

“这次任务临时这样配置，但我不想改变长期默认设置。”

二十二、三套可以直接使用的 config.toml

方案 A：最安全，只读

适合：

第一次使用 Codex、代码审查、只想让 AI 分析项目。

approval_policy = "untrusted"
sandbox_mode = "read-only"

方案 B：日常开发，推荐

适合：

写代码、改 Bug、运行测试、重构项目。

approval_policy = "on-request"
sandbox_mode = "workspace-write"

方案 C：日常开发 + 需要联网

适合：

安装依赖、下载资源、执行需要联网的开发任务。

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

二十三、命令速查表