Claude CLI 指令與旗標速查表：工作階段、權限模式到 CI 一次看懂

Claude CLI 是什麼？就是 Claude Code 的 claude 命令

Claude CLI 指的就是 Claude Code 安裝到你 PATH 上的 claude 命令，不是另一套獨立的 claude.ai 工具。在終端機輸入 claude 會開啟互動式的工作階段（session）。加上 -p 則變成非互動的列印模式（print mode），可以直接寫進腳本或 cron 排程。

這份速查表不照字母排列，而是依「你想做什麼」把大約 20 個指令與旗標（flag）分組。內容對照 2026 年 10 月 19 日讀取的官方 CLI 參考文件。同一天，npm 上 @anthropic-ai/claude-code 的最新版本是 2.1.303。下文凡是標了最低版本的旗標，都是官方文件寫明的版本要求。

使用前提只有一個：Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳號。免費的 claude.ai 方案不包含 Claude Code。你也可以透過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 等第三方供應商使用。訂閱登入和 API 金鑰計費差在哪裡，請看 Claude Code 該用訂閱登入還是 API 金鑰，這裡不重複說明方案內容。

在 VPS 上安裝 Claude CLI 並完成第一次登入

在 macOS、Linux 和 WSL 上，官方的原生安裝方式是這一行：

curl -fsSL https://claude.ai/install.sh | bash

安裝完成後，官方文件要你先開一個新的終端機視窗，再執行：

claude --version

安裝正常的話，這一行會印出一個版本號。除了原生安裝，也有 Homebrew、WinGet、apt、dnf、apk 和 npm 等途徑。要注意的是，原生安裝會在背景自動更新，而 Homebrew、WinGet、apt、dnf 和 apk 的安裝不會自動更新。

在 Linux 上，官方列出的系統需求是 Ubuntu 20.04 以上、Debian 10 以上或 Alpine 3.19 以上，記憶體 4 GB 以上，處理器為 x64 或 ARM64，並且需要網路連線。所以挑 VPS 方案時，記憶體不要低於 4 GB。

第一次執行 claude 時，它會嘗試開啟瀏覽器讓你登入。VPS 通常沒有圖形介面，所以這一步要換個做法：按 c 複製登入網址，在自己電腦的瀏覽器打開，完成後把登入碼貼回終端機的提示。官方文件提到，透過 SSH 連線時這是很常見的情況。Linux 上桌面版和 CLI 的差別，可以參考 在 Linux 上使用 Claude 桌面版與命令列。

怎麼開始，又怎麼回到上次的工作階段？

這一組是每天最常用的指令：

claude
claude "explain this project"
claude -c
claude -c -p "query"
claude -r "auth-refactor" "Finish this PR"
claude -n "my-feature-work"

claude 開啟互動式工作階段。claude "explain this project" 也是開啟互動式工作階段，只是先帶入第一句提示，所以 Claude 一進來就開始工作。

-c（--continue）會載入目前目錄中最近的對話。它有一個常被忽略的細節：它會跳過用 claude -p 或 Agent SDK 建立的工作階段，也會跳過第一句提示是 /loop 的工作階段。所以你用腳本跑完一次 claude -p 之後，再打 claude -c，接上的不會是腳本那一次。要把這些工作階段也算進去，請用 claude -p --continue。claude -c -p "query" 則是在最近的對話上再問一句，並以非互動方式印出結果。

-r（--resume）依 ID 或名稱恢復特定工作階段。不給參數就會出現互動式的選單讓你挑。它也接受工作階段 .jsonl 紀錄檔的絕對路徑。用 ID 搜尋時，它會先找目前專案和它的 git worktree，再找這台機器上的其他所有專案。v2.1.223 之前只會找目前專案和它的 worktree，所以在舊版上，從別的專案目錄恢復工作階段會找不到。

-n（--name）替工作階段取一個顯示名稱。這個名稱會出現在 /resume 的清單和終端機標題上。取了名字之後，就能用名稱恢復，不必記一長串 ID：

