---
title: "CLI 参数怎么用"
description: "把 Codex CLI 参数按任务入口、权限控制和自动化场景拆开，避免把会随版本变化的命令清单写死。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Codex CLI 的参数不要按“完整列表”学习。更实用的方式是先判断你要启动哪类任务，再决定使用哪些参数覆盖默认配置。

官方 CLI 会继续演进，完整命令和 flag 以 `codex --help`、子命令 `--help` 和官方 CLI Features 为准。本页只保留稳定用法和风险边界。

> [!TIP]
> 记住一个原则：长期默认值写进 `config.toml`，项目规则写进 `.codex/`，本次临时变化才用 CLI 参数。

<Cards>
  <Card title="CLI Features" href="https://developers.openai.com/codex/cli/features">
    查看 Codex CLI 的 TUI、slash commands、remote app server、MCP、exec 等官方能力说明。
  </Card>
  <Card title="Configuration Reference" href="https://developers.openai.com/codex/config-reference">
    查看参数背后的配置 key、类型、默认值和可用范围。
  </Card>
  <Card title="Agent Security" href="https://developers.openai.com/codex/agent-approvals-security">
    理解 approval、sandbox、network access 和 agent 执行边界。
  </Card>
</Cards>

## CLI 参数的三类用途

```mermaid
flowchart TB
    Start["codex 命令"] --> Entry["选择任务入口"]
    Start --> Boundary["设置执行边界"]
    Start --> Override["覆盖本次配置"]

    Entry --> TUI["interactive TUI"]
    Entry --> Exec["codex exec"]
    Entry --> Cloud["cloud / apply / resume"]

    Boundary --> Sandbox["sandbox"]
    Boundary --> Approval["approval"]
    Boundary --> Workspace["working directory / extra dirs"]

    Override --> Model["model / profile"]
    Override --> Feature["feature flags"]
    Override --> Config["-c key=value"]
```

读参数时先问：

- 我是在打开交互式 TUI，还是跑一次自动化任务。
- 这次是否允许改文件、联网、执行命令。
- 这次变化应该临时生效，还是应该写进配置文件。

如果这三个问题没想清楚，参数越多越容易误用。

## 最常用入口

打开交互式 TUI：

```bash
codex
```

带一个初始任务进入 TUI：

```bash
codex "检查这个 PR 的风险点"
```

在指定目录启动：

```bash
codex --cd /path/to/repo
```

非交互执行一次任务：

```bash
codex exec "运行测试并总结失败原因"
```

把 stdin 作为任务输入：

```bash
cat prompt.md | codex exec -
```

这些入口的差别不是“命令长短”，而是交互模型不同：TUI 适合边看边改，`exec` 适合脚本化、CI、批处理。

## 权限参数优先看 sandbox 和 approval

Codex 会读文件、改文件、调用工具。启动前最重要的是权限边界。

常见组合：

```bash
codex --sandbox read-only --ask-for-approval on-request
codex --sandbox workspace-write --ask-for-approval on-request
codex exec --sandbox workspace-write --ask-for-approval never "运行只读审计"
```

使用建议：

- 只想让它分析项目，用 `read-only`。
- 允许它改当前 workspace，用 `workspace-write`。
- 需要访问 workspace 外目录时，明确传入额外目录，而不是放开全部权限。
- 自动化运行如果使用 `never`，必须确保外层 runner 已经隔离。
- 不要把危险组合写成团队默认值。

> [!WARNING]
> `--dangerously-bypass-approvals-and-sandbox` / `--yolo` 只适合外部已经隔离、可回滚、低价值环境。它不是“更省事”的日常模式。

## 临时配置用 `-c`

`-c` / `--config` 用于覆盖本次 invocation 的配置。它适合临时实验，不适合替代正式配置。

```bash
codex -c model_reasoning_effort='"high"'
codex -c sandbox_mode='"read-only"'
codex -c 'features.codex_hooks=true'
```

注意：

