Codex Security CLI 参考 | 命令、提供商、参数与退出码

使用本参考文档查看支持的 codex-security 命令、标志、输出格式和退出行为。如需引导式完成首次扫描，请从 CLI 快速入门开始。

使用 npx @openai/codex-security 运行 CLI。

命令概览

usage: codex-security [--version] <command> [options]

CLI 提供以下命令：

命令	用途
`codex-security scan`	运行 Codex Security 扫描。
`codex-security install-hook`	安装 Git 预提交安全扫描。
`codex-security bulk-scan`	发现仓库并运行可恢复的批量扫描。
`codex-security scans`	列出、检查、比较和检索已保存的扫描日志。
`codex-security findings`	审查并更新已保存的安全发现。
`codex-security export`	将已完成的发现导出为 CSV、JSON 或 SARIF。
`codex-security publish`	将已完成扫描的发现发布到 Linear。
`codex-security validate`	检查一个或多个候选安全发现。
`codex-security patch`	修补一个或多个安全问题。
`codex-security login`	登录、存储凭据或检查登录状态。
`codex-security logout`	移除已存储的登录信息。
`codex-security info`	显示只读 SDK 和捆绑插件元数据。

CLI 还提供以下集成命令：

命令	用途
`codex-security completions`	生成 shell 补全脚本。
`codex-security mcp`	将 CLI 注册为 MCP 服务器。
`codex-security skills`	将 Codex Security 技能同步到智能体。

列出所有可用命令：

npx @openai/codex-security --help

向命令添加 --help 以检查其参数和选项：

npx @openai/codex-security scan --help

codex-security --version 会输出已安装的版本并退出。 codex-security info --json 会报告 SDK 和捆绑插件版本。这两个命令都不需要 Python。

发现命令并连接智能体

输出智能体可读的命令清单：

npx @openai/codex-security --llms

以 JSON 格式检查扫描参数架构：

npx @openai/codex-security scan --schema --format json

为 Bash 生成 shell 补全：

npx @openai/codex-security completions bash

对于相应的 shell，请将 bash 替换为 zsh 或 fish。

扫描结果支持 --format toon|json|yaml|jsonl 和 --full-output。此框架级 --format 与 --export-format 不同，后者用于选择从已完成扫描中导出的工件格式。全局命令帮助也会列出 md，但扫描结果不支持 Markdown 输出。

将 CLI 注册为 MCP 服务器：

npx @openai/codex-security mcp add

将 Codex Security 技能同步到你的智能体：

npx @openai/codex-security skills add

MCP 仅公开只读的 info 元数据命令。扫描、导出、身份验证、验证和修补仍只能通过 CLI 完成。

`codex-security scan`

