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 server。
`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 server：

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

在 scan 或 bulk-scan 中使用 --provider amazon-bedrock 和 Bedrock 模型 ID。 AWS 开通模型访问权限后，扫描会使用 AWS 凭据，无需 --auth、OpenAI 登录或 OpenAI API key。

Daybreak Blue 和 Daybreak Red

Daybreak Blue 和 Daybreak Red 需要获得 Trusted Access for Cyber 批准。如需申请访问权限，请提交企业访问申请，或联系你的 OpenAI 客户团队。获批后，请与 AWS 客户团队合作，在 Amazon Bedrock 上开通模型访问权限。

Daybreak Red 批准不包含 GPT-5.6-Cyber 访问权限。GPT-5.6-Cyber 需要单独获得美国政府（USG）批准。在 Amazon Bedrock 上开通 GPT-5.6-Cyber 之前，请联系你的 OpenAI 客户团队申请这项额外批准。请参阅 Daybreak 访问要求。

访问权限	Bedrock 模型 ID	AWS 区域
Daybreak Blue	`openai.gpt-daybreak-blue-5.6-sol`	`us-east-2`
Daybreak Red	`openai.gpt-5.6-cyber`	`us-east-2`

有关可用性，请查看 AWS 的 Daybreak Blue 和 Daybreak Red 模型说明。

要使用 Daybreak Blue 扫描，请将 <aws-profile-name> 替换为有权访问 Daybreak Blue 模型的 AWS 配置档案：

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-daybreak-blue-5.6-sol --effort high

要使用 Daybreak Red 扫描，请选择有权访问 GPT-5.6-Cyber 的 AWS 配置档案。它可能与你用于 Daybreak Blue 的配置档案不同：

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-cyber --effort high

你也可以使用 AWS_BEARER_TOKEN_BEDROCK 或标准 AWS 凭据链进行身份验证。临时访问密钥还需要 AWS_SESSION_TOKEN。请在运行扫描的同一个 shell 或 CI 作业中设置凭据和 AWS_REGION。

本地结果和访问检查

已保存的本地报告、scans show 和 export 无需云端凭据即可使用。将发现的问题上传至 Codex Security Cloud，需要单独通过 ChatGPT 登录，并具有目标位置的访问权限。

info 和 scan --dry-run 不会检查 AWS 凭据或模型访问权限。请运行一次扫描来检查访问权限。发生 AWS 身份验证或拒绝访问错误时，请检查凭据、区域和模型权限。

Bedrock 版本支持情况

@openai/codex-security@0.1.31 支持 Amazon Bedrock 扫描。对于上述 Daybreak Blue 和 Daybreak Red 模型 ID，此版本不提供费用估算，也不支持 --max-cost。

检查已安装的软件包和随附的 Codex 版本：

npx @openai/codex-security --version
npx @openai/codex-security info --json

使用 npx @openai/codex-security scan --help 查看已安装版本提供的选项。

选择扫描目标

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

参数	说明
`--path PATH`	扫描相对于仓库的路径。可重复使用该标志以指定更多路径。
`--diff BASE`	扫描从 `BASE` 到 `--head` 的已提交更改。head 默认为 `HEAD`。
`--head HEAD`	为 `--diff` 设置目标修订版本。
`--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

达到时间上限时，扫描会停止尚未完成的工作进程，保留已完成的扫描结果，并将其汇总到最终报告中。请查看报告，了解已审查的范围和暂缓的工作。仅达到截止时间并不能决定退出码；退出码由执行状态和严重程度策略决定。

在 ~/.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 PR。需要 `--patch`。
`--max-cost USD`	当扫描的估算模型成本超过指定美元金额时停止扫描。
`--dry-run`	检查仓库、目标、知识库、输出目录和 Codex 配置，但不启动扫描。
`--headless`	显示纯文本进度，而非交互式扫描仪表板。
`--verbose`	将经过脱敏的生命周期、身份验证、进度和成本诊断信息输出到 stderr。
`--json`	将清单、发现、覆盖范围、路径和轮次元数据作为一个 JSON 文档输出。
`--format FORMAT`	将完整扫描结果输出为 `toon`、`json`、`yaml` 或 `jsonl`。
`--full-output`	使用默认结构化输出格式输出完整结果。

费用上限是估算值，并非严格的支出上限。已经在进行中的请求完成时，费用可能略高于上限。如果深度扫描在 Codex Security 汇总已完成工作进程的结果后达到上限，CLI 可以将完整结果定稿，并报告预算警告。此时返回 0；如果发现项达到已配置的严重程度阈值，则返回 1。如果无法生成有效的完整结果，则返回 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 的情况下选择其他模型和推理强度，请选择你的凭据有权访问的模型。如果你使用 ChatGPT 登录，请在使用这些示例前查看 GPT-6.1 Sol 可用性：

npx @openai/codex-security scan . --model gpt-6.1-sol --effort medium

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

npx @openai/codex-security scan . --codex 'model="gpt-6.1-sol"'

`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。

要在交互式发现过程中选择模型和推理强度，请使用你的凭据有权访问的模型。请参阅使用 ChatGPT 登录时 GPT-6.1 Sol 的可用性：

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

对于准备好的仓库列表，请提供 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 可在仓库或扫描出错时重试。已完成的扫描不会因覆盖缺口或违反严重程度策略而重试。这些扫描的结果仍可使用。

再次运行相同命令，即可从现有输出目录恢复。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

如果发现项所在路径被排除，或匹配关系不确定，则该发现项为未知。如果后一次扫描未在其扫描过的代码中发现该项，则该项为未观测到。只有明确以已修复为由关闭的发现项才算已解决。需要重新计算现有匹配时，请将 --force 添加到 match。

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

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 创建 PR：

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

如果推送或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 server 时，info 是唯一可用的命令。扫描、导出、发布、登录、验证和修补仍只能通过 CLI 完成。

读取扫描输出

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

交互式终端会显示实时仪表板，其中包含当前扫描阶段、已评审文件、活动、token 用量和估算成本。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。如果有相关数据，还会包含 token 用量和预估费用。例如：

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  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 输出还会包含修补结果以及创建的任何PR。

进度、完成摘要、归档通知和错误仍输出到 stderr。即使严重程度策略返回退出码 1，已完成的扫描仍会输出完整的 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（如有）。

读取 scan.status（位于 scan-manifest.json 中）可查看执行状态：completed、 failed、canceled 或 interrupted。新结果不包含 coverage.completeness。查看推迟审查的范围、明确排除的内容以及尚待解答的问题（位于 coverage.json 中），以了解扫描审查了哪些内容。

退出代码和信号

CLI 使用以下退出代码：

退出码	条件
`0`	扫描或批量扫描任务已完成并通过严重程度策略检查，发布已完成且没有失败项，或其他命令执行成功。
`1`	已完成的扫描或批量扫描任务报告了严重程度达到或超过配置阈值的发现。
`2`	发生输入、执行、结果完整性、必需输出或导出错误，或发布中有一个或多个发现发布失败。
`130`	Ctrl-C 中断了扫描或发布。
`143`	SIGTERM 终止了扫描或发布。

覆盖范围缺口不会改变已完成扫描的退出码，也不会绕过其严重程度策略。退出码 0 并不意味着每个文件都已接受审查。请求结构化输出时，已完成的扫描和部分成功的发布仍会将可用结果写入 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 24 或 26，或 22.13.0 及以上的 Node.js 22。扫描、批量扫描、导出、扫描历史记录和已保存发现还需要 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

Daybreak Blue 和 Daybreak Red

本地结果和访问检查

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`