claude --resume my-feature-work

工作階段存在哪裡、歷史紀錄怎麼找，在 Claude Code 恢復工作階段與歷史紀錄 有完整說明。

在無頭 VPS 上寫腳本：-p 列印模式怎麼用？

-p（--print）讓 Claude Code 以非互動方式執行：讀入提示，做完工作，印出結果，然後結束。這是在沒有螢幕的伺服器上自動化的基礎。

claude -p "query"
cat error.log | claude -p "explain these errors"

透過管線（pipe）送進去的標準輸入上限是 10MB。超過這個大小，命令會以非零的結束代碼退出並顯示錯誤。所以很大的日誌檔要先用 tail 或 grep 裁短，再送進去。

輸出格式用 --output-format 指定，共有三種：

claude -p "query" --output-format text
claude -p "query" --output-format json
claude -p "query" --output-format stream-json --verbose --include-partial-messages

text 是預設值，就是純文字。json 是結構化的 JSON，包含結果、工作階段 ID 和其他中繼資料，其中也有 total_cost_usd 欄位。這個費用數字是用戶端的估算，不是帳單。stream-json 是逐行輸出的 JSON，適合即時串流。官方範例中，stream-json 會搭配 --verbose，要逐個 token 串流時再加上 --include-partial-messages。

結束代碼（exit code）是腳本判斷成敗的依據。官方文件寫明：成功時結束代碼為 0，執行失敗時為非零。用 SIGTERM 中止一次 claude -p 執行時，結束代碼是 143。還有一點要小心：如果執行中缺少認證，這個訊息會被當成結果印到標準輸出。所以腳本不能只看標準輸出就當作答案，最好先用後面介紹的 claude auth status 確認登入狀態。

替無人看管的執行設上限

claude -p --max-turns 3 "query"
claude -p --max-budget-usd 2 "query"
claude -p --permission-prompts none "query"

--max-turns 限制代理（agent）的回合數，只能在列印模式使用。達到上限時，命令會以錯誤結束。預設沒有上限，所以無人看管的腳本最好自己設一個。

--max-budget-usd 在估算花費達到指定金額時停止執行，同樣只能在列印模式使用。它比對的是用戶端的費用估算，這個估算可能和實際帳單不同。子代理（subagent）的花費也會算進去。花費可能超過上限，所以官方建議保留一些餘裕。另外，透過 --continue 或 --resume 帶回來的先前執行的累計金額，不算進這次的上限。相關的上限執行行為需要 v2.1.217 以上。

--permission-prompts none 讓 Claude Code 在列印模式中直接拒絕任何權限提示，而不是等待一個不存在的宿主程式回應。預設值是 host。這個旗標需要 v2.1.259 以上，舊版會回報未知選項的錯誤。在沒有宿主的一般 -p 執行中，權限提示本來就會被拒絕，這個旗標額外告訴 Claude 不要重試那些被拒絕的動作。權限規則、PermissionRequest hook 和權限模式仍然會先做決定。

--bare：在陌生的程式庫裡更安全

export ANTHROPIC_API_KEY="<your API key>"
claude --bare -p "summarize the README"

--bare 會跳過自動探索，也就是不載入 hooks、skills、自訂指令、子代理、外掛、MCP 伺服器、自動記憶和 CLAUDE.md。官方把它列為腳本與 SDK 呼叫的建議模式，並表示未來版本會讓它成為 -p 的預設行為。相關限制在 v2.1.286 起完整生效。

它和登入方式有直接衝突。在 bare 模式下，Claude Code 從不讀取 OAuth 憑證或系統鑰匙圈，也不讀 CLAUDE_CODE_OAUTH_TOKEN。所以要用 ANTHROPIC_API_KEY 或 apiKeyHelper 提供認證。

