# Codex CLI 与终端参考

> Codex CLI 终端使用、启动参数、exec、resume、app-server、远程连接、诊断、JSONL 和 stdin 管道的进阶参考。

URL: https://docs.passion8.cc/docs/codex/cli-terminal-reference
Language: zh-CN
Publisher: Passion8

[命令大全](https://docs.passion8.cc/docs/codex/commands) 是速查表。本页补充 CLI 工作方式、终端会话、非交互输出、远程 app-server 和常见诊断方式。

## 启动位置

Codex 的工作边界从当前目录开始。日常建议在项目根目录启动:

```bash
cd /path/to/project
codex
```

临时指定目录:

```bash
codex -C /path/to/project
codex --cd /path/to/project "解释这个项目"
```

如果任务需要跨多个目录,优先用 git worktree、monorepo 根目录或 `--add-dir`,不要直接开全盘权限。

## 常用启动组合

| 场景 | 命令 |
| --- | --- |
| 默认交互 | `codex` |
| 带初始任务 | `codex "修复这个报错"` |
| 只读研究 | `codex --sandbox read-only --ask-for-approval on-request` |
| 可信项目小步实现 | `codex --sandbox workspace-write --ask-for-approval on-request` |
| 指定模型 | `codex --model gpt-6-sol` |
| 临时启用 live search | `codex --search` |
| 严格配置检查 | `codex --strict-config` |

`--dangerously-bypass-approvals-and-sandbox` 只适合隔离环境、临时 worktree、可恢复目录。不要在生产目录或含密钥目录里作为默认启动方式。

## 交互式会话习惯

| 动作 | 推荐做法 |
| --- | --- |
| 引用文件 | 输入 `@` 或用 `/mention` |
| 复杂任务 | 先 `/plan`,再执行 |
| 长任务 | 用 `/goal` 写清完成条件 |
| 看当前状态 | `/status` |
| 看 diff | `/diff` |
| 做 review | `/review` |
| 切权限 | `/permissions` |
| 压缩上下文 | `/compact` |
| 恢复历史 | `/resume` 或 `codex resume --last` |

Codex 线程可以继续、fork、归档或删除。不要让两个线程同时改同一批文件,除非每个线程都在独立 worktree 里。

## 非交互 exec

`codex exec` 适合脚本、CI 和一次性批处理:

```bash
codex exec "review the current diff and list P0/P1 risks"
```

继续上一段非交互会话:

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

指定 session:

```bash
codex exec resume <SESSION_ID> "continue with the same constraints"
```

非交互模式默认要求在 Git 仓库里运行,这是为了降低破坏性改动风险。确实需要在非 Git 目录跑时,再考虑 `--skip-git-repo-check`。

## stdin 管道

当另一个命令产生上下文时,用 prompt + stdin:

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

日志排查:

```bash
tail -n 200 app.log \
  | codex exec "identify the likely root cause and next three debugging steps"
```

CI 更新:

```bash
gh run view 123456 --log \
  | codex exec "write a concise PR comment explaining the CI failure"
```

## 输出与自动化

| 需求 | 做法 |
| --- | --- |
| 机器读取结果 | 使用 JSON / JSONL 输出参数,并让 prompt 要求固定结构 |
| 多阶段 pipeline | 用 `codex exec resume` |
| 保留最后回复 | 重定向 stdout 到文件 |
| 保留完整 diff | `git diff --binary HEAD > codex.patch` |
| 限定模型和权限 | 传 `--model`、`--sandbox`、`--ask-for-approval` |

如果要做 GitHub Actions,优先看 [非交互、CI 与 SDK](https://docs.passion8.cc/docs/codex/noninteractive-ci-sdk)。

## app-server 与远程连接

`codex app-server` 是 Codex App / IDE 等富客户端背后的协议入口,适合做深度集成或调试,不是普通 CI 的首选。

常见启动:

```bash
codex app-server
codex app-server --listen ws://127.0.0.1:4500
codex app-server --listen unix://
```

连接远程 app-server:

```bash
codex --remote ws://127.0.0.1:4500
```

WebSocket 远程监听仍应只放在 localhost 或 SSH tunnel 后面。需要暴露给远程客户端时,必须配置认证 token,不要裸露在公网或局域网。

## 诊断

```bash
codex doctor
codex debug models
codex features
codex mcp list
```

TUI 内:

```text
/debug-config
/mcp
/status
/usage
/feedback
```

日志:

```bash
RUST_LOG=debug codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log
```

`codex-login.log` 用于登录排错。非交互 `codex exec` 通常把诊断信息直接输出在命令结果里。

## shell completion

Codex CLI 支持生成 shell completion。具体参数随版本变化,先看:

```bash
codex completion --help
```

如果找不到某个子命令,先升级 CLI 或用 `codex --help` / `codex <subcommand> --help` 查看当前版本支持的命令。

## 官方参考

- [Codex manual: CLI command reference](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Slash commands in Codex CLI](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Non-interactive mode](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: App Server](https://developers.openai.com/codex/codex-manual.md)