对仓库、所选路径、已提交的更改或工作树运行扫描。

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time-hours HOURS]
                           [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh,max}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--dry-run] [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository 默认为当前目录。

选择扫描身份验证方式

使用默认选项 --auth auto 可自动选择凭据。如果 ChatGPT 登录和 OPENAI_API_KEY 或 CODEX_API_KEY 均可用，采用文本输出的交互式扫描会询问要使用哪个凭据。CI、JSON 和 JSONL 扫描以及其他没有交互式终端的扫描会使用环境 API key。试运行不会提示或加载凭据。

要使用已存储的凭据，请传入 --auth chatgpt：

npx @openai/codex-security scan . --auth chatgpt

要使用环境 API key，请传入 --auth api-key：

npx @openai/codex-security scan . --auth api-key

要将已存储凭据设为自动选择时的默认值，请运行 unset OPENAI_API_KEY CODEX_API_KEY。

使用 OpenRouter 或 Fireworks

使用其 API key 和显式模型选择 OpenRouter：

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

使用其 API key 和显式模型选择 Fireworks：

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

这两个提供商也都支持 bulk-scan。

使用 Amazon Bedrock

使用 --provider amazon-bedrock 选择 Amazon Bedrock，并通过 --model 指定显式 Bedrock 模型：

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

设置 AWS_REGION，并使用 AWS_BEARER_TOKEN_BEDROCK、标准 AWS 访问密钥、AWS 配置文件、Web 身份、容器凭据或默认 AWS 凭据链进行身份验证。Bedrock 扫描使用 AWS 凭据，而非 --auth、ChatGPT 登录或 OpenAI API key。scan 和 bulk-scan 均支持 --provider。

选择扫描目标

每次扫描请选择一种目标类型。

参数	说明
`--path PATH`	扫描相对于仓库的路径。可重复使用该标志以指定更多路径。
`--diff BASE`	扫描从 `BASE` 到 `--head` 的已提交更改。head 默认为 `HEAD`。
`--head HEAD`	为 `--diff` 设置 head 修订版本。
`--working-tree`	扫描相对于 `--base` 的暂存和未暂存更改。base 默认为 `HEAD`。
`--base BASE`	为 `--working-tree` 设置 base 修订版本。
`--mode {standard,deep}`	选择扫描模式。默认为 `standard`。

--path、--diff 和 --working-tree 互斥。--head 需要 --diff，--base 需要 --working-tree。深度模式支持仓库和路径目标。

差异和工作树扫描要求仓库参数为 Git 工作树根目录。所选引用必须存在于该检出中。

扫描整个仓库：

npx @openai/codex-security scan .

扫描所选路径：

npx @openai/codex-security scan . --path src --path tests

扫描已提交的更改：

npx @openai/codex-security scan . --diff origin/main --head HEAD

扫描暂存和未暂存的更改：

npx @openai/codex-security scan . --working-tree --base HEAD

对仓库运行更深入的审查：

npx @openai/codex-security scan . --mode deep

配置深度扫描

将以下选项与 --mode deep 配合使用，以控制工作进程并发数和运行时间：

参数	说明
`--workers N`	并发独立标准扫描工作进程的上限。默认为 `4`。
`--subagents N`	每个工作进程可用的子智能体数。默认为 `3`。
`--stop-after-no-new N`	连续 `N` 个已完成的工作进程扫描未发现新问题后停止。默认为 `4`。
`--max-discovery-runs N`	独立标准扫描总运行次数的上限。默认为 `40`。
`--max-time-hours HOURS`	工作进程执行时限（小时）。默认为 `96`；接受小数。

--subagents 接受零或正整数。--max-time-hours 接受不大于 96 的正数。其余选项要求正整数。这些选项不适用于标准扫描。

例如，使用两个工作进程，最多允许运行十次，并在 1.5 小时后停止工作进程执行：

npx @openai/codex-security scan . \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

达到时限后，扫描会停止未完成的工作进程，保留已完成的扫描结果，并将其聚合到最终报告中。如果没有工作进程完成源代码审查，扫描会记录覆盖范围不完整并返回退出代码 2。

在 ~/.codex/codex-security/config.toml 中设置持久默认值；设置 CODEX_HOME 时，也可在 $CODEX_HOME/codex-security/config.toml 中设置：

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

命令行选项会覆盖这些默认值。scan --workers 控制一次深度扫描内的独立标准扫描工作进程；bulk-scan --workers 控制并发仓库扫描。stop_after_consecutive_errors 只能在 TOML 文件中设置；其默认值为 3。

添加安全上下文

使用 --knowledge-base PATH 提供架构文档、威胁模型或安全策略。可重复使用该选项以指定更多文件或目录：

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

支持的文档包括 .md、.markdown、.txt、.pdf 和 .docx 文件。CLI 会递归搜索目录、拒绝链接输入路径、跳过链接目录条目，并将提取的文档内容排除在已保存的扫描结果之外。

添加扫描指令

要添加扫描指令，请通过 --scan-prompt-file 提供文本或 Markdown 文件。使用 --post-scan-prompt-file 可在成功扫描以及覆盖范围不完整或出错的扫描之后，在同一已验证会话中运行后续指令：

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

例如，使用扫描提示聚焦授权边界，并让后续步骤在扫描目录中写入新的 post-scan-summary.md。如果后续步骤失败，CLI 会报告警告并保留已完成的扫描。取消后或扫描达到成本上限时，不会运行后续步骤。

设置输出和策略选项

使用以下选项保留工件、保存先前结果或创建机器可读结果。

参数	说明
`--output-dir DIR`	将扫描工件写入外围 Git 工作树之外的私有目录。默认为持久 Codex Security 状态目录。
`--archive-existing`	将现有结果移至 `DIR.previous-<timestamp>-<id>`，并从空输出目录开始。需要 `--output-dir`。
`--fail-on-severity LEVEL`	当已完成扫描报告严重程度达到或超过 `critical`、`high`、`medium` 或 `low` 的发现时，返回退出代码 `1`。
`--patch`	在完整扫描后修复并验证所选发现。
`--patch-severity LEVEL`	修补严重程度达到或超过 `critical`、`high`、`medium` 或 `low` 的发现。默认为 `low`。
`--create-pr`	提交已验证的修补文件并创建 GitHub 拉取请求。需要 `--patch`。
`--max-cost USD`	当扫描的估算模型成本超过指定美元金额时停止扫描。
`--dry-run`	检查仓库、目标、知识库、输出目录和 Codex 配置，但不启动扫描。
`--headless`	显示纯文本进度，而非交互式扫描仪表板。
`--verbose`	将经过脱敏的生命周期、身份验证、进度和成本诊断信息输出到 stderr。
`--json`	将清单、发现、覆盖范围、路径和轮次元数据作为一个 JSON 文档输出。
`--format FORMAT`	将完整扫描结果输出为 `toon`、`json`、`yaml` 或 `jsonl`。
`--full-output`	使用默认结构化输出格式输出完整结果。

成本上限是估算值，而非严格的支出上限。已在进行的请求可能会在略微超过上限后完成。如果深度扫描在 Codex Security 聚合已完成工作进程的结果后达到上限，CLI 会封存可用结果，将覆盖范围标记为 partial，并返回退出代码 2。否则，它会返回 2，并将任何可用的部分输出留在磁盘上。

省略 --output-dir 时，结果会持久保存在 $CODEX_HOME/state/plugins/codex-security/scans/<repository> 下。CODEX_HOME 默认为 ~/.codex。设置 CODEX_SECURITY_STATE_DIR 可改为将结果保存在 $CODEX_SECURITY_STATE_DIR/scans/<repository> 下。这些目录可能包含源代码摘录和漏洞详情，因此应相应管理其权限和保留期限。

工作台将扫描历史记录保存在 $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3 中。设置 CODEX_SECURITY_STATE_DIR 也会移动工作台数据库。

输出目录必须位于所扫描目录及其任何外围 Git 工作树之外。扫描可以使用 --archive-existing 替换现有结果目录。

在重复使用输出目录之前保留先前结果：

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

扫描默认仅生成报告。在 CI 中添加 --fail-on-severity 以评估严重程度策略：

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

试运行会检查本地输入（包括知识库文档），但不会加载凭据、启动 Codex 或探测插件的 Python 解释器：

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

配置运行时

需要显式指定模型、解释器、插件或 Codex 配置值时，请使用运行时选项。

参数	说明
`--auth {auto,chatgpt,api-key}`	选择扫描凭据。默认为 `auto`。
`--provider {openai,openrouter,fireworks,amazon-bedrock}`	选择推理提供商。默认为 `openai`。
`--model MODEL`	选择模型。默认为 `gpt-5.6-sol`。OpenRouter、Fireworks 和 Amazon Bedrock 必须指定此项。
`--effort {minimal,low,medium,high,xhigh,max}`	选择模型的推理强度。默认为 `xhigh`。
`--plugin-path PATH`	使用 Codex Security 插件目录或 ZIP 覆盖捆绑插件。
`--python PATH`	为插件运行时选择 Python 解释器。
`--codex KEY=VALUE`	覆盖隔离的 Codex 配置值。值使用 TOML 语法。可重复使用该标志以指定更多值。

要在不写入 TOML 的情况下选择其他模型和推理强度：

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

对通过 --codex 传入的字符串值加引号，以便 TOML 解析器接收字符串：

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

`codex-security install-hook`

为当前仓库安装 Git 预提交安全检查：

npx @openai/codex-security install-hook

该检查会在每次提交前扫描暂存和未暂存的更改，并阻止高严重程度发现或扫描错误。它遵循 core.hooksPath，且不会替换现有的预提交脚本。需要时可设置不同的严重程度阈值：

npx @openai/codex-security install-hook . --fail-on-severity medium

`codex-security bulk-scan`

发现并扫描 GitHub 仓库，或从仓库 CSV 运行可恢复的扫描：

有关 GitHub 发现、CSV 清单、扫描活动结果和容器化扫描的完整指南，请参阅运行批量安全扫描。

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh,max}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