為什麼要在 VPS 上特別注意這一點？因為不加 --bare 的 -p 工作階段，會執行專案 .claude/settings.json 裡的 hooks，並連線 .mcp.json 裡列出的伺服器。即使那個資料夾你從來沒有信任過，也不會出現工作區信任對話框。這代表你 git clone 一個陌生的程式庫，再對它跑 claude -p，就等於讓那個程式庫的作者在你的伺服器上執行指令。對來源不明的程式碼，請用 --bare。

怎麼控制 Claude 能做什麼：權限模式（permission mode）

--permission-mode 決定 Claude 哪些動作不必問你就能執行。可用的值有六個：

• default：只有讀取不必詢問。介面上把這個模式叫做 Manual，v2.1.200 起也可以寫成 manual。
• acceptEdits：讀取、編輯檔案，以及 mkdir、touch、mv、cp 這類常見的檔案系統指令。
• plan：只讀取。在可以使用自動模式的環境中，還包括分類器核准的指令。
• auto：所有動作，但背景有安全檢查。
• dontAsk：工作目錄中的讀取，加上事先核准的工具。任何原本會跳出提示的動作都直接拒絕。
• bypassPermissions：所有動作。官方文件標註「只限隔離的容器和虛擬機」。

claude --permission-mode plan
claude --permission-mode auto
claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

腳本裡請一定明確指定模式。原因是 -p 執行的起始模式不是固定的。在會抓取功能旗標的工作階段中，它從 default 開始。在不抓取的工作階段中，例如使用第三方供應商或關閉了遙測，v2.1.285 以上會從 auto 開始，更早的版本則是 default。互動式終端機和 VS Code 的工作階段從 v2.1.283 起都從 auto 開始。同一個腳本換一台機器，行為就可能不同，所以要自己寫明。

dontAsk 適合 CI，因為它不會停下來等人。它不在 Shift+Tab 的切換循環裡，只能用 --permission-mode dontAsk 設定。

自動模式（auto mode）適用所有方案，但對模型有要求。在 Anthropic API 上需要 Opus 4.6 以上、Sonnet 4.6 以上、Haiku 5.5 或 Fable 模型。Team 和 Enterprise 的管理員可以用 permissions.disableAutoMode 關閉它。無法使用時，要求自動模式的工作階段會以 Manual 開始。官方也提醒：自動模式減少了提示，但不保證安全。分類器怎麼判斷、哪些情況仍會詢問，請看 Claude Code 自動模式與權限設定。

--allowedTools 和 --disallowedTools

claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"
claude -p "review my changes" --allowedTools "Bash(git diff *)" "Read"
claude --disallowedTools "Bash(rm *)"
claude --disallowedTools "mcp__*"

--allowedTools 列出不必詢問就能執行的工具。--disallowedTools 是拒絕規則。兩者的寫法有一個關鍵差別。在 --disallowedTools 裡只寫工具名稱，例如 "Edit"、"*" 或 "mcp__*"，會把整個工具從 Claude 的上下文中拿掉。寫成 Bash(rm *) 這種限定範圍的規則，則保留工具，只拒絕符合的呼叫。

結尾的 * 代表前綴比對，而且 * 前面的空格有意義。Bash(git diff *) 允許以 git diff 開頭的指令。請照官方的寫法複製，不要隨手刪掉那個空格。如果你要限制的是「有哪些工具存在」，而不是「哪些工具免詢問」，請改用 --tools。另外，在自動模式的執行中，單獨一個 Bash 的允許項目會被丟棄。

拒絕規則在每一種模式都有效，包括 bypassPermissions。允許規則在 bypassPermissions 中則沒有作用，因為那個模式本來就全部放行。

為什麼 --dangerously-skip-permissions 只能用在可以丟掉的機器？

--dangerously-skip-permissions 等同於 --permission-mode bypassPermissions。它不是另一個比較溫和的選項。

