Codex CLICodex CLI

English summaries and interface labels are available. Detailed source notes below are currently in Chinese.

模型与开放条件Model & openness

默认可跑 OpenAI 自家模型，架构上也允许换成别的 provider。

官方 config-basic 的「Default model」示例是 model = "gpt-5.5"。 CLI 另有 --model / -m 可以覆盖（示例给的是 gpt-5.4）。

配套的模型开关有三个：

• model_context_window
• model_reasoning_effort
• model_catalog_json（或用 codex debug models 查看模型目录）

自定义 provider 是官方明确支持的（config-advanced「Custom model providers」）。

配置方式：顶层写 model + model_provider，再配 [model_providers.<id>]。

可用的字段有五个：base_url / env_key / wire_api / http_headers / auth.command。

内置的 provider ID 保留名有三个：openai、ollama、lmstudio。

另有内置 amazon-bedrock。官方示例直接给：

官方示例：[model_providers.mistral] base_url="https://api.mistral.ai/v1"

本地模型走 OSS 模式：--oss + oss_provider = "ollama" | "lmstudio"。 想改内置 OpenAI provider 的地址，用 openai_base_url。

换成第三方模型之后，tool calling 的质量官方没给量化结论。

Runs OpenAI's own models by default; architecturally it also allows swapping to other providers.

The official config-basic "Default model" example is model = "gpt-5.5". The CLI also has --model / -m to override (the example given is gpt-5.4).

Three companion model switches:

• model_context_window
• model_reasoning_effort
• model_catalog_json (or view the model catalog with codex debug models)

Custom providers are explicitly supported by the official side (config-advanced "Custom model providers").

Configuration: write model + model_provider at the top level, then configure [model_providers.<id>].

Five available fields: base_url / env_key / wire_api / http_headers / auth.command.

Three reserved built-in provider IDs: openai, ollama, lmstudio.

There is also a built-in amazon-bedrock. The official example gives directly:

Official example: [model_providers.mistral] base_url="https://api.mistral.ai/v1"

Local models go through OSS mode: --oss + oss_provider = "ollama" | "lmstudio". To change the built-in OpenAI provider's address, use openai_base_url.

After switching to third-party models, the official gives no quantified conclusion on tool-calling quality.

运行位置Where it runs

它是一个本地跑着的终端进程。

代码用 Rust 写。releases 的版本标签是 rust-v*。

生命周期绑在终端会话上：退出即结束。

It is a terminal process running locally.

The code is written in Rust. Release version tags are rust-v*.

Its lifetime is bound to the terminal session: quit and it ends.

本地文件Local files

它在你的工作目录里动手，默认只写工作区，而且要求那里是 Git 仓库。

官方 agent-approvals-security 的原文是下面这一句：

官方原文："no network access and write permissions limited to the active workspace"

这句的意思是：没有网络访问，写权限只限当前工作区。

这里的「工作区」含当前目录与 /tmp，用 /status 可以查看工作区目录。

沙箱默认档位分两种：

• 版本控制目录默认 workspace-write
• 非版本控制目录默认 read-only

workspace-write 之下，.git / .agents / .codex 是递归只读的。

可调的几项：--add-dir 追加可写目录、-C/--cd 指定工作目录、 project_root_markers 自定义项目根识别（默认含 .git）。

一条硬约束：非交互的 codex exec 要求工作目录是 Git 仓库。官方原文是：

官方原文："Codex requires commands to run inside a Git repository"

想跳过这条检查，用 --skip-git-repo-check。

It works inside your working directory, writes only to the workspace by default, and requires that directory to be a Git repository.

The official agent-approvals-security wording is this sentence:

Official wording: "no network access and write permissions limited to the active workspace"

That means: no network access, write permissions limited to the active workspace.

The "workspace" here includes the current directory and /tmp; /status shows the workspace directories.

Sandbox default tiers come in two flavors:

• version-controlled directories default to workspace-write
• non-version-controlled directories default to read-only

Under workspace-write, .git / .agents / .codex are recursively read-only.

Tunable items: --add-dir appends writable directories, -C/--cd sets the working directory, project_root_markers customizes project-root detection (.git included by default).

One hard constraint: non-interactive codex exec requires the working directory to be a Git repository. Official wording:

Official wording: "Codex requires commands to run inside a Git repository"

To skip this check, use --skip-git-repo-check.

关机后的任务Tasks after shutdown

本地这个终端进程随会话结束，但官方还另有一层云端任务形态，已核到。

官方 Codex cloud 页原文说，Codex cloud 让 Codex 在自己的云环境里干活：