不带参数运行 npx @openai/codex-security bulk-scan 可交互式选择仓库。此流程需要登录 GitHub CLI。

在交互式发现期间选择模型和推理强度：

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

对于准备好的仓库列表，请提供 CSV 和 --output-dir：

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

CSV 必须包含 id、repository 和 revision 列。修订版本必须是完整提交哈希。可选的 scope、mode 和 prompt 列用于配置各个仓库：

id,repository,revision,scope,mode,prompt
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authorization boundaries.

使用 --knowledge-base PATH 在所有仓库之间共享安全文档。使用 --scan-prompt-file FILE 添加共享扫描指令； CSV 的 prompt 列会在该共享提示之后添加仓库专用指令。 --post-scan-prompt-file FILE 会在每次扫描后运行后续指令，包括覆盖范围不完整或出错的扫描。取消后或扫描达到成本上限时不会运行。

--workers 限制同时进行的仓库扫描数，默认为 4。--mode 默认为 standard，--max-attempts 默认为 1。设置 --max-attempts 可重试仓库或扫描错误。覆盖范围不完整的已完成扫描不会重试。其结果仍然可用，且命令会返回退出代码 2。

再次运行同一命令可从现有输出目录恢复。CLI 会跳过已完成的扫描，包括覆盖范围不完整的扫描。

