codex-advisor

Codex Advisor

概述

当你需要对计划、代码审查进行外部验证，或在棘手问题上陷入困境时，可将 OpenAI 的 Codex CLI 用作第二意见顾问。此技能使用非交互模式（codex exec）进行脚本化／自动化调用。

适用场景

• 开始工作前审查实现计划
• 审查复杂或安全敏感的代码变更
• 权衡取舍显著的架构决策
• 调试卡住超过 30 分钟的问题
• 获取解决问题的其他方案
• 验证对陌生代码库的假设

前置条件

• OpenAI API 密钥或 ChatGPT Plus／Pro／Business 账户
• 已安装 Codex CLI

安装

# Via npm
npm install -g @openai/codex

# Or via Homebrew
brew install --cask codex

身份验证

# Option 1: API key (required for non-interactive mode in CI)
export OPENAI_API_KEY="your-key"

# Option 2: Codex-specific key for CI environments
export CODEX_API_KEY="your-key"

# Option 3: Interactive login (one-time setup)
codex --login

模型选择

根据任务选择合适的模型：

模型	最适合	使用场景
gpt-5.2	通用推理	计划审查、架构问题和非编码任务的默认选择
gpt-5.2-codex	真实世界的软件工程	代码审查、调试和特定于编码的任务
gpt-5.1-codex-max	扩展的多步骤工作流	长时间运行的任务（>10 分钟）、大型迁移和复杂重构
gpt-5.1-codex-mini	注重预算的项目	成本重要时进行简单审查

建议：

• 一般问题从 gpt-5.2 开始
• 任务专门涉及代码时使用 gpt-5.2-codex
• 涉及多个文件或复杂多步骤工作的任务使用 gpt-5.1-codex-max

推理强度级别

为进行彻底分析，始终使用 xhigh 推理：

级别	使用场景
xhigh	默认 - 深度分析、安全审查和架构决策
high	对延迟有要求的复杂分析
medium	简单任务的快速响应
low/none	不建议用于顾问场景

非交互模式

所有命令都使用 codex exec 进行非交互式执行。这对脚本化调用和管道操作至关重要。

关键标志

标志	用途
--json	输出 JSON Lines，便于机器解析
-o <path>	将最终消息保存到文件
-C <path>	设置工作目录（当前代码库使用 -C .）
--full-auto	启用文件修改（谨慎使用）
--sandbox read-only	只读沙盒（默认，最安全）
--sandbox workspace-write	仅允许写入工作区

输出处理

# JSON output for parsing
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  --json "Your prompt" 2>/dev/null

# Save to file
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  -o output.txt "Your prompt"

# Pipe input and capture output
git diff | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review this diff" > review.txt 2>/dev/null

命令参考

计划审查

获取对实现计划的反馈：

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  "Review this implementation plan. Identify potential issues, missing edge cases, security concerns, or better approaches:

<paste plan here>"

审查涉及当前代码库的计划：

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "Review this implementation plan in the context of this codebase. Identify potential issues, conflicts with existing patterns, or better approaches:

<paste plan here>"

代码审查

审查代码变更中的错误、安全问题和改进之处：

# Review staged changes
git diff --staged | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review these changes before commit. Check for:
- Bugs or logic errors
- Security vulnerabilities
- Performance issues
- Missing error handling"

# Review a specific diff
git diff | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review this diff for bugs, security issues, and improvements"

# Review with codebase context
codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" -C . \
  "Review src/auth/login.ts for bugs, security vulnerabilities, and suggest improvements"

解决棘手问题

遇到难题而陷入困境时：

codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" -C . \
  "I'm stuck on this problem: <description>

What I've tried:
1. <attempt 1>
2. <attempt 2>

Error/behavior I'm seeing: <details>

Suggest solutions or debugging approaches."

架构决策

获取有关设计权衡的意见：

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "I need to decide between these approaches for <feature>:

