Codex使用说明 - 技术栈

📘 OpenAI Codex 使用说明书（最详细版）

1-pnpm install -g @openai/codex 当前我是按照这个方式进行安装的
2-GLM配置参考链接：https://docs.bigmodel.cn/cn/coding-plan/tool/codex
3-常用斜杠命令（交互模式内）

命令	作用
`/init`	扫描项目并生成 AGENTS.md（项目说明/规则文件）
`/status`	查看当前会话状态、模型、沙箱模式
`/model`	切换模型（如 `gpt-5-codex` 等）
`/approvals`	切换审批模式
`/diff`	查看当前改动 diff
`/review`	对当前改动/提交进行代码审查
`/compact`	压缩上下文历史，节省 token
`/clear` / `new`	清空上下文开启新会话
`/mcp`	查看/管理已连接的 MCP 服务器
`/quit`	退出

4-Codex 强调安全性，通过沙箱+审批机制控制 Agent 权限：

模式	说明
Read Only（只读）	默认。只能读文件，任何写入/联网都需你批准
Auto（自动）	可在工作区内自动读写、执行命令；网络访问需批准
Full Access（完全访问）	无沙箱，自动执行一切（有风险，慎用）

bash 复制代码

# 命令行指定模式
codex --sandbox workspace-write "运行测试并修复"
codex --full-auto "..."        # 等价于 workspace-write + 自动审批
codex --dangerously-bypass-approvals-and-sandbox "..."  # 完全放开（高危）

5-最佳实践建议

1. 先 /init 生成 AGENTS.md------项目上下文越清晰，输出越准
1. 任务要具体：明确目标文件、验收标准（"运行 npm test 确保通过"）
1. 善用 --full-auto 处理机械性任务，只读模式用于代码解读
1. 每次会话聚焦一个任务 ，用 /compact 控制上下文膨胀
1. 重要改动前用 /diff 审查，配合 Git 分支工作
1. 把重复性说明写进 AGENTS.md，而不是每次重复输入

一、Codex 是什么

Codex 是 OpenAI 推出的 AI 编程智能体，它不只是补全代码，而是一个能自主完成任务的 Agent------可以阅读仓库、编辑文件、运行命令、执行测试、审查代码。它有多种使用形态：

形态	说明
Codex CLI	终端里的本地编码智能体，跨平台（macOS/Linux/Windows）
IDE 扩展	VS Code / Cursor 等编辑器插件，在编辑器内直接调用
Codex 云端版	在 ChatGPT 网页（chatgpt.com/codex）中云端运行任务，连接 GitHub 仓库
Codex App（macOS）	2026 年 2 月发布的桌面应用，可并行管理多个 Agent 工作流

二、安装

1. 前置要求

已安装 Node.js 22+（npm 方式需要）
操作系统：macOS 12+、Ubuntu 20.04+/Debian 10+、Windows 11（推荐 WSL）

2. 安装方式

bash 复制代码

# 方式一：npm 全局安装（最常用）
npm install -g @openai/codex
pnpm install -g @openai/codex    当前我是按照这个方式进行安装的

# 方式二：macOS 用 Homebrew
brew install --cask codex

# 方式三：直接下载二进制
# 访问 https://github.com/openai/codex/releases 下载对应平台二进制

3. 登录认证

当前我是配置的GLM，GLM配置参考链接：https://docs.bigmodel.cn/cn/coding-plan/tool/codex

bash 复制代码

codex login

支持 ChatGPT 账号登录（Plus / Pro / Team / Enterprise 套餐均含额度）
或设置环境变量使用 API Key ：export OPENAI_API_KEY="sk-..."
检查登录状态：codex login status

三、基本使用

1. 交互模式（REPL）

bash 复制代码

cd 你的项目目录
codex              # 启动交互式会话
codex "修复这个登录Bug"   # 带初始提示启动

2. 非交互模式（脚本/CI 用）

bash 复制代码

codex exec "解释这个仓库的结构"
codex exec --full-auto "运行测试并修复失败的用例"

3. 恢复历史会话

bash 复制代码

codex resume              # 选择恢复某次会话
codex resume --last       # 直接恢复最近一次会话

四、常用斜杠命令（交互模式内）