有关容器化扫描活动，请参阅在 Docker 中运行批量扫描。

`codex-security scans`

查找已保存的扫描

列出当前目录的已保存扫描：

npx @openai/codex-security scans

列出其他仓库的扫描：

npx @openai/codex-security scans list /path/to/repository

查找存储在特定输出目录下的扫描：

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

检查或重复扫描

显示已保存扫描的结果和配置：

npx @openai/codex-security scans show SCAN_ID

添加 --show-linked-findings 以包含早期扫描中的发现链接。

使用原始配置对当前检出重新运行扫描：

npx @openai/codex-security scans rerun SCAN_ID

重新运行需要原始扫描所记录的插件版本。如果已安装版本不同，命令会停止，而不会使用其他插件运行。

检查已保存的扫描日志

读取扫描及其工作进程已保存的完整会话事件。这些日志未经脱敏，可能包含源代码或凭据，因此请在共享前进行审查：

npx @openai/codex-security scans logs SCAN_ID

添加 --json 可获得包含完整信息的机器格式结果。

匹配和比较发现

比较两次扫描，以查找新增、持续存在、重新出现、已解决和未知的发现：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较会自动匹配具有相同根本原因的发现，并复用已保存的匹配。要显式保存匹配，请使用 scans match：

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

如果后一次扫描覆盖范围不完整或未覆盖发现的原始位置，该发现即为未知。需要重新计算现有匹配时，请向 match 添加 --force。

要匹配当前仓库的所有已完成扫描，包括来自其他检出的扫描：

npx @openai/codex-security scans match --all

即使重新运行相同配置，扫描结果也可能不同。匹配和比较会跟踪变化；它们不会使结果具有确定性，也无法证明漏洞已不存在。对于安全关键发现，请使用 validate 根据当前代码重新检查。

`codex-security findings`

列出当前仓库所有扫描中的未解决发现：

npx @openai/codex-security findings list

传入仓库路径以检查其他检出：

npx @openai/codex-security findings list /path/to/repository

添加 --json 以获得结构化输出。列表会标识最新扫描中出现的发现，以及未在该扫描中确认的早期发现。

请注意，早期发现会一直保持未解决状态，直至被解决或驳回（未出现在最新扫描中并不视为已修复的证据）。

要将已审查的发现记录为误报：

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

检查已保存扫描以确定该发现的具体实例：

npx @openai/codex-security scans show SCAN_ID

记录该误报的具体原因：

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

原因不能为空。Codex Security 会为该仓库保存此决定，并将其作为上下文提供给未来扫描。每次扫描都会独立重新检查当前源代码、控制措施和可达性。先前的决定不会抑制某项规则、路径或漏洞类别。

`codex-security export`

