CX-12 Codex CLI 辅助指南：App 用户什么时候需要终端

交互模式：codex
  -> 适合终端里长期协作、排查、使用 slash commands
 
无头模式：codex exec
  -> 适合 CI、脚本、一次性报告、结构化输出
 
专项命令：codex review / codex mcp / codex plugin marketplace
  -> 适合审查、工具配置和插件来源管理

codex --help
codex
codex app
codex exec "summarize this repo"
codex review
codex mcp list
codex features
codex plugin marketplace list

codex --version
codex doctor
codex remote-control --help
codex plugin marketplace list

codex --ask-for-approval on-request --sandbox workspace-write
codex --ask-for-approval never --sandbox read-only

codex --dangerously-bypass-approvals-and-sandbox

codex exec "read the repo and summarize test commands"

codex exec "Read package.json and AGENTS.md. Report the install, test, lint, and build commands. Do not modify files."

codex exec \
  --output-schema ./schemas/audit-result.schema.json \
  "Read package.json and return only schema-valid JSON with scripts, packageManager, and risky lifecycle hooks."

codex review

/keymap debug

/goal Finish the docs link audit. Stop when every broken local link has either been fixed or listed with a reason.

codex mcp --help
codex
# 在交互界面输入 /plugins

codex remote-control --help
codex remote-control

codex exec "Read package.json, README, and AGENTS.md. Report install, test, lint, and build commands. Do not modify files."

codex exec \
  --output-schema ./schemas/repo-commands.schema.json \
  "Return install, test, lint, build commands as schema-valid JSON. Do not modify files."

codex plugin marketplace list
codex plugin marketplace upgrade

codex exec \
  --sandbox read-only \
  --ask-for-approval never \
  "Review the current PR diff for correctness, security risks, and missing tests. Do not modify files. Return findings and verification gaps."

codex mcp list
codex mcp --help
codex doctor

codex exec \
  --sandbox read-only \
  --ask-for-approval never \
  "Review the current diff for bugs, security risks, and missing tests. Do not modify files."

codex doctor
codex --help
codex --profile read-only

codex
# 在 TUI 输入 /plugins
 
codex plugin marketplace list
codex plugin marketplace upgrade

codex doctor

- 本地安装。
- 配置。
- 认证。
- 运行时。
- Git。
- terminal。
- app-server。
- thread inventory。

下面是 `codex doctor` 的输出。
请帮我判断：
1. 哪些是必须处理的问题
2. 哪些只是提示
3. 先修哪一个
4. 是否影响 App、CLI、MCP 或认证
不要让我粘贴任何密钥。

codex exec "summarize the repository structure and list the top 5 risky areas"

npm test 2>&1 |
  codex exec "summarize the failing tests and propose the smallest likely fix"

codex exec --json "summarize the repo structure" | jq

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

codex exec resume SESSION_ID

codex exec --sandbox read-only "summarize this repo"
codex exec --sandbox workspace-write "update README install instructions"
codex exec --sandbox danger-full-access "run this in an isolated container only"

- 用 Codex GitHub Action。
- 或只在单次 `codex exec` 调用环境里提供。
- 不让 untrusted code 和 key 处在同一进程环境。

The CI workflow failed for this commit.
Run the targeted test command if available.
Identify the smallest likely fix.
Do not refactor unrelated files.
If the failure cannot be reproduced, summarize the missing evidence.

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp --help

/mcp

1. 看 config.toml 是否有 server。
2. 看 server command 是否能本机启动。
3. 看 token 环境变量是否存在。
4. 看 App/CLI 是否同一 CODEX_HOME。
5. 新开线程确认能力是否刷新。

/plugins

请帮我排查本地 Codex plugin marketplace。
我会提供 marketplace.json 和目录结构。
请检查：
1. source.path 是否相对 marketplace root
2. 插件是否有 `.codex-plugin/plugin.json`
3. 是否需要重启 Codex
4. 是否应该从 App Plugins 页面或 `/plugins` 查看

codex review

codex review "Focus on correctness, security, behavior regressions, and missing tests."

- app-server 是本地 App 相关的服务入口。
- remote-control 帮助确保本地 app-server daemon 以远程控制支持运行。
- 这不是新手第一天要用的功能。
- 涉及网络监听和 token 时，要格外注意安全边界。

我在排查 Codex remote-control / app-server。
请先解释当前命令会打开什么本地服务、监听范围是什么、是否需要认证 token。
不要建议我暴露到公网。

%USERPROFILE%\.codex

~/.codex

export CODEX_HOME=/mnt/c/Users/<you>/.codex