官方文件說，這個模式只能用在隔離的環境中，例如容器、虛擬機，或沒有網路連線的開發容器，也就是 Claude Code 無法傷害宿主系統的地方。它對提示詞注入（prompt injection）和非預期的動作沒有任何防護。少數動作仍會詢問，例如 ask 規則和刪除關鍵路徑的 rm。在 -p 執行中，這些仍會詢問的呼叫會直接被拒絕。

在 Linux 和 macOS 上，它拒絕以 root 或 sudo 身分啟動，並顯示這行訊息：

--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons

在系統認得的沙箱裡，這項檢查會被略過。你的 VPS 如果存著 SSH 金鑰、資料庫或正式環境的設定，它就不是「可以丟掉的機器」。在這種伺服器上，請用 dontAsk 搭配 --allowedTools，或用自動模式。

模型與思考力度：--model、--effort、--fallback-model

claude --model opus
claude --model claude-sonnet-5
claude --effort high
claude --fallback-model sonnet,haiku

--model 接受別名或完整的模型名稱。sonnet 是最新的 Sonnet，opus 是最新的 Opus，haiku 是快速的 Haiku，fable 是你所用供應商的 Fable 模型。另外還有 best、opusplan、sonnet[1m] 和 opus[1m]。別名指向的是「最新」的模型，所以需要固定模型時，請寫完整名稱。

--effort 設定思考力度，選項有 low、medium、high、xhigh、max 和 ultracode。可用的等級取決於模型，ultracode 需要 v2.1.203 以上。這個旗標只覆寫本次工作階段的設定，不會保存下來。預設值多半是 high，但 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 medium，Opus 4.7 預設為 xhigh。

--fallback-model 在主要模型過載或無法使用時切換到備用模型。它接受以逗號分隔的清單，依序嘗試，最多三個模型，多出來的會被忽略。切換只對目前這一回合有效，下一則訊息會先再試主要模型。認證、計費、速率限制、請求大小和傳輸錯誤都不會觸發切換，所以額度用完時，它不會改用備用模型。這個旗標會覆寫 fallbackModel 設定。

怎麼讓安裝保持健康：更新、固定版本與診斷

claude update
claude install stable
claude install 2.1.303
claude doctor

claude update 更新到最新版本。根據官方文件，安裝了新版時它會回報 Successfully updated from <old version> to version <new version>，已經是最新版時則回報 Claude Code is up to date (<version>)。

claude install 接受版本號、stable 或 latest，預設是 latest。很多教學說 claude install stable 可以「固定版本」，這並不正確。stable 是一個發布頻道：它提供的版本通常大約一週前發布，並跳過有重大問題的版本。安裝時選的頻道會成為之後自動更新的預設頻道，所以 stable 仍會繼續前進。autoUpdatesChannel 設定也可以選擇頻道。

真的要固定在某一版，請安裝明確的版本號，再關掉背景自動更新：

claude install 2.1.303
echo 'export DISABLE_AUTOUPDATER=1' >> ~/.bashrc

DISABLE_AUTOUPDATER 只停止背景更新，不會阻擋你手動執行 claude update 或 claude install。要封鎖所有更新途徑，用 DISABLE_UPDATES。minimumVersion 設定只是最低版本的下限，不是固定版本。還有一點要記得：新推出的模型可能需要比 stable 頻道更新的 Claude Code 版本。

claude doctor 在終端機印出唯讀的安裝與設定診斷，不會啟動工作階段。內容包括安裝狀態、設定檔的驗證錯誤和 Remote Control 的使用資格。它也會顯示最近一次更新的結果，以及自動更新是否開啟。工作階段裡的 /doctor 則是可以套用修正的檢查。自動更新沒有動靜時，先看 claude doctor。

怎麼檢查登入狀態，在 CI 裡又怎麼登入？

claude auth login
claude auth login --console
claude auth status
claude auth status --text
claude auth logout

claude auth login 登入。加上 --console 則改用 Anthropic Console 登入，以 API 用量計費，而不是用訂閱。claude auth logout 登出。

