Codex 命令行工具 – 自学教程

Codex 命令行工具（Codex CLI）是运行在终端环境下的轻量智能体客户端，无需图形界面，支持交互会话与非交互批处理。它可以直接读写项目文件、执行 Shell、做代码分析、批量处理源码，非常适合本地终端、远程 SSH 服务器、Git Hooks、CI/CD 流水线自动化场景。本文介绍 CLI 的定位差异、平台账号要求、安装、高级命令参数、配置体系、非交互模式、工具集成、调试排错以及最佳实践。

一、核心定位与多客户端差异对比

Codex 存在三种主流客户端形态，能力边界各不相同：

Codex CLI（命令行工具）：终端运行，无GUI；支持文件读写、Shell执行、批量处理、非交互批处理；不支持 Computer Use；擅长脚本、服务器、流水线自动化。
Codex IDE 扩展：嵌入编辑器；侧重编码时局部辅助、选中代码重构、报错修复；无法执行系统Shell。
Codex 桌面应用：全图形界面完整版本；具备 Computer Use、全部斜杆命令、MCP、可视化Diff、长后台任务。

三者可以互补配合：本地编码优先 IDE 扩展；本地整机复杂工程任务用桌面端；远程服务器、脚本自动化、CI流水线使用 CLI。

二、支持平台、安装与账号认证

2.1 支持操作系统

macOS：完整支持，可与桌面端共用账号凭证。
Linux：全功能支持，是SSH远程环境的首选。
Windows：PowerShell可用，强烈推荐WSL环境，原生CMD存在兼容性缺陷。

2.2 安装方式

通过包管理器安装二进制包，安装完成后校验版本：

# npm安装
npm install -g @openai/codex
codex --version

2.3 账号与认证

需要 ChatGPT Pro / Business / Enterprise，免费账号不可用。
本地工作站：执行codex login交互式登录。
服务器/CI环境：使用API密钥环境变量完成认证。
企业管理员可管控CLI可用模型、沙箱、网络策略，通过requirements.toml下发强制配置。

三、CLI核心能力

交互式REPL会话：进入终端对话，读取当前目录上下文，完成代码生成、项目分析、问题排查。
文件读写与批量处理：修改、生成、批量更新源码，补充注释、单元测试，规范化代码风格。
Shell命令辅助执行：根据自然语言生成Shell命令，默认遵循审批策略，高危操作等待人工确认。
项目静态分析：扫描目录，输出项目摘要、依赖梳理、安全与规范问题。
非交互批处理：单次执行任务后直接退出，支持管道输入、JSON结构化输出，适配脚本自动化。
子集斜杆命令：支持/plan、/review、/diff、/status；Computer Use相关指令不可用。

四、CLI高级参数

CLI提供丰富启动参数，可以临时覆盖配置文件设置，优先级：命令行参数 > 环境变量 > 项目配置 > 全局配置。

参数	说明	示例
`--model`	指定调用模型	`--model gpt‑5‑codex`
`--sandbox`	设置沙箱模式	`--sandbox readonly`
`--approval‑policy`	审批策略	`--approval‑policy approve`
`--auto‑edit`	开启自动编辑模式	—
`--full‑auto`	完全自动模式	—
`--quiet / -q`	静默模式，精简输出	—
`--json`	JSON结构化输出，便于程序解析	—
`--context`	指定加载上下文文件	`--context AGENTS.md`
`--system‑prompt`	自定义系统提示词	`--system‑prompt "你是Rust专家"`
`--max‑tokens`	设置最大输出Token	`--max‑tokens 4096`
`--temperature`	模型采样温度	`--temperature 0.2`

常用命令示例：

# 只读模式做安全代码审查
codex --sandbox readonly "审查项目代码安全风险"# 全自动修复lint错误
codex --full-auto --approval-policy approve "修复全部lint告警"
# 指定模型+静默模式重构模块
codex --model gpt‑5‑codex --quiet "重构登录认证模块"
# 自定义系统提示
codex --system-prompt "遵循Go编码规范" "优化工具函数性能"

五、CLI配置文件体系

CLI使用 TOML格式配置，分为全局配置与项目本地配置，项目配置优先级高于用户全局配置。

5.1 全局配置 `~/.codex/config.toml`

model = "gpt‑5‑codex"
approval_policy = "ask"
sandbox_mode = "workspace‑write"

[output]
format = "text"
color = true
progress = true

[context]
auto_compact = true
max_files = 50
exclude = ["node_modules/", ".git/", "dist/"]

[sandbox]
blocked_paths = [".env", "secrets/"]

blocked_paths = [“.env”, “secrets/”]

5.2 项目配置 `.codex/config.toml`（放在项目根目录）