从已完成并封存的扫描中导出 CSV、JSON 或 SARIF。导出会在写入输出前验证扫描工件，且不会触及 Codex 运行时和凭据。

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir 是已完成的扫描目录。

参数	说明
`--export-format {csv,json,sarif}`	选择导出格式。默认为 `sarif`。
`--output FILE\|-`	将所选格式写入文件或 stdout。默认为当前目录中的文件。
`--source-root PATH`	使用仓库检出向 SARIF 添加源代码行指纹。
`--python PATH`	为捆绑的导出程序选择 Python 解释器。

--source-root 仅适用于 --export-format sarif。JSON 会保留已封存的发现文档。CSV 包含可移植的发现列，但不包含本地工作台分类状态。

如果不指定 --output，CLI 会将 SARIF 写入 results.sarif、将 JSON 写入 findings.json，并将 CSV 写入当前工作目录中的 findings.csv。导出内容可能包含源代码摘录和漏洞详情。请在仓库之外运行该命令，或通过 --output 传入所扫描检出之外的私有路径。

将 SARIF 写入文件：

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

将 SARIF 写入 stdout：

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

将发现导出为 JSON：

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

将发现导出为 CSV：

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

`codex-security publish scan`

将已完成扫描中的每项发现发布到 Linear：

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

SCAN_DIR 必须包含已完成并封存的扫描。在交互式终端中可省略它，以从本地扫描历史记录中选择已完成的扫描。创建议题还要求扫描及其发现在本地扫描历史记录中存在。试运行会验证已封存工件，但不执行此持久性检查。

参数	说明
`--to linear`	发布到 Linear。此参数为必填项。
`--linear-team TEAM_ID`	选择 Linear 团队。省略时使用 `CODEX_SECURITY_LINEAR_TEAM`；两者必须提供其一。
`--project PROJECT_ID`	选择 Linear 项目。省略时使用 `CODEX_SECURITY_LINEAR_PROJECT`。如果两者均未设置，议题将直接在团队中创建。
`--linear-api-key KEY`	使用 Linear 个人 API key 直接发布。省略时使用 `CODEX_SECURITY_LINEAR_API_KEY`。
`--linear-assignee EMAIL_OR_USER_ID`	按电子邮件地址或 Linear 用户 ID 分配所创建的议题。需要 `--linear-api-key` 或 `CODEX_SECURITY_LINEAR_API_KEY`。省略时议题保持未分配。
`--dry-run`	准备议题负载，但不启动 Codex、不联系 Linear、不创建议题，也不写入发布状态。
`--json`	将结构化发布结果写入 stdout。进度仍输出到 stderr。

每次非试运行调用都会尝试为每项发现创建新议题。再次发布同一扫描不会匹配、更新或复用现有议题。如果某些发现发布失败，命令会保留已成功创建的议题并返回退出代码 2。使用 --json 时，请先审查 created 和 failed 结果再重试，以免产生重复项。

发布前预览议题负载：

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

使用已连接的 Linear 应用发布

如果没有 Linear API key，该命令会使用你的现有配置和已连接的 Linear 应用启动 Codex。发布前，请登录并将 Linear 连接到你的 Codex 账户：

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

使用 Linear API key 发布

提供 --linear-api-key 或 CODEX_SECURITY_LINEAR_API_KEY 会直接通过 Linear API 发布，且不会启动 Codex。除非选择受理人，否则直接发布会让议题保持未分配状态：

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

命令行值会覆盖对应的环境变量。对于 API key，建议使用 CODEX_SECURITY_LINEAR_API_KEY，而非 --linear-api-key，因为命令行参数可能出现在 shell 历史记录和进程列表中。

`codex-security validate` 和 `codex-security patch`

检查候选发现是否有效：

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

使用捆绑的修复技能生成修复：

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

每个位置参数均接受字面文本或文件路径。这些输入以当前目录为基准。修复后或后续扫描不再报告某项发现时，使用 validate 重新检查该发现。仅比较扫描无法证明修复有效。

使用 --effort 为任一命令选择推理强度：

npx @openai/codex-security validate "Possible SQL injection" --effort high

扫描后修补发现

使用 scan --patch 在完整扫描后修复发现。这要求 @openai/codex-security 版本不低于 0.1.15。默认严重程度阈值为 low。此命令选择高危和严重发现：

