OpenAI Codex CLI¶

项目介绍

Codex CLI is a coding agent from OpenAI that runs locally on your computer.

Codex CLI 是一个来自 OpenAI 的编码代理，可在您的计算机上本地运行。

官方主页：https://chatgpt.com/codex
项目主页：https://github.com/openai/codex
安装方法：见本页下方教程

效果演示¶

特性¶

功能分类	特性
终端式编码助手	Codex CLI 是一个基于终端的交互式编码助理，用于在命令行中编辑代码、生成补丁并运行命令。
工具驱动架构	提供 `apply_patch`、`shell`、`update_plan`、`multi_tool_use` 等工具，用于对仓库文件和操作进行可控修改。
原子补丁编辑	使用专门的补丁格式通过 `apply_patch` 原子地添加/更新/删除文件，便于审计与回滚。
沙箱与审批	支持沙箱策略（如 `workspace-write`、`read-only`）和审批模式（`on-request`、`on-failure`、`never`），控制写入与网络访问权限。
计划追踪	`update_plan` 用于列出步骤并跟踪状态，要求始终只有一个 `in_progress` 步骤以保持明确进度。
交互规范	在重要操作前发送简短前导说明，保持语气友好、简洁并提供进度更新。
安全约束	遵循严格规则（不随意更改无关文件、不添加版权头、不执行破坏性命令），需要用户批准敏感操作。
测试与格式化	推荐在修改后运行相关测试与格式化工具，但不负责修复与当前任务无关的问题。
输出与风格	最终输出遵循 CLI 渲染规范（例如 `**` 标题、反引号表示路径/命令），保持可扫描的简洁结构。
并行执行	支持通过 `multi_tool_use.parallel` 并行运行多个工具以提升效率。

AI 模型配置方法¶

参数修改¶

Api Key：前往ZetaTechs API获取。

请求地址格式：

主站

https://api.zetatechs.com/v1

企业站

https://ent.zetatechs.com/v1

Windows 端图文指引¶

1.安装 Node.js 环境¶

Codex CLI 需要 Node.js 环境才能运行。

Node.js 环境安装步骤

打开浏览器访问 https://nodejs.org/
点击 "LTS" 版本进行下载（推荐长期支持版本）
下载完成后双击 .msi 文件
按照安装向导完成安装，保持默认设置即可

Windows 注意事项

建议使用 PowerShell 而不是 CMD
如果遇到权限问题，尝试以管理员身份运行
某些杀毒软件可能会误报，需要添加白名单

验证安装是否成功

安装完成后，打开 PowerShell 或 CMD，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功

2.安装 Git Bash¶

Windows 注意事项

Windows 环境下需要使用 Git Bash 安装 Codex CLI。安装完成后，环境变量设置和使用 Codex CLI 仍然在普通的 PowerShell 或 CMD 中进行。

下载并安装 Git for Windows

访问 https://git-scm.com/downloads/win
点击 "Download for Windows" 下载安装包
运行下载的 .exe 安装文件
在安装过程中保持默认设置，直接点击 "Next" 完成安装

验证 Git Bash 安装

安装完成后，打开 Git Bash，输入以下命令验证：

git --version

如果显示版本号，说明安装成功

3.安装 Codex CLI¶

安装 Codex CLI

打开 Git Bash（重要：不要使用 PowerShell），运行以下命令：

# 在 Git Bash 中全局安装 Codex CLI
npm install -g @openai/codex

这个命令会从 npm 官方仓库下载并安装最新版本的 Codex CLI。

重要提醒

必须在 Git Bash 中运行，不要在 PowerShell 中运行
如果遇到权限问题，可以尝试在 Git Bash 中使用 sudo 命令

验证 Codex CLI 安装

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。

4.修改环境变量¶

修改 Codex CLI 配置文件

为了让 Codex CLI 连接到你的中转服务，需要设置多个环境变量：

OPENAI_API_KEY：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OPENAI_BASE_URL：https://api.zetatechs.com/v1