Option A: <description>
Option B: <description>

Given this codebase, which approach is better and why? Consider maintainability, performance, and consistency with existing patterns."

其他方案

想要获得全新视角时：

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "Here's my current approach to <problem>: <description>

What are alternative ways to solve this? What am I missing?"

工作流示例

实现前审查

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "Review this implementation plan for a user authentication system:

1. Add JWT middleware to Express routes
2. Create /auth/login and /auth/register endpoints
3. Store refresh tokens in Redis
4. Add rate limiting on auth endpoints

Identify missing pieces, security concerns, or better approaches."

提交前审查

git diff --staged | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review these changes for a PR. Check for:
- Bugs or logic errors
- Security vulnerabilities
- Performance issues
- Missing error handling
- Test coverage gaps

Provide specific line-by-line feedback."

长时间运行的迁移

对于复杂的多文件重构，使用 gpt-5.1-codex-max：

codex exec -m gpt-5.1-codex-max -c model_reasoning_effort="xhigh" -C . \
  "Help me migrate this codebase from Express to Fastify.

Review the current structure and create a detailed migration plan.
Identify all files that need changes and potential breaking changes."

CI／自动化

在 CI 环境中，使用 CODEX_API_KEY：

# In CI environment
CODEX_API_KEY=${{ secrets.CODEX_API_KEY }} \
  codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  --json "Review this code" > review.json

GitHub Actions 示例

- name: Code Review with Codex
  env:
    CODEX_API_KEY: ${{ secrets.CODEX_API_KEY }}
  run: |
    git diff origin/main...HEAD | codex exec \
      -m gpt-5.2-codex \
      -c model_reasoning_effort="xhigh" \
      -o review.txt \
      "Review this PR diff for bugs and security issues"

最佳实践

何时使用 Codex Advisor

• 影响多个系统的复杂变更
• 安全敏感代码（身份验证、加密、输入验证）
• 对性能要求严格的部分
• 陌生的代码库或编程语言
• 卡住超过 30 分钟时

何时不使用

• 简单、显而易见的变更（拼写错误、格式调整）
• 有明确解决方案的小问题修复
• 需要快速处理低风险变更时
• 模式已确定的重复性任务

获得更好结果的提示

1. 提供上下文：包含相关文件路径、错误消息以及你已尝试的方法
2. 明确具体：提出聚焦的问题，而不是要求“审查所有内容”
3. 使用 -C .：让 Codex 查看你的代码库，以提供结合上下文的建议
4. 选择合适的模型：通用任务使用 gpt-5.2，代码任务使用 gpt-5.2-codex，复杂任务使用 gpt-5.1-codex-max
5. 验证建议：始终结合你的代码库验证 Codex 的建议

安全注意事项

• Codex 会将代码发送到 OpenAI 的服务器进行分析
• 分享专有代码前，请查看你所在组织的政策
• 避免在代码示例中发送敏感凭据、API 密钥或个人身份信息
• 使用具有适当速率限制的 API 密钥来监控用量

故障排除

“stdin 不是终端”

通过管道传输数据时，始终使用 codex exec：

# Wrong - interactive mode doesn't support piped input
git diff | codex -m gpt-5.2 "Review this..."

# Correct - use exec for non-interactive execution
git diff | codex exec -m gpt-5.2 "Review this..."

“找不到命令”

# Check installation
which codex

# Reinstall if needed
npm install -g @openai/codex

身份验证错误

# Re-authenticate interactively
codex --login

# Or set API key
export OPENAI_API_KEY="your-key"
export CODEX_API_KEY="your-key"  # For CI

速率限制

高频使用时，请使用具有适当层级限制的 API 密钥，而不是 ChatGPT 身份验证。

无输出 / 空响应

确保将 stderr 与 stdout 分开处理：

# Capture output properly
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  "Your prompt" 2>/dev/null > output.txt

# Or use -o flag
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  -o output.txt "Your prompt"