npx @openai/codex-security scan . --patch --patch-severity high --json

已验证和已修复的发现不会触发 --fail-on-severity。

修补已保存的发现

传入发现或实例 ID 以修补其原始仓库，或从已保存扫描中选择发现：

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest 会选择当前仓库最新完成的扫描。已保存发现命令支持 --json；字面文本和文件输入不支持。

添加 --create-pr 可仅提交已验证的修补文件，并使用 GitHub CLI 创建拉取请求：

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

如果推送或拉取请求失败，请从同一仓库运行输出的 patch --resume-pr BRANCH 命令以重试。

修补 Linear 议题

为个人 API key 设置 CODEX_SECURITY_LINEAR_API_KEY 或 LINEAR_API_KEY，或者为 OAuth 令牌设置 LINEAR_ACCESS_TOKEN。建议使用环境变量，而非 --linear-api-key KEY，以免密钥进入 shell 历史记录。

按 ID 或 URL 导入议题。重复使用 --linear-issue 可选择多个议题：

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

使用 --linear-project 选择项目的未解决议题。添加 --linear-filter 可缩小选择范围：

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

除非过滤器设置 state，否则 CLI 会排除已完成和已取消的议题。它不会更改 Linear 议题。

`codex-security login`、`logout` 和 `info`

交互式登录：

npx @openai/codex-security login

在远程或无头计算机上使用设备身份验证：

npx @openai/codex-security login --device-auth

检查当前登录：

npx @openai/codex-security login status

移除已存储的登录信息：

npx @openai/codex-security logout

通过 stdin 传入 API key 以进行存储：

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

存储企业访问令牌：

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

检查只读 SDK 和捆绑插件元数据：

npx @openai/codex-security info --json

将 CLI 公开为 MCP 服务器时，info 是唯一可用的命令。扫描、导出、发布、登录、验证和修补仍只能通过 CLI 完成。

读取扫描输出

默认情况下，扫描会将进度、完成摘要和错误发送到 stderr，而不会将完整扫描结果写入 stdout。请求 --json、 --format 或 --full-output 可将结构化扫描结果发送到 stdout。

交互式终端会显示实时仪表板，其中包含当前扫描阶段、已审查文件、活动、令牌用量和估算成本。CI 和重定向的输出使用纯文本进度。添加 --headless 可在交互式终端中使用纯文本进度：

npx @openai/codex-security scan . --headless

仪表板还会显示实时会话详情。这些内容未经脱敏，可能包含源代码或凭据。请在共享前进行审查。

详细诊断

添加 --verbose 可将经过脱敏的生命周期、身份验证、进度和成本诊断信息输出到 stderr：

npx @openai/codex-security scan . --verbose

设置 CODEX_SECURITY_LOG_LEVEL=debug 可在不使用该标志的情况下启用相同诊断。未设置 CODEX_SECURITY_LOG_LEVEL 时，LOG_LEVEL=debug 也会启用诊断。

完成摘要

已完成扫描会将仓库的未解决发现数量、严重程度明细、覆盖范围、用时、报告路径和结果目录写入 stderr。若有相关信息，还会包含令牌用量和估算成本：

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

信息级发现计入摘要总数。严重程度策略只评估当前扫描中的 critical、high、medium 和 low 发现，不评估仓库总数中显示的早期发现。

JSON 输出

scan --json 会向 stdout 写入一个完整的 JSON 文档。其顶层结构如下：

manifest
repositoryFindings
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
cost
turn
  id
  status
  durationMs
  finalResponse
  usage

进行修补时，JSON 输出还会包含修补结果以及创建的任何拉取请求。

进度、完成摘要、归档通知和错误仍输出到 stderr。当严重程度策略返回退出代码 1 或覆盖范围不完整返回退出代码 2 时，已完成扫描仍会输出完整的 JSON 结果。

扫描工件

已完成扫描会将可读报告和结构化工件保存在一起：

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

各结构化文件用途不同：

文件	内容
`scan-manifest.json`	扫描标识、状态、目标、范围、生成方和已封存工件记录。
`findings.json`	发现标识符、严重程度、置信度、分类、位置、证据、验证、数据流、可达性和修复措施。
`coverage.json`	已审查的表面、排除项、延后工作、未决问题和覆盖完整性。
`report.md`	可读扫描报告。
`artifacts/`	辅助扫描工件。
`exports/results.sarif`	扫描期间生成的 SARIF（如有）。

