如何阅读本 reference
本页汇总每一个有文档说明的 Codex CLI command 和 flag。你可以用交互式表格按 key 或 description 搜索。每个 section 都会说明 option 是 stable 还是 experimental，并标出有风险的组合。
CLI 的大多数 defaults 都继承自 ~/.codex/config.toml。你在 command line 传入的任何 -c key=value overrides，都会在本次 invocation 中优先生效。更多信息见 Config basics 。
Global flags
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --add-dir | path | 授予额外目录写入权限 alongside the main workspace。Repeat for multiple paths. |
| --ask-for-approval, -a | untrusted / on-request / never | 控制 Codex 何时暂停并等待人工 approval 之前 running a command。on-failure is deprecated；prefer on-request for interactive runs 或 never for non-interactive runs. |
| --cd, -C | path | 设置 working directory for agent 之前 it starts processing your request. |
| --config, -c | key=value | 覆盖 configuration values。Values parse as TOML 如果 possible；otherwise the literal string is used. |
| --dangerously-bypass-approvals-and-sandbox, --yolo | boolean | 不经过 approvals 或 sandboxing 运行每个 command。只应在外部加固的 environment 中使用. |
| --dangerously-bypass-hook-trust | boolean | 运行 enabled hooks 不使用 requiring 持久化ed hook trust for this invocation。Intended only for automation that already vets hook sources. |
| --disable | feature | Force-disable a feature flag (translates 到 -c features.<name>=false)。Repeatable. |
| --enable | feature | Force-enable a feature flag (translates 到 -c features.<name>=true)。Repeatable. |
| --image, -i | path[,path...] | 附加一个或多个 image files 到 the initial prompt。Separate multiple paths 使用 commas 或 repeat the flag. |
| --model, -m | string | 覆盖 model 设置 in configuration (例如 gpt-5.4). |
| --no-alt-screen | boolean | Disable alternate screen mode for the TUI (overrides tui.alternate_screen for this 运行). |
| --oss | boolean | 使用 the local 打开 source model provider (equivalent 到 -c model_provider="oss")。Validates that Ollama is running. |
| --profile, -p | string | Layer $CODEX_HOME/profile-name.config.toml on top of the base user config. |
| --remote | ws://host:port / wss://host:port / unix:// / unix://PATH | 连接 到 a remote app-server endpoint over WebSocket 或 a Unix socket。Supported for codex, codex resume, codex fork, codex archive, codex delete, 和 codex unarchive；other subcommands reject remote mode. |
| --remote-auth-token-env | ENV_VAR | 读取 bearer token 从 this environment variable 和 send it 当 connecting 使用 --remote。Requires --remote；tokens are only sent over wss:// URLs 或 local-only ws:// URLs. |
| --sandbox, -s | 读取-only / workspace-write / danger-full-access | 选择 sandbox policy for model-generated shell commands. |
| --search | boolean | 启用 live web 搜索 (sets web_search = "live" 而不是 the 默认 "cached"). |
| --strict-config | boolean | Error 当 config.toml contains fields this Codex version does not recognize。Supported by runtime commands such as codex, exec, 检查, 恢复, fork, app-server, mcp-server, 和 exec-server. |
| PROMPT | string | 可选 text instruction 到 启动 session。Omit 到 launch the TUI 不使用 a pre-filled message. |
These options 应用 到 the base codex command. Most propagate to commands；see the notes above 或 the relevant command help for exceptions。For propagated flags, follow the relevant command help。例如, codex exec --oss ... applies --oss to exec.
Command overview
The 成熟度 column uses feature maturity labels such as Experimental, Beta, 和 Stable。See Feature Maturity for how 到 interpret these labels.
| Key | 成熟度 | 说明 |
|---|---|---|
| codex | Stable | Launch the terminal UI。Accepts the global flags above plus an 可选 prompt 或 image attachments. |
| codex app | Stable | 启动 Codex desktop app on macOS 或 Windows。On macOS, Codex can 打开 a workspace path；on Windows, Codex prints the path 到 打开. |
| codex app-server | Experimental | 启动 Codex app server for local development 或 debugging over stdio, WebSocket, 或 a Unix socket. |
| codex apply | Stable | 应用最新 diff generated by a Codex Cloud task 到 your local working tree。Alias： codex a. |
| codex archive | Stable | 归档已保存的 interactive session by session ID 或 session name. |
| codex cloud | Experimental | Browse 或 execute Codex Cloud tasks 从 the terminal 不使用 opening the TUI。Alias： codex cloud -tasks. |
| codex completion | Stable | 生成 shell completion scripts for Bash, Zsh, Fish, 或 PowerShell. |
| codex debug app-server send-message-v2 | Experimental | Debug app-server by sending a single V2 message through the built-in test client. |
| codex debug models | Experimental | 打印 the raw model catalog Codex sees, including an option 到 inspect only the bundled catalog. |
| codex delete | Stable | 永久删除已保存的 interactive session by session ID 或 session name. |
| codex doctor | Stable | 生成 diagnostic report for local installation, config, auth, runtime, Git, terminal, app-server, 和 thread inventory issues. |
| codex exec | Stable | 运行 Codex non-interactively。Alias： codex e. Stream results to stdout or JSONL and optionally resume previous sessions. |
| codex execpolicy | Experimental | Evaluate execpolicy rule files 和 see whether a command would be allowed, prompted, 或 blocked. |
| codex features | Stable | 列出 feature flags 和 持久化ently enable 或 disable them in config.toml. |
| codex fork | Stable | fork 之前的 interactive session into a 新的 thread, preserving the original transcript. |
| codex login | Stable | 认证 Codex using ChatGPT OAuth, device auth, an API key, 或 an access token piped over stdin. |
| codex logout | Stable | 移除 stored authentication credentials. |
| codex mcp | Experimental | Manage Model Context Protocol servers (列出, 添加, 移除, authenticate). |
| codex mcp-server | Experimental | 运行 Codex itself as an MCP server over stdio。Useful 当 another agent consumes Codex. |
| codex plugin | Experimental | 安装、列出并移除 plugins 从 configured marketplace sources. |
| codex plugin marketplace | Experimental | 添加, 列出, upgrade, 或 移除 plugin marketplaces 从 Git 或 local sources. |
| codex remote-control | Experimental | Ensure the local app-server daemon is running 使用 remote-control support enabled. |
| codex resume | Stable | Continue a previous interactive session by ID 或 恢复 the most 最近 conversation. |
| codex sandbox | Experimental | 运行 arbitrary commands inside Codex-provided macOS, Linux, 或 Windows sandboxes. |
| codex unarchive | Stable | Restore an archived interactive session by session ID 或 session name. |
| codex update | Stable | 检查并应用 a Codex CLI update 当 the installed release supports self-update. |
Command details
codex (interactive)
Running codex with no subcommand launches the interactive terminal UI (TUI)。The agent accepts the global flags above plus image attachments。Web 搜索 默认s 到 cached mode；使用 --search 到 切换 到 live browsing。For low-friction local work, 使用 --sandbox workspace-write --ask-for-approval on-request.
使用 --remote ws://host:port 或 --remote wss://host:port 到 连接 the TUI 到 an app server started 使用 codex app-server --listen ws://IP:PORT. For a local Unix socket, 使用 --remote unix:// for the 默认 socket 或 --remote unix://PATH for an explicit path。添加 --remote-auth-token-env <ENV_VAR> 当 the server requires a bearer token for WebSocket authentication.
codex app-server
启动 Codex app server locally。This is primarily for development 和 debugging 和 may change 不使用 notice.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --analytics-default-enabled | boolean | Defaults analytics 到 enabled for first-party app-server clients unless the user opts out in config. |
| --listen | stdio:// / ws://IP:PORT / unix:// / unix://PATH / off | Transport listener URL。使用 stdio:// for JSONL, ws://IP:PORT for a TCP WebSocket endpoint, unix:// for the 默认 Unix socket, unix://PATH for a custom Unix socket, 或 off 到 disable the local transport. |
| --stdio | boolean | 使用 stdio transport。Equivalent 到 --listen stdio:// 和 mutually exclusive 使用 --listen. |
| --ws-audience | string | Expected aud claim for signed bearer tokens。Requires --ws-auth signed-bearer-token. |
| --ws-auth | capability-token / signed-bearer-token | Authentication mode for app-server WebSocket clients。如果 omitted, WebSocket auth is disabled；non-local listeners warn during startup. |
| --ws-issuer | string | Expected iss claim for signed bearer tokens。Requires --ws-auth signed-bearer-token. |
| --ws-max-clock-skew-seconds | number | Clock skew allowance 当 validating signed bearer token exp 和 nbf claims。Requires --ws-auth signed-bearer-token. |
| --ws-shared-secret-file | absolute path | File containing the HMAC shared secret used 到 validate signed JWT bearer tokens。Required 使用 --ws-auth signed-bearer-token. |
| --ws-token-file | absolute path | File containing the shared capability token。使用 使用 --ws-auth capability-token unless you provide --ws-token-sha256 instead. |
| --ws-token-sha256 | hexadecimal SHA-256 digest | Expected SHA-256 digest for capability-token authentication。使用 而不是 --ws-token-file 当 the client token comes 从 another source. |
codex app-server --listen stdio:// keeps the default JSONL-over-stdio behavior, and codex app-server --stdio is an alias for that transport. --listen ws://IP:PORT enables WebSocket transport for app-server clients. The server accepts ws:// listen URLs; use TLS termination or a secure proxy when clients connect with wss://. Use --listen unix:// to accept WebSocket handshakes on Codex’s default Unix socket, or --listen unix:///absolute/path.sock to choose a socket path. If you generate schemas for client bindings, add --experimental to include gated fields and methods.
codex remote-control
Ensure the app-server daemon is running 使用 remote-control support enabled。Managed remote-control clients 和 SSH remote workflows 使用 this command；it’s not a replacement for codex app-server --listen when you are building a local protocol client.
codex app
Launch Codex Desktop 从 the terminal on macOS 或 Windows。On macOS, Codex can 打开 a specific workspace path；on Windows, Codex prints the path 到 打开.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --download-url | url | Advanced override for the Codex desktop installer URL used during 安装. |
| PATH | path | Workspace path for Codex Desktop。On macOS, Codex opens this path；on Windows, Codex prints the path. |
codex app opens an installed Codex Desktop app, or starts the installer when the app is missing. On macOS, Codex opens the provided workspace path; on Windows, it prints the path to open after installation.
codex debug app-server send-message-v2
Send one message through app-server’s V2 thread/turn flow using the built-in app-server test client.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| USER_MESSAGE | string | Message text sent 到 app-server through the built-in V2 test-client flow. |
This debug flow initializes 使用 experimentalApi：true, starts a thread, sends a turn, 和 streams server notifications。使用 it 到 reproduce 和 inspect app-server protocol behavior locally.
codex debug models
打印 the raw model catalog Codex sees as JSON.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --bundled | boolean | Skip refresh 和 打印 only the model catalog bundled 使用 the 当前 Codex binary. |
使用 --bundled 当 you want 到 inspect only the catalog bundled 使用 the 当前 binary, 不使用 refreshing 从 the remote models endpoint.
codex apply
应用 the most 最近 diff 从 a Codex cloud task 到 your local repository。You must authenticate 和 have access 到 task.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| TASK_ID | string | Identifier of the Codex Cloud task whose diff should be applied. |
Codex prints the patched files 和 exits non-zero 如果 git apply fails (例如, due 到 conflicts).
codex archive and codex unarchive
归档 或 restore a saved interactive session by session ID 或 session name。使用 these commands 当 you want 到 clean up session picker 不使用 deleting the transcript。Session IDs take precedence over session names.
codex archive <SESSION> codex unarchive <SESSION>| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --remote | ws://host:port / wss://host:port / unix:// / unix://PATH | 连接 到 a remote app-server endpoint 之前 changing 归档 state. |
| --remote-auth-token-env | ENV_VAR | 读取 bearer token 从 this environment variable 当 --remote requires authentication. |
| SESSION | session ID / session name | Saved session 到 归档 或 restore。Session IDs take precedence over session names. |
codex delete
永久删除已保存的 interactive session by session ID 或 session name。使用 this only 当 you want 到 移除 the transcript 而不是 hiding it 从 active session lists.
codex delete <SESSION> codex delete <SESSION_UUID> --force| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --force | boolean | 删除 不使用 prompting。The session argument must be a UUID；names still require interactive confirmation. |
| --remote | ws://host:port / wss://host:port / unix:// / unix://PATH | 连接 到 a remote app-server endpoint 之前 deleting session. |
| --remote-auth-token-env | ENV_VAR | 读取 bearer token 从 this environment variable 当 --remote requires authentication. |
| SESSION | session ID / session name | Saved session 到 删除。Session IDs take precedence over session names. |
使用 --force only 使用 a session UUID。Named sessions still require confirmation so Codex doesn’t 删除 a repeated 或 ambiguous name 不使用 a prompt.
codex cloud
Interact 使用 Codex cloud tasks 从 the terminal。The 默认 command opens an interactive picker；codex cloud exec submits a task directly, 和 codex cloud list returns recent tasks for scripting or quick inspection.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --attempts | 1-4 | Number of assistant attempts (best-of-N) Codex Cloud should 运行. |
| --env | ENV_ID | Target Codex Cloud environment identifier (必需)。使用 codex cloud to list options. |
| QUERY | string | Task prompt。如果 omitted, Codex prompts interactively for details. |
Authentication follows the same credentials as the main CLI。Codex exits non-zero 如果 task submission fails.
codex cloud list
列出 最近 cloud tasks 使用 可选 filtering 和 pagination.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --cursor | string | Pagination cursor returned by a previous request. |
| --env | ENV_ID | Filter tasks by environment identifier. |
| --json | boolean | Emit machine-readable JSON 而不是 plain text. |
| --limit | 1-20 | Maximum number of tasks 到 return. |
Plain-text output prints a task URL followed by status details。使用 --json for automation。The JSON payload contains a tasks array plus an 可选 cursor value。Each task includes id, url, title, status, updated_at, environment_id, environment_label, summary, is_review, 和 attempt_total.
codex completion
生成 shell completion scripts 和 redirect the output 到 the appropriate location, 例如 codex completion zsh > "${fpath[1]}/_codex".
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| SHELL | bash / zsh / fish / power-shell / elvish | Shell 到 生成 completions for。Output prints 到 stdout. |
codex doctor
生成 a local diagnostic report 之前 filing a support issue 或 while investigating a broken Codex installation。The report checks installation, configuration, authentication, runtime, Git, terminal, app-server, 和 thread inventory health.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --all | boolean | Expand long lists in the detailed human-readable report. |
| --ascii | boolean | 使用 ASCII status labels 和 separators in human-readable output. |
| --json | boolean | Emit a redacted machine-readable support report. |
| --no-color | boolean | Disable ANSI color in human-readable output. |
| --summary | boolean | 显示 grouped check rows 和 the final count summary only. |
codex features
Manage feature flags stored in $CODEX_HOME/config.toml。The enable 和 disable commands 持久化 changes so they 应用 到 future sessions。The features subcommand doesn’t accept --profile.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| Disable subcommand | codex features disable <feature> | Persistently disable a feature flag in $CODEX_HOME/config.toml. |
| Enable subcommand | codex features enable <feature> | Persistently enable a feature flag in $CODEX_HOME/config.toml. |
| 列出 subcommand | codex features list | 显示 known feature flags, their maturity stage, 和 their effective state. |
codex exec
使用 codex exec (或 the short form codex e) for scripted 或 CI-style runs that should finish 不使用 human interaction.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --cd, -C | path | 设置 workspace root 之前 executing task. |
| --color | always / never / auto | Control ANSI color in stdout. |
| --dangerously-bypass-approvals-and-sandbox, --yolo | boolean | 绕过 approval prompts 和 sandboxing。Dangerous—only 使用 inside an isolated runner. |
| --dangerously-bypass-hook-trust | boolean | 运行 enabled hooks 不使用 requiring 持久化ed hook trust for this invocation。Intended only for automation that already vets hook sources. |
| --ephemeral | boolean | 运行 不使用 持久化ing session rollout files 到 disk. |
| --full-auto | boolean | 已弃用的 compatibility flag。Prefer --sandbox workspace-write；Codex prints a warning 当 this flag is used. |
| --ignore-rules | boolean | Do not load user 或 project execpolicy .rules files for this 运行. |
| --ignore-user-config | boolean | Do not load $CODEX_HOME/config.toml。Authentication still uses CODEX_HOME. |
| --image, -i | path[,path...] | 附加 images 到 the first message。Repeatable；supports comma-separated lists. |
| --json, --experimental-json | boolean | 打印 newline-delimited JSON events 而不是 formatted text. |
| --model, -m | string | Override the configured model for this 运行. |
| --oss | boolean | 使用 the local 打开 source provider (requires a running Ollama instance). |
| --output-last-message, -o | path | 把 assistant 的 final message 写入文件。Useful for downstream scripting. |
| --output-schema | path | JSON Schema file describing the expected final response shape。Codex validates tool output against it. |
| --profile, -p | string | Layer $CODEX_HOME/profile-name.config.toml on top of the base user config. |
| --sandbox, -s | 读取-only / workspace-write / danger-full-access | Sandbox policy for model-generated commands。Defaults 到 configuration. |
| --skip-git-repo-check | boolean | Allow running outside a Git repository (useful for one-off directories). |
| -c, --config | key=value | Inline configuration override for the non-interactive 运行 (repeatable). |
| PROMPT | string / - (读取 stdin) | Initial instruction for task。使用 - 到 pipe prompt 从 stdin. |
| 恢复 subcommand | codex exec resume [SESSION_ID] | 恢复 an exec session by ID 或 添加 --last 到 continue the most 最近 session 从 the 当前 working directory。添加 --all 到 consider sessions 从 any directory。Accepts an 可选 follow-up prompt. |
Codex writes formatted output by 默认。添加 --json 到 receive newline-delimited JSON events (one per state change)。The 可选 恢复 subcommand lets you continue non-interactive tasks。使用 --last 到 pick the most 最近 session 从 the 当前 working directory, 或 添加 --all 到 搜索 across all sessions:
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --all | boolean | Include sessions outside the 当前 working directory 当 selecting the most 最近 session. |
| --image, -i | path[,path...] | 附加 one 或 more images 到 the follow-up prompt。Separate multiple paths 使用 commas 或 repeat the flag. |
| --last | boolean | 恢复 the most 最近 conversation 从 the 当前 working directory. |
| PROMPT | string / - (读取 stdin) | Optional follow-up instruction sent 立即 之后 resuming. |
| SESSION_ID | uuid | 恢复 the specified session。Omit 和 使用 --last 到 continue the most 最近 session. |
codex execpolicy
Check execpolicy rule files 之前 you save them。codex execpolicy check accepts one or more --rules flags (例如, files under ~/.codex/rules) 和 emits JSON showing the strictest decision 和 any matching rules。添加 --pretty 到 format the output。The execpolicy command is currently in preview.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --pretty | boolean | Pretty-print the JSON result. |
| --rules, -r | path (repeatable) | Path 到 an execpolicy rule file 到 evaluate。Provide multiple flags 到 combine rules across files. |
| COMMAND... | var-args | Command 到 be checked against the specified policies. |
codex login
Authenticate the CLI 使用 a ChatGPT account, API key, 或 access token。With no flags, Codex opens a browser for the ChatGPT OAuth flow.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --device-auth | boolean | 使用 OAuth device code flow 而不是 launching a browser window. |
| --with-access-token | boolean | 从 stdin 读取 access token (例如 printenv CODEX_ACCESS_TOKEN / codex login --with-access-token). |
| --with-api-key | boolean | 读取 an API key 从 stdin (例如 printenv OPENAI_API_KEY / codex login --with-api-key). |
| status subcommand | codex login status | 打印 the active authentication mode 和 exit 使用 0 当 logged in. |
codex login status exits with 0 when credentials are present, which is helpful in automation scripts.
codex logout
移除保存的 credentials for both API key 和 ChatGPT authentication。This command has no flags.
codex mcp
管理 Model Context Protocol server entries stored in ~/.codex/config.toml.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| 添加 <name> | -- <command...> / --url <value> | Register a server using a stdio launcher command 或 a streamable HTTP URL。Supports --env KEY=VALUE for stdio transports. |
| get <name> | --json | 显示 a specific server configuration。--json prints the raw config entry. |
| 列出 | --json | 列出 configured MCP servers。添加 --json for machine-readable output. |
| login <name> | --scopes scope1,scope2 | 启动 an OAuth login for a streamable HTTP server (servers that support OAuth only). |
| logout <name> | 移除 stored OAuth credentials for a streamable HTTP server. | |
| 移除 <name> | 删除 a stored MCP server definition. |
The 添加 subcommand supports both stdio 和 streamable HTTP transports:
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --bearer-token-env-var | ENV_VAR | Environment variable whose value is sent as a bearer token 当 connecting 到 a streamable HTTP server. |
| --env KEY=VALUE | repeatable | Environment variable assignments applied 当 launching a stdio server. |
| --oauth-client-id | CLIENT_ID | OAuth client identifier for a streamable HTTP MCP server。Requires --url. |
| --oauth-resource | RESOURCE | OAuth resource parameter 到 include during login for a streamable HTTP MCP server。Requires --url. |
| --url | https://… | Register a streamable HTTP server 而不是 stdio。Mutually exclusive 使用 COMMAND.... |
| COMMAND... | stdio transport | Executable plus arguments 到 launch the MCP server。Provide 之后 --. |
OAuth actions (login, logout) only work 使用 streamable HTTP servers (和 only 当 the server supports OAuth).
codex plugin
安装、列出并移除 plugins 从 configured marketplaces.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| 添加 <plugin[@marketplace]> | [--marketplace, -m NAME] [--json] | 安装 a plugin 从 a configured marketplace。使用 --marketplace 或 -m 当 the plugin argument omits @marketplace. |
| 列出 | [--marketplace, -m NAME] [--available --json] [--json] | 列出 installed plugins。With --json, output has installed 和 可用 arrays；--available includes uninstalled marketplace plugins 和 requires --json. |
| marketplace | Manage configured marketplace sources。See codex plugin marketplace below. | |
| 移除 <plugin[@marketplace]> | [--marketplace, -m NAME] [--json] | 移除 an installed plugin 从 local config 和 cache。使用 --json for automation-friendly output. |
codex plugin add --json prints pluginId, name, marketplaceName, version, installedPath, and authPolicy. codex plugin list --json prints installed and available arrays. Entries include pluginId, name, marketplaceName, version, installed, enabled, source, installPolicy, authPolicy, and, when available, marketplaceSource with the configured marketplace source type and value. codex plugin remove --json prints pluginId, name, and marketplaceName.
codex plugin marketplace
管理 plugin marketplace sources that Codex can browse 和 安装 从.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| 添加 <source> | [--ref REF] [--sparse PATH] [--json] | 安装 a plugin marketplace 从 GitHub shorthand, a Git URL, an SSH URL, 或 a local marketplace root directory。--sparse is 支持的 only for Git sources 和 can be repeated. |
| 列出 | [--json] | 显示 plugin marketplaces Codex is currently considering 和 the root path for each marketplace. |
| 移除 <marketplace-name> | [--json] | 移除 a configured plugin marketplace. |
| upgrade [marketplace-name] | [--json] | Refresh one configured Git marketplace, 或 all configured Git marketplaces 当 no name is provided. |
codex plugin marketplace add accepts GitHub shorthand such as owner/repo or owner/repo@ref, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace root directories. Use --ref to pin a Git ref, and repeat --sparse PATH to use a sparse checkout for Git-backed marketplace repositories.
codex plugin marketplace list prints in-scope marketplace names and roots, including implicitly discovered default marketplaces and configured marketplace snapshots.
添加 --json 到 marketplace 添加, 列出, upgrade, 或 移除 commands for automation-friendly output。Marketplace 添加 JSON includes marketplaceName, installedRoot, 和 alreadyAdded；列出 JSON includes a marketplaces array 使用 name, root, 和 可选 marketplaceSource；upgrade JSON includes selectedMarketplaces, upgradedRoots, 和 errors；移除 JSON includes marketplaceName 和 installedRoot.
codex mcp-server
运行 Codex as an MCP server over stdio so that other tools can 连接。This command inherits global configuration overrides 和 exits 当 the downstream client closes the connection.
codex resume
继续一个 interactive session by ID 或 恢复 the most 最近 conversation。codex resume scopes --last to the current working directory unless you pass --all. It accepts the same global flags as codex, including model 和 sandbox overrides.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --all | boolean | Include sessions outside the 当前 working directory 当 selecting the most 最近 session. |
| --last | boolean | Skip picker 和 恢复 the most 最近 conversation 从 the 当前 working directory. |
| SESSION_ID | uuid | 恢复 the specified session。Omit 和 使用 --last 到 continue the most 最近 session. |
codex fork
fork 之前的 interactive session into a 新的 thread。By 默认, codex fork opens the session picker；添加 --last 到 fork your most 最近 session instead.
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --all | boolean | 显示 sessions beyond the 当前 working directory in picker. |
| --last | boolean | Skip picker 和 fork the most 最近 conversation 自动. |
| SESSION_ID | uuid | Fork the specified session。Omit 和 使用 --last 到 fork the most 最近 session. |
codex sandbox
使用 sandbox helper 到 运行 a command under the same policies Codex uses internally.
macOS seatbelt
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --allow-unix-socket | path | Allow the sandboxed command 到 bind 或 连接 Unix sockets rooted at this path。Repeat 到 allow multiple paths. |
| --cd, -C | DIR | Working directory used for profile resolution 和 command execution。Requires --permissions-profile. |
| --config, -c | key=value | Pass configuration overrides into the sandboxed 运行 (repeatable). |
| --include-managed-config | boolean | Include managed requirements while resolving an explicit permissions profile。Requires --permissions-profile. |
| --log-denials | boolean | Capture macOS sandbox denials 使用 log stream while command runs 和 打印 them 之后 exit. |
| --permissions-profile, -P | NAME | 应用 a named permissions profile 从 the active configuration stack. |
| --profile, -p | NAME | Layer $CODEX_HOME/NAME.config.toml on top of the base user config. |
| COMMAND... | var-args | Shell command 到 execute under macOS Seatbelt。Everything 之后 -- is forwarded. |
Linux Landlock
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --cd, -C | DIR | Working directory used for profile resolution 和 command execution。Requires --permissions-profile. |
| --config, -c | key=value | Configuration overrides applied 之前 launching the sandbox (repeatable). |
| --include-managed-config | boolean | Include managed requirements while resolving an explicit permissions profile。Requires --permissions-profile. |
| --permissions-profile, -P | NAME | 应用 a named permissions profile 从 the active configuration stack. |
| --profile, -p | NAME | Layer $CODEX_HOME/NAME.config.toml on top of the base user config. |
| COMMAND... | var-args | Command 到 execute under Landlock + seccomp。Provide the executable 之后 --. |
Windows
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| --cd, -C | DIR | Working directory used for profile resolution 和 command execution。Requires --permissions-profile. |
| --config, -c | key=value | Configuration overrides applied 之前 launching the sandbox (repeatable). |
| --include-managed-config | boolean | Include managed requirements while resolving an explicit permissions profile。Requires --permissions-profile. |
| --permissions-profile, -P | NAME | 应用 a named permissions profile 从 the active configuration stack. |
| --profile, -p | NAME | Layer $CODEX_HOME/NAME.config.toml on top of the base user config. |
| COMMAND... | var-args | Command 到 execute under the native Windows sandbox。Provide the executable 之后 --. |
codex update
检查并应用 a Codex CLI update 当 the installed release supports self-update。Debug builds 打印 a message telling you 到 安装 a release build instead.
Flag 组合和安全提示
对于可以限制在 workspace 内的 unattended local work，请使用 --sandbox workspace-write；除非你位于专用 sandbox VM 中，否则避免使用 --dangerously-bypass-approvals-and-sandbox。
当你需要授予 Codex 对更多 directories 的 write access 时，优先使用 --add-dir，而不是强制使用 --sandbox danger-full-access。
在 CI 中将 --json 与 --output-last-message 搭配使用，以捕获 machine-readable progress 和最终的 natural-language summary。
Codex CLI overview ：installation, upgrades, 和 quick tips.
Config basics ：持久化 默认s like the model 和 provider.
Advanced Config ：profiles, providers, sandbox tuning, 和 integrations.
AGENTS.md ：conceptual overview of Codex agent capabilities 和 best practices.