Claude Code 的 CLI 是功能最完整的使用方式:所有斜線指令、管道輸入、腳本自動化都從這裡來。這篇 Claude Code CLI 教學把常用指令和旗標整理成一份參考,並以 Windows PowerShell 實際執行的畫面說明。
本文內容對照 2026 年 11 月的官方 CLI reference,實測版本為 Claude Code v2.1.322。指令與旗標增加得很快,完整清單請以官方文件為準。
還沒安裝的話,在 PowerShell 執行這一行:
irm https://claude.ai/install.ps1 | iex如果你主要在 VS Code 裡工作,可以先看 Claude Code VS Code 教學。
本文目錄
Claude Code CLI 基本用法
| 指令 | 作用 |
|---|---|
claude | 啟動互動式工作階段 |
claude "問題" | 啟動並直接送出第一句提示 |
claude -p "問題" | 回答完就結束,不進互動模式 |
cat 檔案 | claude -p "問題" | 把檔案內容用管道送進去 |
claude -c | 接續目前資料夾最近的一次對話 |
claude -r | 開啟選單,挑一個過去的對話接續 |
claude -r "名稱" "問題" | 依名稱或 ID 接續指定對話 |
啟動與檢查
在專案資料夾裡輸入 claude 就會進入互動模式。第一次在某個資料夾執行時,會先問你是否信任這個資料夾。

遇到問題時先跑這兩個:
claude --version
claude doctorclaude doctor 會列出安裝狀態與設定檔的錯誤,不會啟動工作階段,也不會改動任何東西。

一次性問答:-p
加上 -p(--print)會直接輸出答案然後結束,適合快速提問或寫進腳本:
claude -p "用一句話說明 report.py 在做什麼"
管道輸入
把其他指令的輸出接給 Claude:
cat report.py | claude -p "用三點以內列出這段程式可能的問題"
git diff main --name-only | claude -p "檢查這些檔案有沒有安全問題"在 PowerShell 裡 cat 是 Get-Content 的別名,可以直接用。網路上常見的 tail -200 app.log 是 Linux 寫法,PowerShell 要改成:
Get-Content app.log -Tail 200 | claude -p "分析這些日誌裡的異常"
接續對話
claude -c:直接回到這個資料夾最近的一次對話。claude -r:開啟可搜尋的選單。在 VS Code 擴充套件裡開的對話也會出現在這裡。claude -n "名稱":啟動時幫對話取名,之後用claude -r "名稱"找回來。

常用旗標
旗標可以組合使用,例如 claude --model sonnet --permission-mode plan。要注意 claude --help 不會列出所有旗標,沒列出來不代表不能用。