claude auth status 以 JSON 顯示認證狀態，加 --text 則是人看得懂的文字。其中 authMethod 欄位的值是 none、claude.ai、oauth_token、api_key、api_key_helper 或 third_party 其中之一。configDirectory 欄位需要 v2.1.268 以上。最有用的是它的結束代碼：已登入時為 0，未登入時為 1。所以腳本可以在呼叫 claude -p 之前先檢查：

if ! claude auth status >/dev/null; then
  echo "Claude Code is not logged in" >&2
  exit 1
fi

用 claude setup-token 讓伺服器上的腳本登入

claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN="<the token setup-token printed>"
claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

claude setup-token 產生一組有效期一年的 OAuth 權杖，給 CI 和腳本使用。它只把權杖印出來，不會存到任何地方，所以你要自己把它設成 CLAUDE_CODE_OAUTH_TOKEN 環境變數，並妥善保管。它需要 Pro、Max、Team 或 Enterprise 方案。這組權杖只能發送模型請求，不能用 Remote Control，也不能用 claude.ai 的連接器。

使用時有兩個衝突要避開。第一，bare 模式不讀這組權杖，所以用 setup-token 時不要加 --bare。第二，在非互動模式中，只要有 ANTHROPIC_API_KEY，就一定會用它，因為 API 金鑰在憑證順序中排在 OAuth 權杖前面。所以伺服器上殘留一個舊的 API 金鑰環境變數時，用量會以 API 計費，而不是算進訂閱。只有 Console 帳號、沒有訂閱的人，請直接用 ANTHROPIC_API_KEY。

舊教學還在寫錯的三件事

第一，claude --help 不會列出每一個旗標。官方 CLI 參考寫得很清楚：某個旗標沒有出現在 --help 裡，不代表它不能用。查旗標時，請以 CLI 參考文件為準。

第二，--enable-auto-mode 已經在 v2.1.111 移除。現在自動模式預設就在 Shift+Tab 的切換循環裡，要一開始就進入自動模式，請用 --permission-mode auto。

第三，--remote 現在是 --cloud 的已淘汰別名，連接續既有工作階段的寫法也一樣。舊寫法還能用，但新的腳本請寫 --cloud。

雲端工作階段：--cloud 和 --teleport

git push
claude --cloud "fix the failing tests"
claude --teleport
claude --teleport <session-id>
claude -p "also update the changelog" --cloud <session-id>

claude --cloud "task" 會為目前的程式庫建立一個新的雲端工作階段。它使用 GitHub 遠端上你目前所在的分支，所以要先 git push，否則雲端看不到你本機的修改。claude -p "msg" --cloud <session-id> 則是把一則後續訊息排進既有的雲端工作階段。

claude --teleport 把雲端工作階段拉回本機終端機，--teleport <session-id> 則恢復指定的那一個。它需要乾淨的 git 狀態，以及相同的程式庫和帳號。這個交接只有單向：可以把雲端拉下來，不能把終端機的工作階段推上去。

這兩個功能都需要 claude.ai 登入，使用 API 金鑰或第三方供應商時無法使用。--cloud 也需要組織允許遠端工作階段的政策。雲端工作階段適用 Pro、Max 和 Team 方案，以及擁有 premium 席位或 Chat + Claude Code 席位的 Enterprise 使用者。它和你其他的 Claude 用量一起計入方案的使用上限，雲端虛擬機不另外收費。額度怎麼算，請看 Claude 雲端工作階段的額度與用量。

最後一個容易混淆的名稱：--remote-control 和 --cloud 無關。它讓你從 claude.ai 或 Claude 應用程式監看並操控一個在本機執行的 CLI 工作階段。

依用途整理的 Claude CLI 速查清單