model = "deepseek‑coder"
approval_policy = "ask"

[context]
include = ["src/**/*.ts", "tests/**/*.ts"]

同时项目目录下的AGENTS.md会被自动加载，统一编码规范、保护文件清单，保证CLI、IDE扩展、桌面端行为一致。

六、非交互模式（自动化核心）

非交互模式执行完任务直接退出，没有交互式会话，用于脚本、管道、CI流水线。

6.1 单次任务执行

# 静默模式完成代码修改
codex --quiet "为 app.py 添加完整类型注解"# 将输出重定向保存到文档
codex --quiet "生成项目API文档" > api‑docs.md

6.2 管道stdin输入

# 传入文本让Codex分析
echo "请解释下面逻辑" | codex --quiet# 读取日志文件分析报错根因
cat error.log | codex --quiet "分析错误，定位根因"
# 结合git diff做变更审查
git diff | codex --quiet "审查本次代码变更的安全问题"

6.3 JSON结构化输出

--json输出机器可读JSON，字段包含task、status、files_modified、files_read、result，方便脚本解析：

codex --json "找出项目内全部TODO注释" > todos.json

注意：默认ask审批策略在管道环境会卡住等待交互确认；全自动流水线需要显式配置--approval‑policy approve或--full‑auto。

七、与开发工具集成

7.1 Git Hooks（pre‑commit）

在提交代码前自动做Lint修复或者代码审查：

#!/bin/bash
# .git/hooks/pre‑commit
codex --full-auto --quiet "修复所有lint错误"
git add -A

7.2 GitHub Actions CI/CD

- name: 代码安全审查
  run: |
    codex --sandbox readonly --quiet "审查PR变更的安全性与性能问题"

7.3 Makefile集成

lint-fix:
	codex --full-auto "修复项目全部lint告警"test-gen:
	codex --full-auto "为src目录生成单元测试"
review:
	codex --sandbox readonly "审查当前代码变更"

八、日志、调试与排错

# 详细verbose模式输出完整执行过程
codex --verbose "复现并修复bug"# 将任务日志保存至文件
codex --log‑file codex.log "修复接口异常"
# 查看审计记录，记录所有文件与命令操作
cat ~/.codex/audit.log

常见问题

CLI和桌面App能否同时操作同一个项目？
可以同时运行，但不建议同时修改同一套代码，容易产生文件冲突；不同项目可以并行使用。
非交互模式是否全部功能可用？
文件、代码处理可用；Computer Use这类图形交互功能不可用。
如何限制任务最大执行时长？
借助系统timeout命令控制超时：timeout 300 codex --quiet "任务描述"。

九、权限安全策略

CLI具备直接调用系统Shell的能力，风险高于IDE扩展，完整继承Codex沙箱‑审批双层安全模型。

沙箱：支持read‑only、workspace‑write；danger‑full‑access需要显式开启，生产环境不建议使用。
审批策略：默认ask(on‑request)高危操作人工确认；自动化流水线才使用approve。
企业场景：管理员通过requirements.toml强制锁定沙箱、审批策略，用户命令行参数无法覆盖强制配置。
审计：全部文件变更、Shell调用会写入审计日志，可用于事后追溯。
功能限制：CLI没有屏幕捕获，完全无法使用Computer Use电脑操控。

十、最佳实践与使用建议

远程服务器、SSH、CI流水线优先使用CLI；本地编码优先IDE扩展；本地整机复杂自动化任务使用桌面端。
高危批量操作，优先使用--sandbox readonly做方案评审，确认后再开启写入权限。
自动化脚本最小权限原则，仅开放任务必需目录，限制可用Shell命令。
项目维护AGENTS.md，统一约束，保证多客户端行为一致。
全自动模式下的代码、脚本输出，仍然需要人工复核，不可直接上线。
Windows环境优先WSL，规避原生CMD兼容性问题。

十一、功能限制

无图形界面，不支持Computer Use整机操控。
仅支持部分斜杆命令，桌面端UI专属能力不可用。
交互式复杂多轮探索任务体验弱于桌面端，更适合批处理与脚本自动化。
Windows原生CMD存在兼容性缺陷，推荐WSL。

十二、总结

Codex CLI是面向终端、服务器与自动化流水线的轻量客户端。依托丰富命令参数、多层配置体系、非交互模式，可以和Git Hooks、Makefile、GitHub Actions等工具深度集成，实现代码审查、批量修改、测试生成等工程自动化。CLI与IDE扩展、桌面应用形成完整互补，在远程无图形环境发挥不可替代的价值。使用时需要重视沙箱、审批策略与审计日志，在自动化效率与系统安全之间取得平衡。