模型與效能
| 旗標 | 說明 | 範例 |
|---|---|---|
--model | 指定模型,可用別名(sonnet、opus、haiku、fable)或完整名稱 | claude --model sonnet |
--effort | 推理強度:low、medium、high、xhigh、max、ultracode,可用等級依模型而定 | claude --effort high |
--fallback-model | 主要模型過載或無法使用時自動改用的模型,可用逗號列出多個 | claude --fallback-model sonnet |
--autocompact | 設定這次工作階段的自動壓縮門檻(需 v2.1.221 以上) | claude --autocompact 500k |
--max-turns | 限制執行回合數,只在 -p 模式有效 | claude -p --max-turns 3 "..." |
--max-budget-usd | 預估花費到達上限就停止,只在 -p 模式有效;實際花費可能略超過 | claude -p --max-budget-usd 2 "..." |
對話管理
| 旗標 | 說明 | 範例 |
|---|---|---|
--continue、-c | 接續目前資料夾最近的對話 | claude -c |
--resume、-r | 依 ID 或名稱接續,不帶參數則開啟選單 | claude -r "auth-refactor" |
--name、-n | 幫對話取名 | claude -n "my-feature" |
--fork-session | 接續時另開新的 session,不動到原本的 | claude -r abc123 --fork-session |
--session-id | 指定 session ID(必須是 UUID) | |
--no-session-persistence | 不儲存對話,只在 -p 模式有效 | claude -p --no-session-persistence "..." |
輸出與格式
| 旗標 | 說明 | 範例 |
|---|---|---|
--print、-p | 輸出答案後結束 | claude -p "..." |
--output-format | -p 模式的輸出格式:text、json、stream-json | claude -p "..." --output-format json |
--input-format | -p 模式的輸入格式:text、stream-json | |
--json-schema | 要求輸出符合指定的 JSON Schema,只在 -p 模式有效 | |
--verbose | 顯示完整的逐回合輸出 | claude --verbose |
權限與安全
| 旗標 | 說明 | 範例 |
|---|---|---|
--permission-mode | 啟動時的權限模式:default(別名 manual)、acceptEdits、plan、auto、dontAsk、bypassPermissions | claude --permission-mode plan |
--allowedTools | 這些工具執行時不再詢問 | claude --allowedTools "Read" |
--disallowedTools | 拒絕規則;只寫工具名稱會把該工具整個移除 | claude --disallowedTools "Bash(rm *)" |
--tools | 限制可用的內建工具 | claude --tools "Bash,Edit,Read" |
--dangerously-skip-permissions | 略過權限詢問,等同 --permission-mode bypassPermissions | |
--safe-mode | 停用所有自訂項目(CLAUDE.md、skills、plugins、hooks、MCP 等),用來排查設定壞掉的問題 | claude --safe-mode |
舊教學常見的 --enable-auto-mode 已在 v2.1.111 移除。Auto 模式現在預設就在 Shift+Tab 的切換循環裡,要直接以 Auto 啟動請用 --permission-mode auto。
--dangerously-skip-permissions 只建議在沒有網路的隔離環境使用,平常開發用 Auto 或 Plan 模式就夠了。
系統提示詞
| 旗標 | 行為 |
|---|---|
--system-prompt | 取代整個預設提示詞 |
--system-prompt-file | 用檔案內容取代 |
--append-system-prompt | 接在預設提示詞後面 |
--append-system-prompt-file | 把檔案內容接在預設提示詞後面 |
這幾個旗標可以組合,例如先用 --system-prompt 取代,再用 --append-system-prompt 補一句。一般情況建議用 append:預設提示詞裡有工具使用的指引,整個取代掉容易讓 Claude 變得不好用。專案的固定規範則寫在 CLAUDE.md,不必每次帶旗標。
claude -p --append-system-prompt "一律用繁體中文回答" "摘要 README.md"工作目錄與環境
| 旗標 | 說明 | 範例 |
|---|---|---|
--add-dir | 額外加入可讀寫的資料夾 | claude --add-dir ../shared |
--worktree、-w | 在獨立的 git worktree 裡啟動 | claude -w feature-auth |
--bare | 精簡模式:不載入 hooks、skills、plugins、MCP、CLAUDE.md,腳本呼叫啟動較快 | claude --bare -p "..." |
--ide | 啟動時自動連上 IDE(剛好只有一個可用時) | claude --ide |
--chrome、--no-chrome | 啟用或停用 Chrome 瀏覽器整合 | claude --chrome |
--desktop | 在 Claude 桌面版 App 開啟目前資料夾,終端機不啟動工作階段 | claude --desktop |
MCP 與外掛
| 旗標 | 說明 | 範例 |
|---|---|---|
--mcp-config | 從 JSON 檔或字串載入 MCP Server | claude --mcp-config ./mcp.json |
--strict-mcp-config | 只用 --mcp-config 指定的,忽略其他 MCP 設定 | |
--plugin-dir | 只在這次工作階段載入指定資料夾或 .zip 的 plugin | claude --plugin-dir ./my-plugin |
--disable-slash-commands | 停用所有 skills 與指令 |
雲端與遠端
| 旗標 | 說明 | 範例 |
|---|---|---|
--cloud | 建立雲端工作階段。舊的 --remote 是它的別名,已不建議使用 | claude --cloud "修正登入的 bug" |
--teleport | 把雲端工作階段接回本機終端機 | claude --teleport |
--remote-control、--rc | 啟動互動工作階段並開啟 Remote Control,可從 claude.ai 或手機 App 接手 | claude --rc "My Project" |
--from-pr | 開啟與某個 PR 關聯的對話選單 | claude --from-pr 123 |
子指令
claude auth:帳號登入
claude auth login # 登入
claude auth login --console # 改用 Console 帳號,以 API 用量計費
claude auth status --text # 查看目前登入狀態
claude auth logout # 登出claude auth status 預設輸出 JSON,加 --text 才是給人看的格式。已登入時結束代碼是 0、未登入是 1,寫腳本時可以拿來判斷。
要在 CI 或腳本裡使用訂閱帳號,用 claude setup-token 產生長效 token。它只會把 token 印在終端機、不會儲存,請自行妥善保管。
claude mcp:MCP Server 管理
# 新增本機(stdio)Server
claude mcp add my-server -- node C:\path\to\server.js
# 新增遠端(HTTP)Server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"
claude mcp list # 列出已設定的 Server
claude mcp remove my-server # 移除
claude mcp login sentry # 直接跑 OAuth 登入,不必進 /mcp 面板
claude mcp logout sentry # 清除儲存的 OAuth 憑證claude mcp add 只會儲存設定,不會驗證憑證對不對。加完之後用 claude mcp list 確認,它會直接顯示每個 Server 的連線狀態。