• claude：開啟互動式工作階段。
• claude "query"：開啟互動式工作階段，並帶入第一句提示。
• claude -c：載入目前目錄最近的對話，會跳過 -p、SDK 和 /loop 工作階段。
• claude -p --continue：接續最近的對話，包含 -p、SDK 和 /loop 工作階段。
• claude -r <ID 或名稱>：恢復特定工作階段，不給參數則顯示選單。
• claude -n <名稱>：替工作階段取名，之後可用 --resume <名稱> 恢復。
• claude -p "query"：非互動的列印模式。
• --output-format text|json|stream-json：列印模式的輸出格式。
• --max-turns：限制回合數，只限列印模式。
• --max-budget-usd：依用戶端估算的花費停止，只限列印模式，可能超過上限。
• --permission-prompts none：直接拒絕權限提示，需要 v2.1.259 以上。
• --bare：跳過 hooks、MCP、CLAUDE.md 等自動探索，只用 API 金鑰認證。
• --permission-mode：default、acceptEdits、plan、auto、dontAsk、bypassPermissions。
• --allowedTools 和 --disallowedTools：免詢問的工具與拒絕規則。
• --dangerously-skip-permissions：等同 bypassPermissions，只用在隔離環境。
• --model：sonnet、opus、haiku、fable 或完整模型名稱。
• --effort：low 到 max，以及 ultracode。
• --fallback-model：主要模型過載時的備用清單，最多三個。
• claude update 和 claude install <版本>：更新，或安裝指定的版本與頻道。
• claude doctor：唯讀的安裝與設定診斷。
• claude auth status：檢查登入，已登入結束代碼為 0，未登入為 1。
• claude setup-token：產生一年期的 OAuth 權杖，給 CI 使用。
• claude --cloud 和 claude --teleport：建立雲端工作階段，或把它拉回本機。

FAQ

Claude CLI 和 Claude Code 是不同的工具嗎？

不是。Claude CLI 就是 Claude Code 安裝到 PATH 上的 claude 命令。用 curl -fsSL https://claude.ai/install.sh | bash 安裝後，在新的終端機視窗執行 claude --version，會印出版本號。它需要 Pro、Max、Team、Enterprise 或 Console 帳號，免費的 claude.ai 方案不包含 Claude Code。

為什麼 claude -c 接不上我剛才用 claude -p 跑的工作階段？

因為 -c（--continue）刻意跳過用 claude -p 或 Agent SDK 建立的工作階段，也跳過第一句提示是 /loop 的工作階段。要接續這些工作階段，請改用 claude -p --continue。如果你知道工作階段的 ID 或名稱，也可以直接用 claude -r <ID 或名稱> 恢復。

在 VPS 的 CI 腳本裡，Claude Code 要怎麼登入？

有訂閱的話，執行 claude setup-token 產生一年期的 OAuth 權杖，再把它設成 CLAUDE_CODE_OAUTH_TOKEN。這時不要加 --bare，因為 bare 模式不讀這組權杖。只有 Console 帳號的話，請設定 ANTHROPIC_API_KEY。在非互動模式中，只要有 API 金鑰就會優先使用它。執行前可以用 claude auth status 檢查，已登入時結束代碼為 0，未登入時為 1。

claude install stable 可以把版本固定下來嗎？

不行。stable 是發布頻道，提供通常大約一週前、跳過重大問題的版本，而且之後會跟著自動更新前進。要固定版本，請安裝明確的版本號，例如 claude install 2.1.303，再把環境變數 DISABLE_AUTOUPDATER 設為 1 停止背景更新。要連手動更新一起封鎖，則用 DISABLE_UPDATES。

可以在自己的 VPS 上使用 --dangerously-skip-permissions 嗎？

官方只建議在隔離的環境中使用，例如容器、虛擬機，或沒有網路連線的開發容器。這個旗標等同 --permission-mode bypassPermissions，對提示詞注入沒有防護。在 Linux 上它也拒絕以 root 或 sudo 身分啟動。存有金鑰或正式資料的 VPS，請改用 --permission-mode dontAsk 搭配 --allowedTools，只放行你需要的指令。