修改默认模型 (可选)

Codex CLI 默认使用 gpt-5 (medium)，如需要使用其他模型作为默认参数可修改配置文件。

资源浏览器打开路径%USERPROFILE%\.codex自动跳转到配置文件目录。

如：C:\Users\Administrator\.codex

注意：如果没有这个文件夹，可以按下方教程，启动 Codex CLI 运行一次，授权 Codex 编辑文件夹权限，该操作会自动生成配置文件。

config.toml

编辑config.toml（若无该文件，则新建。若已有该文件，可删除内部自动生成的内容。）

model = "gpt-5-mini-high"

5.开始使用 Codex CLI¶

现在你可以开始使用 Codex CLI 了！

启动 Codex CLI

直接启动 Codex CLI:

# 启动 Codex CLI
codex

在特定项目中使用:

# 进入你的项目目录
cd C:\path\to\your\project

# 启动 Codex CLI
codex

临时修改使用模型：

# 启动 Codex CLI 前使用
codex -c model="gpt-5-high"

Enter 启动 Codex CLI

注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

6.Windows 常见问题解决¶

安装时提示 "permission denied" 错误

这通常是权限问题，尝试以下解决方法：

以管理员身份运行PowerShell
或者配置npm使用用户目录：npm config set prefix %APPDATA%\npm

PowerShell 执行策略错误

如果遇到执行策略限制，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

MacOS 端图文指引¶

1.安装 Homebrew (已安装请跳过)¶

Homebrew 是 macOS（或 Linux）缺失的软件包的管理器。

官网：https://brew.sh

安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2.安装 Node.js 环境¶

Node.js 环境安装步骤

更新 Homebrew

brew update

安装 Node.js

brew install node

macOS 注意事项

如果遇到权限问题，可能需要使用sudo
首次运行可能需要在系统偏好设置中允许
建议使用Terminal或iTerm2

验证安装是否成功

安装完成后，打开终端，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功

3.安装 Codex CLI¶

安装 Codex CLI

打开终端，运行以下命令：

# 全局安装 Codex CLI
npm install -g @openai/codex

如果遇到权限问题，可以使用 sudo：

sudo npm install -g @openai/codex

验证 Codex CLI 安装

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。

4.设置环境变量¶

为了让 Codex CLI 连接到你的中转服务，需要修改默认接口地址、API Key 和默认模型 (可选)：

确定您使用的 Shell

echo $SHELL

如果输出是/bin/bash，您使用的是Bash Shell，配置文件是~/.bashrc。

如果输出是/bin/zsh，您使用的是Zsh Shell，配置文件是~/.zshrc。

修改环境变量 | zsh

输入命令：

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc

echo 'export OPENAI_BASE_URL="https://api.zetatechs.com/v1"' >> ~/.zshrc

应用修改：

source ~/.zshrc

修改环境变量 | bash

输入命令：

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.bash_profile

echo 'export OPENAI_BASE_URL="https://api.zetatechs.com/v1"' >> ~/.bash_profile

应用修改：

source ~/.bashrc

修改默认模型

Codex CLI 默认使用 gpt-5 (medium)，如需要使用其他模型作为默认参数可修改配置文件。

cat > ~/.codex/config.toml << 'EOF'
model = "gpt-5-mini-high"
EOF

5.开始使用 Codex CLI¶

现在你可以开始使用 Codex CLI 了！

启动 Codex CLI

直接启动 Codex CLI:

# 启动 Codex CLI
codex

在特定项目中使用:

# 进入你的项目目录
cd /path/to/your/project

# 启动 Codex CLI
codex

临时修改使用模型：

# 启动 Codex CLI 前使用
codex -c model="gpt-5-high"

Enter 启动 Codex CLI

注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

6.macOS 常见问题解决¶

安装时提示权限错误

尝试以下解决方法：

使用sudo安装：sudo npm install -g @openai/codex
或者配置npm使用用户目录：npm config set prefix ~/.npm-global