- 值按 TOML 解析；字符串通常要加引号。
- Nested key 可以用点号。
- 同一个参数可以重复传入。
- 如果某个覆盖值每次都要写，应回到 `config.toml` 或 profile。

这也是排查配置问题的好方法：先用 `-c` 验证单次行为，再决定是否固化。

## Profile 适合常用工作模式

如果你经常切换模式，不要每次手写一长串参数。用 profile。

```toml
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.implementation]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

启动：

```bash
codex --profile review
codex --profile implementation
```

Profile 最适合表达“我现在要进入哪种工作状态”。它比临时 flag 更稳定，也比复制命令更少出错。

## `exec` 用于自动化，不等于放弃审查

`codex exec` 常用于批处理、脚本和 CI 风格任务。

```bash
codex exec "检查 docs 中有没有失效链接"
```

适合场景：

- 对一批文件做一致性检查。
- 在 CI 或脚本里生成结构化结果。
- 从 stdin 读取长 prompt。
- 让 Codex 完成一次明确、可验证的任务。

不适合场景：

- 需求还在讨论。
- 需要频繁人工决策。
- 需要对生产环境做不可逆操作。
- 任务边界不清楚但权限很大。

自动化入口更要明确 sandbox、approval、工作目录和输出格式。

## Remote 和 app-server 要先处理认证边界

Codex CLI 支持把 TUI 连接到 remote app-server。这类能力适合本地开发、远程工作区和特殊集成，但默认不应暴露给不受信任网络。

使用时重点检查：

- endpoint 是否只在可信网络可达。
- token 是否通过安全渠道传递。
- `ws://` 是否仅用于 localhost 或受控环境。
- app-server 是否有清晰的启动和关闭方式。

如果不确定认证和网络边界，不要为了方便直接暴露 remote endpoint。

## MCP 和插件类命令先看用途

Codex CLI 也包含 MCP、features、completion、cloud、apply、resume 等命令。学习顺序建议：

1. 先掌握 `codex` 和 `codex exec`。
2. 再掌握 sandbox、approval、profile、`-c`。
3. 然后配置 MCP servers。
4. 最后处理 cloud、remote、app-server、plugin marketplace 这类扩展能力。

这样学不会被命令数量带偏。CLI 的核心价值始终是：在正确边界内把 Codex 接入真实工程任务。

## 日常命令模板

只读审计：

```bash
codex --sandbox read-only --ask-for-approval on-request
```

普通本地实现：

```bash
codex --sandbox workspace-write --ask-for-approval on-request
```

单次高推理任务：

```bash
codex -c model_reasoning_effort='"high"' "审查这次重构的风险"
```

脚本化检查：

```bash
codex exec --sandbox read-only --ask-for-approval never "列出 docs 中需要人工复核的页面"
```

这些模板不要原样当成永久标准。最终应该根据你的项目风险、团队规范和运行环境沉淀成 profiles。

## 不建议写死的内容

教程和团队文档里不建议长期写死这些清单：

- 完整 CLI flag 表。
- 完整子命令表。
- 模型列表和价格。
- 实验 feature flag 列表。
- remote / app-server 的内部协议细节。

它们更新频率高，写死后很快变成误导。更稳的写法是说明“怎么查、怎么选、怎么控制风险”。

## 团队文档怎么写

团队内部写 Codex CLI 教程时，不要把页面变成命令速查表。命令速查表会随版本变化，很快失效；更稳定的写法是把“入口选择、权限边界、验证动作、回滚方式”写清楚。新人真正需要知道的是：什么时候进入 TUI，什么时候用 `exec`，什么时候必须只读，什么时候要停下来让负责人确认。

商业项目里还要把 CLI 参数和团队默认 profile 对齐。文档可以给出推荐模式，但最终应落到 `config.toml`、项目规则和 CI 检查里。这样每个人启动 Codex 时看到的是一致边界，而不是从聊天记录里复制一串临时参数。