延伸閱讀:Claude Code 的 MCP Server 設定。
claude update 與 claude install
claude update # 更新到最新版
claude install stable # 安裝或重裝指定版本:stable、latest 或版本號用官方安裝腳本裝的版本會在背景自動更新,平常不用手動跑。用 WinGet 裝的預設不會自動更新,要自己執行 winget upgrade Anthropic.ClaudeCode。
claude plugin:外掛管理
claude plugin install code-review@claude-plugins-officialclaude plugins 是同一個指令的別名。其他子指令請看官方 plugin reference,或這篇 Claude Code Plugins。
claude auto-mode:Auto 模式規則
claude auto-mode defaults # 印出內建的分類規則(JSON)
claude auto-mode config # 印出套用你的設定後實際生效的規則
claude auto-mode reset # 還原成預設,會先詢問確認背景工作階段
這是比較新的功能:把工作丟到背景跑,終端機馬上可以做別的事。
claude --bg "幫 report.py 補上單元測試" # 在背景啟動,會印出 session ID
claude agents # 開啟 agent view,監看所有背景工作階段
claude logs 7c5dcf5d # 看某個工作階段最近的輸出
claude attach 7c5dcf5d # 接回終端機繼續互動
claude stop 7c5dcf5d # 停止
claude rm 7c5dcf5d # 從清單移除詳細說明請看官方 agent view 文件。
claude remote-control:遠端控制
claude remote-control以伺服器模式啟動(本機不開互動畫面),讓你從 claude.ai 或手機 App 操作這台電腦上的 Claude Code。如果想要本機也能同時操作,改用 claude --rc。
其他子指令
| 指令 | 作用 |
|---|---|
claude doctor | 印出安裝與設定的診斷資訊,唯讀 |
claude import | 把其他 coding agent 的設定帶進 Claude Code |
claude purge | 刪除某個專案在本機的所有 Claude Code 資料(對話紀錄、編輯歷史等),可加 --dry-run 先預覽 |
claude ultrareview | 以非互動方式執行 ultrareview,結果印到標準輸出 |
實用的組合技巧
搭配 git
git diff main --name-only | claude -p "檢查這些變更的檔案有沒有安全問題"
git log --oneline -20 | claude -p "總結最近的開發進展"輸出 JSON 給腳本用
加上 --output-format json,輸出會變成一個 JSON 物件。在 PowerShell 裡用 ConvertFrom-Json 接起來,就能直接取用欄位:
$r = claude -p --safe-mode --output-format json "用一句話說明 report.py" | ConvertFrom-Json
$r.result
$r | Select-Object num_turns, duration_ms, total_cost_usd, is_error
常用的欄位有這幾個:
| 欄位 | 內容 |
|---|---|
result | Claude 的回答 |
is_error | 這次執行是否出錯 |
num_turns | 執行了幾個回合 |
duration_ms | 總耗時(毫秒) |
total_cost_usd | 預估花費(美元) |
session_id | 這次對話的 ID,可以拿來 --resume |
範例裡加了 --safe-mode,是為了不讓個人的 CLAUDE.md 和 hooks 影響輸出。我自己的全域設定會在工作完成時跳 Windows 通知,沒加這個旗標的話,回答後面會多出一段和問題無關的文字,JSON 裡也會多一筆被拒絕的指令紀錄。寫腳本時建議都加上。
限制回合與花費
無人看管的腳本一定要設上限:
claude -p --max-turns 5 --max-budget-usd 1 "檢查最新的變更有沒有潛在問題"花費上限是依客戶端的估算值判斷,實際金額可能略超過,設定時要留一點空間。
在獨立的 worktree 裡開工
claude -w feature-register "實作新的使用者註冊功能"Claude 會在 .claude/worktrees/feature-register 建立獨立的工作目錄,不會動到你目前的分支,適合同時跑好幾個任務。
CI/CD
在 CI 裡通常會用 --bare 加快啟動,並明確指定可用的工具:
claude --bare -p --max-turns 3 --allowedTools "Read" "檢查這次變更的程式碼品質"要注意 --bare 模式不會讀取訂閱帳號的登入,需要改用 API Key 驗證。完整做法請看 Claude Code Headless 模式與 CI/CD。
進階旗標速查表
| 旗標 | 說明 |
|---|---|
--agent | 指定這次工作階段使用的 agent |
--agents | 用 JSON 動態定義自訂 subagent |
--bg、--background | 以背景 agent 啟動並立刻返回 |
--exec | 搭配 --bg,把一個 shell 指令當成背景工作執行 |
--advisor | 為這次工作階段啟用 advisor 工具並指定模型 |
--settings | 指定設定檔路徑或 JSON 字串,覆蓋同名的設定 |
--setting-sources | 指定要載入哪些設定來源:user、project、local |
--debug | 除錯模式,可加分類篩選,例如 --debug='mcp,startup' |
--debug-file | 把除錯紀錄寫到指定檔案 |
--init-only | 執行 Setup 與 SessionStart hooks 後結束,不開始對話 |
--include-partial-messages | 輸出串流中的部分訊息,需搭配 -p 與 stream-json |
--permission-prompts | -p 模式下由誰回答權限詢問;設為 none 會直接拒絕 |
--teammate-mode | agent team 的顯示方式 |
--tmux | 為 worktree 建立 tmux session,需搭配 --worktree |
--version、-v | 顯示版本號 |
想快速查一個旗標時,直接在終端機看說明:
claude --help
claude mcp --help
常見問題
claude –help 沒列出的旗標可以用嗎?
可以。官方文件明確說明 --help 不會列出所有旗標,完整清單要看官方 CLI reference。
-p 模式和互動模式差在哪?
| 項目 | 互動模式 | -p 模式 |
|---|---|---|
| 啟動方式 | claude | claude -p "..." |
| 適合 | 來回討論、逐步修改 | 單次提問、腳本、CI |
| 權限詢問 | 會停下來問你 | 沒有人可以回答,需要核准的動作會被跳過,要事先用旗標設定好 |
| 專屬旗標 | --max-turns、--max-budget-usd、--output-format、--json-schema |
PowerShell 說找不到 claude
裝完後要重開終端機視窗,PATH 才會生效。另外,只裝 VS Code 擴充套件是不會有 claude 指令的,CLI 要另外安裝。
出現「this sign-in can end at any time」警告
執行 claude -p 時如果看到 Warning: this sign-in can end at any time from now until ...,代表登入憑證快到期了。這只是提醒,指令仍會正常執行。執行 claude auth login 重新登入一次就會消失。如果是 CI 或無人看管的腳本,改用 claude setup-token 產生長效 token。
設定改壞了,Claude Code 啟動後行為很怪
先用 claude --safe-mode 啟動。它會停用 CLAUDE.md、skills、plugins、hooks、MCP 等所有自訂項目,若這樣就正常,問題就出在你的設定裡,再用 claude doctor 找是哪個設定檔有錯。
總結
- 日常只需要記住四個:
claude、claude -c、claude -r、claude -p。 - 出問題先跑
claude doctor,設定壞掉用claude --safe-mode。 - 寫腳本用
-p搭配--output-format json和--safe-mode,並設好--max-turns與--max-budget-usd。 - Windows 的管道用 PowerShell 寫法,
cat可用,tail改成Get-Content -Tail。 --enable-auto-mode、--remote這些舊旗標已經換掉了,看到舊教學要留意。
嗨,我是ㄚ槌,寫了十多年程式的全端工程師,也就是站名裡的那個「小人物」。平常跟 bug 搏鬥,順手把踩過的坑整理成筆記:Claude Code 與 AI 開發、Python、SQL,偶爾也玩 ESP32 智慧家庭、NAS 自架服務和網頁開發。希望這些筆記能幫你少踩幾個坑。