macOS 安全设置阻止运行

如果系统阻止运行 Codex CLI：

打开"系统偏好设置" → "安全性与隐私"
点击"仍要打开"或"允许"
或者在Terminal中运行：sudo spctl --master-disable

环境变量不生效

检查以下几点：

确认修改了正确的配置文件（.zshrc或.bash_profile）
重新启动Terminal
验证设置：echo $ANTHROPIC_BASE_URL

Linux 端图文指引¶

1.安装 Node.js 环境¶

Codex CLI 需要 Node.js 环境才能运行。

Node.js 环境安装步骤

添加 NodeSource 仓库

sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

安装 Node.js

sudo apt-get install -y nodejs

Linux 注意事项

某些发行版可能需要安装额外的依赖
如果遇到权限问题，使用 sudo
确保你的用户在 npm 的全局目录有写权限

验证安装是否成功

安装完成后，打开终端，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功

2.安装 Codex CLI¶

安装 Codex CLI

打开终端，运行以下命令：

# 全局安装 Codex CLI
npm install -g @openai/codex

如果遇到权限问题，可以使用 sudo：

sudo npm install -g @openai/codex

验证 Codex CLI 安装

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。

3.修改配置文件¶

为了让 Codex CLI 连接到你的中转服务，需要修改默认接口地址、API Key 和默认模型 (可选)：

确定您使用的 Shell

echo $SHELL

如果输出是/bin/bash，您使用的是Bash Shell，配置文件是~/.bashrc。

如果输出是/bin/zsh，您使用的是Zsh Shell，配置文件是~/.zshrc。

修改环境变量 | bash

输入命令：

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.bash_profile

echo 'export OPENAI_BASE_URL="https://api.zetatechs.com/v1"' >> ~/.bash_profile

应用修改：

source ~/.bashrc

修改环境变量 | zsh

输入命令：

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc

echo 'export OPENAI_BASE_URL="https://api.zetatechs.com/v1"' >> ~/.zshrc

应用修改：

source ~/.zshrc

4.开始使用 Codex CLI¶

现在你可以开始使用 Codex CLI 了！

启动 Codex CLI

直接启动 Codex CLI:

# 启动 Codex CLI
codex

在特定项目中使用:

# 进入你的项目目录
cd /path/to/your/project

# 启动 Codex CLI
codex

临时修改使用模型：

# 启动 Codex CLI 前使用
codex -c model="gpt-5-high"

Enter 启动 Codex CLI

注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

5.Linux 常见问题解决¶

安装时提示权限错误

尝试以下解决方法：

使用sudo安装：sudo npm install -g @openai/codex
或者配置npm使用用户目录：npm config set prefix ~/.npm-global
然后添加到PATH：export PATH=~/.npm-global/bin:$PATH

缺少依赖库

某些 Linux 发行版需要安装额外依赖：

# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"

环境变量不生效

检查以下几点：

确认修改了正确的配置文件（.bashrc或.zshrc）
重新启动终端或运行source ~/.bashrc
验证设置：echo $ANTHROPIC_BASE_URL

使用技巧¶

欢迎投稿

启动 Codex CLI 命令(自动运行) | by 布鲁斯甽

codex -c model="gpt-5-medium" -s danger-full-access -a never   # 完全访问系统，执行命令永不问 （完全放飞模式，极其危险）

codex -c model="gpt-5-medium" -s danger-full-access -a on-failure   # 完全访问系统，全自动跑，失败时才问批准 （能快速迭代但不完全失控）

codex -c model="gpt-5-medium" -s danger-full-access -a on-request  # 完全访问系统，模型自己决定何时问 （交给AI判断）

codex -c model="gpt-5-medium" -s workspace-write -a on-failure   # 允许写当前工作区，全自动跑，失败时才问批准 （低摩擦的自动执行模式，适合快速跑任务）

codex -c model="gpt-5-medium" -s workspace-write -a on-request   # 允许写当前工作区，模型自己决定何时问 （常规默认模式）