Get-ChildItem
where.exe git
$env:CODEX_HOME

ls
which git
echo "$CODEX_HOME"

codex doctor > codex-doctor.txt

请读取 codex-doctor.txt。
帮我判断哪些问题会影响 Codex App 使用。
不要修改配置，先给排查顺序。

git log --oneline -20 |
  codex exec "group these commits into release note categories" \
  -o release-summary.md

请审查 release-summary.md 是否夸大了用户影响。
只改措辞，不改变 commit 事实。

codex mcp add context7 -- npx -y @upstash/context7-mcp

请确认当前线程能否使用文档 MCP。
如果不能，帮我排查配置刷新、项目作用域和工具可见性。

gh run view 123456 --log > ci.log

cat ci.log |
  codex exec "Summarize the CI failure. Identify the first failing job, likely root cause, and next three debugging steps. Do not propose broad refactors." \
  -o ci-summary.md

请读取 ci-summary.md。
帮我判断这个失败适合：
1. 本地 App 修
2. Cloud 修
3. 只在 CI 配置里修
4. 需要人工调查
不要修改文件。

CLI:
  抓取 CI 日志并生成摘要
 
App:
  判断任务范围，整理 handoff
 
Cloud:
  修复可复现失败
 
App:
  Review diff，准备 PR 描述

gh run view 123456 --log |
  codex exec "Turn this CI log into a concise handoff for a repair task." \
  -o cloud-handoff.md

请读取 cloud-handoff.md。
把它改写成适合 Codex Cloud 的任务 prompt。
要求范围小、禁止无关重构、包含建议验证命令。

codex exec --sandbox danger-full-access "fix everything"

codex exec --sandbox read-only "summarize current repo risks and suggest three narrow tasks"

npm test 2>&1 | codex exec "summarize failing tests"

OPENAI_API_KEY=... npm test && codex exec "fix CI"

最低掌握：
- `codex doctor`
- `codex exec` 的只读用法
- `codex mcp` 的查看和诊断
- CLI TUI 里的 `/plugins`

请用 CLI 辅助我诊断当前 Codex 环境。
 
目标：
1. 先运行 doctor。
2. 解释输出里哪些会影响 App 使用。
3. 不修改配置。
4. 给出下一步排查顺序。

需要掌握：
- `codex exec --json`
- `--output-schema`
- sandbox 参数
- API key 暴露风险
- GitHub Action 里的最小权限模式

codex exec --sandbox read-only --json \
  "review this diff for regression risk and output JSON findings only"

第 1 次接触 CLI：只讲 doctor 和只读 exec。
第 2 次接触 CLI：讲 mcp/plugin 诊断和 JSON 输出。
第 3 次接触 CLI：讲 CI、安全边界和 schema。
最后再讲 app-server、remote-control 和多环境配置。

codex exec --sandbox danger-full-access "fix project"

codex exec --sandbox read-only "summarize the project and suggest narrow fixes"

codex exec --sandbox workspace-write "update README install commands only"

npm test 2>&1 |
  codex exec --sandbox read-only "summarize the failing tests and likely root cause"

npm test 2>&1 |
  codex exec --sandbox read-only "
  Summarize this test failure.
  Output:
  1. failing test names
  2. likely root cause
  3. files to inspect first
  4. smallest next local action
  Do not suggest broad refactors.
  "

我刚用 CLI 分析了 CI 日志，得到：
 
- failing test: auth redirect preserves callback URL
- likely root cause: redirect helper drops query params
- inspect first: src/auth/redirect.ts, tests/auth-redirect.test.ts
 
请在 App 里只读确认这些文件是否相关。
不要修改文件，先给我最小修复计划。

根据刚才的只读计划，执行最小修复。
 
边界：
1. 只修改 redirect helper 和对应测试。
2. 不改 auth UI。
3. 如果需要改其他文件，先暂停说明原因。
4. 修完后运行相关测试。

npm test -- auth-redirect 2>&1 |
  codex exec --sandbox read-only "
  Compare this output with the earlier failure.
  Tell me whether the targeted test now passes.
  If it fails, summarize only the remaining failure.
  "

git diff --stat |
  codex exec --sandbox read-only --json "
  Classify this diff summary into one of:
  docs-only, tests-only, code-low-risk, code-needs-review.
  Return JSON with keys: category, reason, suggested_next_step.
  "

如果 category 是 docs-only：
- 提示用户仍然打开 Review 面板看 diff。
- 可以建议运行 docs lint。
 
如果 category 是 code-needs-review：
- 不自动继续。
- 提醒用户回到 App 或 PR review 流程。