覆盖完整性有三个值：

complete：扫描记录所选范围的完整覆盖。
partial：扫描记录延后工作或其他覆盖限制。
unknown：扫描将覆盖完整性报告为未知。

在将覆盖范围用作安全决策的证据前，请审查延后的表面、明确的排除项和未决问题。

退出代码和信号

CLI 使用以下退出代码：

退出代码	条件
`0`	扫描以完整覆盖结束并通过严重程度策略；批量扫描或发布无失败完成；或其他命令成功。
`1`	已完成扫描报告了严重程度达到或超过所配置级别的发现。
`2`	CLI 遇到输入、运行时或导出错误；扫描覆盖范围不完整；批量扫描中的仓库出错；或发布中有一项或多项发现失败。
`130`	Ctrl-C 中断了扫描或发布。
`143`	SIGTERM 终止了扫描或发布。

任何覆盖范围为 partial 或 unknown 的扫描都会返回 2，即使没有严重程度策略也是如此。请求结构化输出时，已完成的扫描和部分完成的发布仍会将可用结果写入 stdout。CLI 会在中断或运行时错误后输出所有部分输出的位置。

本地扫描权限

CLI 和 SDK 扫描使用你的本地操作系统权限运行。每次扫描都使用 codex_security_scan 文件系统配置文件，并将 approvalPolicy 设置为 "never"。该配置文件允许读取本地文件系统，并写入工作区根目录和所选扫描状态目录。扫描不会停下来请求交互式批准。

通过 CLI --codex 或 SDK codexOverrides 提供的设置（包括 approval_policy、sandbox_mode 和文件系统权限）无法替换或限制这些扫描控制。主机和网络限制仍然适用。

扫描和工作台进程可能会继承你的环境，包括无关的 API 令牌和云凭据。仅扫描你信任且有权评估的仓库，并且只提供扫描所需的凭据。

身份验证和先决条件

设置 OPENAI_API_KEY 或 CODEX_API_KEY、使用 npx @openai/codex-security login 登录，或使用现有的基于文件的 Codex 登录。对于 OpenRouter 或 Fireworks，请设置相应提供商的 API key 并选择模型。对于 Amazon Bedrock，请改用 Bedrock API key 或标准 AWS 凭据链。

有关凭据选择，请参阅选择扫描身份验证方式。

对于 CI，请将 API key 的作用域限制在扫描步骤，并使用可信工作流。

CLI 需要 Node.js 22（22.13.0 或更高版本）、24 或 26。扫描、批量扫描、导出、扫描历史记录和已保存发现还需要 Python 3.10 或更高版本。 Python 3.10 还需要 tomli。将 --python 与 scan、bulk-scan 或 export 配合使用，或者为任何由 Python 支持的命令设置 PYTHON。

接下来可阅读 CLI 快速入门、批量扫描指南、CLI 常见问题、CI 指南或 TypeScript SDK 指南。

纯文本别名

--output FILE|-

命令概览

发现命令并连接智能体

codex-security scan

选择扫描身份验证方式

使用 OpenRouter 或 Fireworks

使用 Amazon Bedrock

选择扫描目标

配置深度扫描

添加安全上下文

添加扫描指令

设置输出和策略选项

配置运行时

codex-security install-hook

codex-security bulk-scan

codex-security scans

查找已保存的扫描

检查或重复扫描

检查已保存的扫描日志

匹配和比较发现

codex-security findings

codex-security export

codex-security publish scan

使用已连接的 Linear 应用发布

使用 Linear API key 发布

codex-security validate 和 codex-security patch

扫描后修补发现

修补已保存的发现

修补 Linear 议题

codex-security login、logout 和 info

读取扫描输出

详细诊断

完成摘要

JSON 输出

扫描工件

退出代码和信号

本地扫描权限

身份验证和先决条件

纯文本别名

`codex-security scan`

`codex-security install-hook`

`codex-security bulk-scan`

`codex-security scans`

`codex-security findings`

`codex-security export`

`codex-security publish scan`

`codex-security validate` 和 `codex-security patch`

`codex-security login`、`logout` 和 `info`