官方原文："work on tasks in the background (including in parallel) using its own cloud environment"

这些任务跑在隔离的 OpenAI 托管容器里：

官方原文："isolated OpenAI-managed containers"

它不访问你的宿主机，也不碰无关数据。

CLI 这一侧有两个入口：

• codex cloud 子命令（实验性，别名 codex cloud-tasks）
• codex apply —— 把云任务的 diff 应用到本地工作树

云端按 ChatGPT 套餐提供（Plus / Pro / Business / Edu / Enterprise）。

云端任务的并发与时长额度官方没给具体数值，只写随套餐。

The local terminal process ends with the session, but the official additionally has a cloud task form, now verified.

The official Codex cloud page says Codex cloud lets Codex work in its own cloud environment:

Official wording: "work on tasks in the background (including in parallel) using its own cloud environment"

These tasks run in isolated OpenAI-managed containers:

Official wording: "isolated OpenAI-managed containers"

It does not access your host machine and does not touch unrelated data.

The CLI side has two entry points:

• the codex cloud subcommand (experimental, alias codex cloud-tasks)
• codex apply — applies a cloud task's diff to the local working tree

Cloud access follows ChatGPT plans (Plus / Pro / Business / Edu / Enterprise).

Cloud-task concurrency and duration quotas: the official gives no concrete numbers, only "follows the plan".

工具与扩展Tools & extensions

内置工具面和 MCP 都已核到。

内置能力分散在 config 的能力开关里，一共六类：

• shell —— 执行命令，开关是 features.shell_tool
• unified_exec —— PTY 执行
• web search —— web_search = cached | live | disabled
• undo、git commit
• multi-agent 协作 —— 开关是 features.multi_agent，工具是 spawn_agent
• 协作工具还有 send_input / resume_agent / wait_agent / close_agent
• memories

非交互侧的事件流也能看到这些动作：codex exec --json 的事件类型含 command executions、file changes、MCP tool calls、web searches、plan updates。

扩展机制有三种：Hooks（PreToolUse / PostToolUse / PreCompact 等）、 Skills（SKILL.md，可打包为 plugins）与 plugin marketplace。

MCP 官方支持完整。 官方 MCP 页原话是：

"Codex supports MCP servers in both the CLI and the IDE extension"

传输支持 STDIO 与 Streamable HTTP（Bearer / OAuth，登录用 codex mcp login）。

配置两处都行：codex mcp CLI，或 [mcp_servers.<name>]。

工具级开关有 enabled_tools / disabled_tools 与 per-tool approval_mode。

反过来也行：codex mcp-server 能把 Codex 本身当 MCP server 暴露给别的 agent。

Both the built-in tool surface and MCP have been verified.

Built-in capabilities are spread across config feature toggles, six classes in total:

• shell — executes commands, toggled by features.shell_tool
• unified_exec — PTY execution
• web search — web_search = cached | live | disabled
• undo, git commit
• multi-agent collaboration — toggled by features.multi_agent, the tool is spawn_agent
• companion tools also include send_input / resume_agent / wait_agent / close_agent
• memories

The non-interactive event stream also surfaces these actions: codex exec --json event types include command executions, file changes, MCP tool calls, web searches, plan updates.

Three extension mechanisms: Hooks (PreToolUse / PostToolUse / PreCompact etc.), Skills (SKILL.md, packageable as plugins) and a plugin marketplace.

MCP support is complete officially. The official MCP page says:

"Codex supports MCP servers in both the CLI and the IDE extension"

Transports support STDIO and Streamable HTTP (Bearer / OAuth; log in with codex mcp login).

Configuration works in two places: the codex mcp CLI, or [mcp_servers.<name>].

Tool-level switches include enabled_tools / disabled_tools and per-tool approval_mode.

The reverse also works: codex mcp-server exposes Codex itself as an MCP server to other agents.

上下文与记忆Context & memory

会话续接 + 自动压缩 + 可选 memories，三轮机制都已核到。

续接：交互式用 codex resume，非交互用 codex exec resume （--last 或 <SESSION_ID>）。codex fork 能把会话分叉成新线程。

app server 架构让线程可启动、续接与恢复。

压缩：官方配置键是 compact_prompt（内联覆盖压缩提示词）与 experimental_compact_prompt_file；另有 PreCompact / PostCompact hook 事件。

上下文窗口可用 model_context_window 显式设置（示例 128000）。

记忆需要显式开启：打开 [features] memories = true 之后， Codex 会把既往会话提炼成本地记忆文件（默认放 ~/.codex/memories/）。

