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`