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`