命令	作用
`/init`	扫描项目并生成 AGENTS.md（项目说明/规则文件）
`/status`	查看当前会话状态、模型、沙箱模式
`/model`	切换模型（如 `gpt-5-codex` 等）
`/approvals`	切换审批模式
`/diff`	查看当前改动 diff
`/review`	对当前改动/提交进行代码审查
`/compact`	压缩上下文历史，节省 token
`/clear` / `new`	清空上下文开启新会话
`/mcp`	查看/管理已连接的 MCP 服务器
`/quit`	退出

五、审批模式与沙箱

Codex 强调安全性，通过沙箱+审批机制控制 Agent 权限：

模式	说明
Read Only（只读）	默认。只能读文件，任何写入/联网都需你批准
Auto（自动）	可在工作区内自动读写、执行命令；网络访问需批准
Full Access（完全访问）	无沙箱，自动执行一切（有风险，慎用）

bash 复制代码

# 命令行指定模式
codex --sandbox workspace-write "运行测试并修复"
codex --full-auto "..."        # 等价于 workspace-write + 自动审批
codex --dangerously-bypass-approvals-and-sandbox "..."  # 完全放开（高危）

六、配置文件（~/.codex/config.toml）

可自定义默认模型、审批策略等：

toml 复制代码

model = "gpt-5-codex"
approval_policy = "on-request"   # untrusted / on-failure / on-request / never
sandbox_mode = "workspace-write"

[projects."/path/to/project"]
trust_level = "trusted"

七、AGENTS.md（项目指令文件）

在项目根目录放置 AGENTS.md，Codex 启动时会自动读取作为上下文，相当于项目级"系统提示词"：

markdown 复制代码

# AGENTS.md
- 本项目使用 pnpm，不用 npm
- 提交信息遵循 Conventional Commits
- 测试命令：pnpm test

也可以创建全局规则：~/.codex/AGENTS.md（对所有项目生效），团队可用符号链接共享。

八、MCP（Model Context Protocol）扩展

Codex 支持接入 MCP 服务器扩展能力（如数据库、浏览器工具等）：

bash 复制代码

# 添加 MCP 服务器
codex mcp add my-server -- npx -y some-mcp-server

# 查看已配置的 MCP
codex mcp list

九、IDE 扩展（VS Code）

在 VS Code 扩展市场搜索 "Codex -- OpenAI's coding agent" 安装
使用 ChatGPT 账号登录
在侧边栏打开 Codex 面板，可直接对话、审查 diff、应用改动
IDE 扩展与 CLI 共享账号和配置，云端任务也能在 IDE 中查看

十、云端 Codex（chatgpt.com/codex）

用 ChatGPT 账号登录 chatgpt.com/codex
连接你的 GitHub 仓库
下达任务（如"给这个函数写测试"），Codex 在云端容器中运行
完成后生成 diff/PR，你审查后合并
优点：不占本地资源、可多任务并行、跨设备接力

十一、最佳实践建议

先 /init 生成 AGENTS.md------项目上下文越清晰，输出越准
任务要具体：明确目标文件、验收标准（"运行 npm test 确保通过"）
善用 --full-auto 处理机械性任务，只读模式用于代码解读
每次会话聚焦一个任务 ，用 /compact 控制上下文膨胀
重要改动前用 /diff 审查，配合 Git 分支工作
把重复性说明写进 AGENTS.md，而不是每次重复输入

十二、常见问题

问题	解决
安装后 `codex` 命令找不到	检查 npm 全局 bin 目录是否在 PATH
登录失败	尝试 `codex login` 重新认证，或检查代理设置
沙箱报错（Linux）	确认内核支持 Landlock/seccomp，或用 Docker 运行
Windows 原生支持	推荐在 WSL2 中使用，最新版已实验性支持 PowerShell

十三、参考链接

GitHub 仓库：https://github.com/openai/codex
官方入门文档：https://learn.chatgpt.com/docs/codex/cli
OpenAI 开发者文档：https://developers.openai.com/codex
命令速查表：https://kingy.ai/news/openai-codex-command-guide
Codex App 发布公告：https://openai.com/index/introducing-the-codex-app

注：Codex 迭代较快，具体命令细节建议以 codex --help 和官方文档为最准。