跳到主要内容

Codex CLI 使用说明

Codex CLI 的核心优势是离工作现场很近：你在哪个目录运行，它就围绕哪个项目、资料包或办公流程工作。新人使用时请先学会控制范围、控制权限、控制成本。

基本使用流程​

  1. 打开终端。
  2. 进入项目目录。
  3. 运行 Codex CLI。
  4. 先让它分析项目，不要直接改文件。
  5. 明确任务范围。
  6. 让它修改。
  7. 让它运行最小必要检查。
  8. 查看 git diff。

示例：

cd ~/Projects/my-app
codex

进入后输入：

请阅读当前目录，告诉我主要文件类型、核心内容和你建议先看的文件。先不要修改文件。

新人推荐提示词​

读项目​

请先只读项目，不要修改文件。请告诉我：
1. 项目类型
2. 主要目录
3. 入口文件
4. 本地开发命令
5. 测试或构建命令

修 bug​

我遇到了这个报错：

粘贴报错内容

请先判断原因，列出你会检查哪些文件。确认后再修改。

小范围修改​

请只修改和这个问题直接相关的文件，保持改动最小。修改后运行相关测试或类型检查。

总结改动​

请总结本次改动，包括修改了哪些文件、为什么改、如何验证。

文件修改前要说清楚​

如果你不希望 Codex 大范围修改，直接写：

不要重构无关代码。
不要格式化整个项目。
不要删除文件。
不要提交 git。
不要部署。

如果你允许它自主完成任务，可以写：

请完成这个修复。可以修改必要文件，但保持改动尽量小。完成后运行项目已有检查命令，并报告结果。

远程服务器使用​

在远程服务器上使用 Codex CLI 时，注意：

  1. 不要用 root 账号直接开发，除非团队明确要求。
  2. API Key 只放在当前用户目录。
  3. 不要把 Key 写入项目仓库。
  4. 长任务前先确认余额。
  5. 如果服务器网络受限，先测试 https://ip2.hackstart.org/health。

测试：

curl -fsS https://ip2.hackstart.org/health

如果这个命令失败，先解决服务器网络问题，再排查 Codex。

和普通 OpenAI Compatible CLI 的区别​

Codex CLI 使用 Responses Provider：

https://ip2.hackstart.org

普通 OpenAI Compatible CLI 通常使用：

https://ip2.hackstart.org/v1

例如某些通用 CLI 只支持 OPENAI_BASE_URL：

export OPENAI_BASE_URL="https://ip2.hackstart.org/v1"
export OPENAI_API_KEY="sk-..."

不要把这段直接复制给 Codex CLI 的 Responses Provider 配置。

用量控制​

Codex CLI 容易因为循环排错消耗较多额度。建议：

  • 先让它解释计划，再允许修改。
  • 每轮失败后让它总结失败原因，不要连续重复同一个命令。
  • 长任务前确认模型和额度。
  • 给 CLI Key 单独设置额度上限。
  • 不同机器使用不同 Key。

出问题先查这五项​

1. codex --version 是否正常
2. ~/.codex/config.toml 是否存在
3. base_url 是否为 https://ip2.hackstart.org
4. wire_api 是否为 responses
5. auth.json 或 OPENAI_API_KEY 是否是 HackStart Key

如果这五项都正确，再看模型权限、账户额度和本机网络。