TUI 里用 /memories 按线程控制，参数走 memories.*。 官方称 memories 会 "redacts secrets"。

注意 memories 默认关闭。

Session resumption + automatic compaction + optional memories — all three mechanisms verified.

Resumption: interactively via codex resume, non-interactively via codex exec resume (--last or <SESSION_ID>). codex fork forks a session into a new thread.

The app-server architecture lets threads be started, resumed and recovered.

Compaction: the official config keys are compact_prompt (inline override of the compaction prompt) and experimental_compact_prompt_file; there are also PreCompact / PostCompact hook events.

The context window can be set explicitly via model_context_window (example: 128000).

Memories must be explicitly enabled: after turning on [features] memories = true, Codex distills past sessions into local memory files (default location ~/.codex/memories/).

In the TUI, /memories controls per thread; parameters go through memories.*. The official says memories "redacts secrets".

Note memories are off by default.

权限与限制Permissions & limits

沙箱与审批边界跟随运行环境。

API key 计费与订阅不是同一额度（此点已在官方用量说明中确认）。

审批与沙箱模式已核验完成：官方口径（agent-approvals-security / config-advanced / config-reference）与 SDK 源码一致。

审批策略用顶层 approval_policy：

• untrusted / on-request / never / granular
• on-failure（已弃用）

复核人用 approvals_reviewer，取 user 或 auto_review。

沙箱模式用 sandbox_mode，取 read-only / workspace-write / danger-full-access； 另有命名 profile :read-only / :workspace / :danger-full-access。

本地默认是 workspace-write，而且网络关闭。

非版本控制目录默认 read-only。

workspace-write 下 .git / .agents / .codex 递归只读。 网络另有 features.network_proxy 域名 allowlist + DNS 重绑定防护。

TUI 里还有三个开关：

• /permissions —— 切 read-only
• --ask-for-approval never —— 关审批
• --dangerously-bypass-approvals-and-sandbox（别名 --yolo）—— 全放开

Windows 另有专属档位：[windows] sandbox = "elevated" | "unelevated"。 codex sandbox 子命令可在 macOS / Linux / Windows 提供沙箱。

但逐平台的实现细节官方没按平台分别展开（已查 config-basic 与 agent-approvals-security 两页，未分平台列出）。

详见 Codex SDK 档案。

Sandbox and approval boundaries follow the runtime environment.

API-key billing and subscription are not the same quota (confirmed in the official usage notes).

Approval and sandbox modes are fully verified: the official stance (agent-approvals-security / config-advanced / config-reference) matches the SDK source.

The approval policy is the top-level approval_policy:

• untrusted / on-request / never / granular
• on-failure (deprecated)

The reviewer is approvals_reviewer, taking user or auto_review.

The sandbox mode is sandbox_mode, taking read-only / workspace-write / danger-full-access; there are also named profiles :read-only / :workspace / :danger-full-access.

The local default is workspace-write, with networking off.

Non-version-controlled directories default to read-only.

Under workspace-write, .git / .agents / .codex are recursively read-only. Networking additionally has features.network_proxy domain allowlist + DNS-rebinding protection.

The TUI has three more toggles:

• /permissions — switch to read-only
• --ask-for-approval never — turn approvals off
• --dangerously-bypass-approvals-and-sandbox (alias --yolo) — open everything

Windows has its own dedicated tier: [windows] sandbox = "elevated" | "unelevated". The codex sandbox subcommand can provide sandboxing on macOS / Linux / Windows.

But the official does not expand per-platform implementation details by platform (checked config-basic and agent-approvals-security; not listed per platform).

See the Codex SDK dossier.

适合什么任务Best for

适合在终端里做工程任务，要接 CI 或要自建客户端的场景。

它有个别人少有的证据：非交互模式有官方文档支持。 docs/exec.md 的标题就是 Non-interactive mode（正文为外链）。

这使它是本站 CLI 分区里除 Gemini CLI 外唯一有非交互证据的对象。

已有仓库的续接与恢复是它的架构重点。

Fits engineering tasks in the terminal, scenarios hooking into CI or building custom clients.

It has a piece of evidence few others have: non-interactive mode has official documentation support. docs/exec.md is titled Non-interactive mode (body is an external link).

That makes it, besides Gemini CLI, the only subject in this site's CLI category with non-interactive evidence.

Resumption and recovery on existing repositories are its architectural focus.

在【仓库】里修【bug】。流程：
1) 先复现并贴失败日志；
2) 给计划（改哪些文件、不改哪些）；
3) 每改一个文件就跑相关测试；
4) 最后给风险点与回滚方式。

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.