Return JSON only.
 
Schema:
{
  "category": "docs-only | tests-only | code-low-risk | code-needs-review",
  "reason": "short explanation",
  "suggested_next_step": "one concrete next action",
  "needs_human_review": true
}
 
Rules:
1. If source code files changed, needs_human_review must be true.
2. If auth, payment, permissions, migrations, dependencies, or CI config changed, category must be code-needs-review.
3. Do not claim tests passed unless test output is provided.

1. CLI 当前目录是不是同一个项目？
2. Windows 原生和 WSL 是否用了不同 home？
3. `CODEX_HOME` 是否不同？
4. CLI 是否能看到同一份 AGENTS.md？
5. App 的权限设置和 CLI sandbox 是否一致？

我在 App 里能完成任务，但 CLI 里失败。
请帮我按层排查：
1. 当前目录和项目根目录。
2. 登录状态。
3. CODEX_HOME。
4. AGENTS.md 发现路径。
5. sandbox / approval 设置。
 
不要修改配置，先列出我应该检查的命令和原因。

- App 线程里有没有额外上下文？
- CLI prompt 是否漏了目标、范围、验证命令？
- CLI 是否运行在另一个分支或 worktree？
- 是否有不同的 config profile？
- 是否有项目-local 配置未被信任或未加载？

请比较我在 App 和 CLI 中给 Codex 的上下文差异。
目标是找出为什么 CLI 输出和 App 不一致。
只分析可能原因，不修改文件。

请把这个 CLI 任务拆成两步：
1. read-only 能完成的信息收集。
2. 需要写权限或外部访问的动作。
 
每一步说明需要的最低权限。

codex exec --sandbox read-only "inspect the project and suggest a narrow fix"

- CI 失败可复现。
- 仓库已推到 GitHub。
- setup script 能安装依赖。
- 任务范围能写成 5-10 行。
- 结果能通过 diff 和测试检查。

- 依赖本机未同步文件。
- 需要访问本地浏览器状态。
- 需要秘密信息在 agent 阶段使用。
- 需要人工不断选择方向。
- 任务描述只有“帮我优化一下”。

codex cloud exec --env ENV_ID "
Fix the failing auth redirect test.
 
Context:
- Branch contains the failing test.
- Failure: redirect target drops query params after login.
- Relevant files likely include auth redirect helper and auth redirect test.
 
Constraints:
- Do not refactor auth module.
- Do not add dependencies.
- Return changed files and commands run.
"

请只读审查 Cloud 返回的 diff。
确认：
1. 是否只处理 auth redirect。
2. 是否有无关文件。
3. 测试证据是否足够。
4. 我本地应该再跑什么命令。

我会提供几个终端输出摘要。
请帮我整理成团队排障条目。
 
要求：
1. 不包含 token、用户名、绝对私有路径。
2. 按症状 -> 可能原因 -> 检查步骤 -> 下一步写。
3. 区分 Windows 原生、WSL、PowerShell。
4. 不要建议重装作为第一步。

Symptom:
CLI reads different config than App.
 
Observed:
Windows App opens project under C:\Users\Kim\Projects\repo.
CLI was launched inside WSL path.
 
Likely:
Different home and config layers.

# Codex CLI/App Config Mismatch
 
## Symptom
 
Codex App and CLI behave differently in the same-looking project.
 
## Likely Cause
 
The App is using Windows-native paths, while CLI was launched from WSL. Each environment may have different home directories, config, credentials, and project trust state.
 
## Check
 
- Confirm exact project path in App.
- Confirm CLI current directory.
- Check whether `CODEX_HOME` differs.
- Confirm which shell is running commands.
 
## Next Step
 
Use one environment consistently for the exercise, then document when WSL is intentionally needed.

请把这次 CLI 排障整理成一条团队 FAQ。
要求：
1. 一句话症状。
2. 三条检查步骤。
3. 一个不要做的误区。
4. 一个推荐下一步。

codex exec --sandbox danger-full-access "find and fix all security issues"

codex exec --sandbox read-only "
Inspect the repository for security-sensitive areas.
Output likely risks, files to inspect, and suggested narrow next tasks.
Do not modify files.
"

codex exec --sandbox workspace-write "
Fix only the hardcoded debug log in src/auth/session.ts.
Do not modify auth flow, dependencies, config, or tests except the matching regression test.
"

codex exec --sandbox read-only "
Review the current diff for security regression and scope creep.
Do not modify files.
"

1. fix all tests
2. clean up the whole repo
3. improve auth security
4. update dependencies
5. prepare release