工具參考

Claude Code 可以使用的工具完整參考，包括權限要求和各工具行為。

Claude Code 可以存取一組內建工具，幫助它理解和修改您的程式碼庫。工具名稱是您在權限規則、子代理工具清單和hook 匹配器中使用的確切字串。

若要控制 Claude 可以使用哪些工具以及何時要求先詢問，請在您的設定、hooks 或子代理的工具清單中設定權限規則。請參閱使用權限規則和 hooks 設定工具以了解接受工具名稱的各個位置。

若要新增自訂工具，請連接 MCP 伺服器。若要使用可重複使用的提示詞型工作流程擴展 Claude，請撰寫技能，它透過現有的 Skill 工具執行，而不是新增工具項目。

使用權限規則和 hooks 設定工具

在大多數情況下，Claude 會決定何時使用這些工具，您在與 Claude 互動時不需要自己命名它們。您在定義權限和其他設定時直接參考工具名稱：

• 在設定中的 permissions.allow 和 permissions.deny，以及 /permissions 介面
• 在 --allowedTools 和 --disallowedTools CLI 旗標
• 在 Agent SDK 的 allowedTools 和 disallowedTools 選項
• 在 skill 的 allowed-tools frontmatter
• 在 hook 的 if 條件

所有這些都接受相同的規則格式 ToolName(specifier)。specifier 取決於工具，多個工具共享一種格式：

此處未列出的工具，例如 ExitPlanMode 或 ShareOnboardingGuide，只接受不帶 specifier 的裸工具名稱。

Edit(...) 允許規則也會授予對相同路徑的讀取存取權，因此您不需要匹配的 Read(...) 規則。Read(...) 拒絕規則也會在相同路徑上阻止 Edit 和 Write 工具，包括在該處建立新檔案，因為兩個工具都會變更 Claude 必須能夠讀回的內容。Read 拒絕檢查需要 Claude Code v2.1.208 或更新版本進行編輯，以及 v2.1.228 或更新版本進行寫入。

Hook matcher 欄位使用裸工具名稱，而不是括號化的規則格式。請參閱 matcher 模式 以了解匹配規則。如需每個工具在 hooks 中傳遞給 tool_input 的欄位名稱，請參閱 PreToolUse 輸入參考。

Agent 工具行為

Agent 工具在獨立的內容視窗中生成一個子代理。子代理自主地完成其任務，然後向父對話返回單一文字結果。父對話看不到子代理的中間工具呼叫或輸出，只能看到最終結果。啟用 agent teams 時，帶有 name 的呼叫可以啟動一個 teammate，它透過團隊訊息而不是返回結果來報告。

若要限制子代理執行的回合數，請在 subagent definition 中設定 maxTurns。當子代理達到限制時，Claude Code 會將返回的結果標記為部分輸出，Claude 可以 resume the subagent 以繼續。

同一個 Agent 工具也會在 fork mode 開啟的地方啟動 forked subagents。fork 會繼承完整的父對話而不是從頭開始，在背景中執行，除了 cases that stay in the foreground 外，並且仍會在您的終端中顯示權限提示。本節的其餘部分描述非 fork 子代理。

非 fork 子代理可以使用哪些工具取決於 subagent definition 中的 tools 和 disallowedTools 欄位：

• 兩個欄位都未設定：子代理繼承每個 tool available to subagents。
• 僅設定 tools：子代理只獲得列出的工具。
• 僅設定 disallowedTools：子代理獲得除了列出的工具外的每個父工具。
• 兩者都設定：disallowedTools 優先。同時列在兩者中的工具會被移除。

在每種情況下，解析的集合都限於 tools available to subagents：不可用於子代理的工具永遠不會被授予，即使在 tools 中列出也是如此。

如果子代理的 tools 列表中的每個項目都無法匹配可用工具，Agent 工具通常會返回一個錯誤，命名這些項目而不是啟動子代理；請參閱 Agent would be spawned with zero tools 以了解訊息和如何修復每個項目。

啟動子代理本身不會提示權限。Claude Code 在執行時根據您的權限規則檢查子代理自己的工具呼叫。

您看到子代理權限提示的位置取決於它是在前景還是背景中執行。Claude Code 預設在背景中執行子代理，除了 cases that run in the foreground 外。

• 前景子代理顯示您在主對話中會看到的相同權限提示，在每個工具呼叫發生時。
• 背景子代理 自 v2.1.186 起在您的主工作階段中顯示權限提示。提示會命名哪個子代理在詢問，按 Esc 會拒絕該工具呼叫而不停止子代理。在 v2.1.186 之前，背景子代理會自動拒絕任何否則會提示的工具呼叫，並在沒有該工具的情況下繼續。

若要 limit what a subagent can reach，請首先縮小其 tools 欄位，例如透過將 Bash 留在列表之外，或在您的設定中設定拒絕規則。

AskUserQuestion 工具行為

Claude 使用 AskUserQuestion 在需要決策或澄清時向您提出多選題。透過選擇選項來回答，或透過 Other 列或備註欄位輸入您自己的文字。

當您透過輸入自己的文字來回答時，Claude Code 會以中立的措辭轉達答案，以便 Claude 遵循您所寫的內容，包括等待或先解釋的請求。

問題自動繼續逾時

問題會保持開啟，直到您回答為止。如果您想讓未回答的問題最終關閉並讓 Claude 在沒有您的情況下繼續，請在您的使用者 settings.json 中或從 /config 中的 Question auto-continue timeout 列設定 askUserQuestionTimeout 設定為 60s、5m 或 10m。

問題閒置該時間長度而沒有輸入後，對話框會自動關閉：它會提交您已選擇的任何選項，並告訴 Claude 您可能離開了鍵盤，因此 Claude 會根據自己的判斷進行，稍後可以重新提問。您會看到最後 20 秒的倒數計時。按任何鍵重新啟動計時器；在報告焦點的終端上，切換到視窗也會重新啟動它。

逾時僅適用於 AskUserQuestion 的多選題；權限提示（包括計畫批准）在閒置時永遠不會自動解決。

Bash 工具行為

Bash 工具在單獨的程序中執行每個命令。

命令之間保留的內容

• 當 Claude 在主工作階段中執行 cd 時，新的工作目錄會延續到後續的 Bash 命令，只要它保持在專案目錄或您使用 --add-dir、/add-dir 或設定中的 additionalDirectories 新增的額外工作目錄內。這包括 Claude 為回應您後續訊息而執行的命令。
  • 子代理工作階段永遠不會延續工作目錄變更。
  • 如果 cd 落在這些目錄之外，Claude Code 會重設為專案目錄，並在工具結果中附加 Shell cwd was reset to <dir>。
  • 若要停用此延續功能，使每個 Bash 命令都在專案目錄中啟動，請設定 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1。
• 環境變數不會保留。一個命令中的 export 在下一個命令中將無法使用。
• 在您的 shell 啟動檔案中定義的別名和 shell 函式可用。在工作階段啟動時，Claude Code 會根據您的 shell 來源 ~/.zshrc、~/.bashrc 或 ~/.profile，擷取產生的別名、函式和 shell 選項，並將其套用到每個 Bash 命令。

在啟動 Claude Code 之前啟動您的 virtualenv 或 conda 環境。若要使環境變數在 Bash 命令之間保留，請在啟動 Claude Code 之前將 CLAUDE_ENV_FILE 設定為 shell 指令碼，或使用 SessionStart hook 動態填入它。

逾時和輸出限制

每個命令都在逾時限制下執行，Claude 管理它：當它需要比命令的預設值更長的時間時，它會使用該呼叫傳遞 timeout 參數 — 您永遠不會設定每個命令的逾時。兩個環境變數限制 Claude 獲得的內容：

• BASH_DEFAULT_TIMEOUT_MS — 當 Claude 不傳遞逾時時的預設值；預設為兩分鐘
• BASH_MAX_TIMEOUT_MS — 使用預設值時，設定上限以限制 Claude 要求的任何內容：有效上限是兩者中較大的，預設為十分鐘

輸出限制

Claude Code 在命令執行時將命令的輸出串流到工作檔案；輸出超過 5 GB 的命令會被終止。命令完成後，Claude Code 從該檔案讀回輸出，最多到下面描述的讀回視窗。輸出有多少到達 Claude 內聯取決於 Claude Code 是否將結果視為失敗：

命令退出代碼為 1 只有在 Claude Code 將退出代碼 1 識別為該命令的良性結果時，才算作 Bash 工具的有效結果：grep、rg、egrep、fgrep、find、diff、test 和 [，加上 git diff 和 git grep。每個其他退出代碼為 1 的命令都算作失敗，即使退出代碼 1 是良性的資訊結果：pgrep 和 jq -e 沒有符合項，cmp 的檔案不同。

BASH_MAX_OUTPUT_LENGTH 設定 Claude Code 從工作檔案讀回到命令結果中的輸出字元數：預設 30,000，最多硬上限 150,000。當您的命令經常超過該視窗時提高它，例如詳細的建置或完整的測試套件日誌。提高它會擴大讀回視窗，這也是失敗命令的摘錄被切割的視窗。它不會提高內聯上限：超過內聯上限的有效結果會作為檔案路徑加預覽到達，無論此變數如何。

若要變更有效結果中 Claude 內聯接收的數量，請改為設定 bashOutputMaxChars 設定，最多 128,000 個字元。它同時調整內聯上限和讀回視窗的大小，Claude Code 隨後會忽略 BASH_MAX_OUTPUT_LENGTH。需要 Claude Code v2.1.261 或更新版本。

背景命令

對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 run_in_background: true 以將命令作為背景工作啟動並在其執行時繼續工作。使用 /tasks 列出並停止背景工作。在您從那裡停止一個後，或從連接的用戶端（例如桌面應用程式）停止後，Claude 會繼續而不是等待。如果子代理啟動了命令，則是該子代理繼續。

前景子代理啟動的命令在該子代理給出最終回應時停止。主對話或背景子代理啟動的命令在最終回應後繼續執行。在使用 -p 旗標的非互動模式中，背景命令在執行的最終結果後不久結束。

當命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 sleep 開頭。Claude 在命令繼續時繼續工作。Claude Code 將相同的生命週期規則套用到移動的命令，就像任何其他背景命令一樣，因此它仍然在該子代理的最終回應時結束前景子代理的命令。設定 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 會停用自動背景化以及其餘的背景工作功能。

移至背景的命令的結果說明發生了什麼：

• 當逾時觸發移動時，結果明確報告它：Command did not complete within its 120s timeout and was moved to the background，秒數與應用的逾時相符，後跟工作 ID 和輸出正在寫入的檔案路徑。
• 移至背景的命令內的 cd、pushd、popd 或 chdir 永遠不會延續：結果說明 Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands.，所以 Claude 不會對未發生的目錄變更採取行動。

Linux 和 WSL 上的記憶體限制

在 Linux 和 WSL 上，將 CLAUDE_CODE_TOOL_MEMORY_LIMIT 設定為大小（例如 4G）以限制 Bash、PowerShell 和 Monitor 工具命令可以使用的記憶體，使一個失控的建置無法佔用工作階段其餘部分需要的記憶體。需要 Claude Code v2.1.233 或更新版本。在 v2.1.246 之前，Monitor 工具命令在上限之外執行。

• 將大小寫成位元組數或帶有 K、M、G 或 T 後綴。設定 0、off、false、no 或 none 以關閉上限。Claude Code 會忽略任何無法讀取為大小的其他值，例如 4e9。
• Claude Code 將工作階段的所有 Bash、PowerShell 和 Monitor 命令計入一個上限，而不是每個命令各自計入。
• Claude Code 使用記憶體 cgroup 套用上限。當無法設定 cgroup 時，命令在沒有上限的情況下執行，來自 claude --debug 的偵錯日誌會說明原因。
• 在 Claude Code 啟動的第一個程序已開啟上限或因為關閉值或失敗的 cgroup 設定而關閉上限後，Claude Code 會保留該結果直到您重新啟動。若要套用已變更或移除的值或固定的設定，請再次啟動 claude。
• 當命令無法保持在上限以下時，核心會終止命令，其結果中沒有任何內容命名上限。

Claude Code 也可以將它啟動的其他類型的程序計入相同的限制。將 CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE 設定為要從上限中豁免的類型的逗號分隔清單；Claude Code 將上限套用到不在您清單上的每種類型。將其設定為 none 以限制每種類型，或設定為 all-new 以僅限制 Bash、PowerShell 和 Monitor 工具命令。需要 Claude Code v2.1.246 或更新版本。您可以命名的類型：

• mcp: 本機 MCP 伺服器
• lsp: 語言伺服器
• hooks: hook 命令
• plugin: 外掛程式執行的命令
• helper: Claude Code 自己的協助程式命令，例如 git
• agent: 子 Claude Code 程序，例如代理隊友

無論您列出什麼，這些規則都適用：

• 未知名稱：Claude Code 會忽略它不識別的名稱
• Bash、PowerShell 和 Monitor：Claude Code 無論您列出什麼，都會將 Bash、PowerShell 和 Monitor 工具命令保持在上限以下
• 變數未設定：Claude Code 從 Anthropic 從伺服器傳遞的設定中取得其他限制類型的集合，該集合可能隨時間變化，因此當您需要不變的集合時設定變數
• 權限閘控 hook：即使每種類型都受限，Claude Code 也會從上限中排除可以阻止或變更動作結果的 hook，以及任何此類 hook 呼叫的 MCP 伺服器，因此核心終止權限閘控 hook 無法允許它正在阻止的動作

Edit 工具行為

Edit 工具執行精確的字串替換。它接受 old_string 和 new_string，並用後者替換前者。它不使用正規表達式或模糊匹配。

編輯要應用必須通過三項檢查。在任何檢查之前，由 Read 拒絕規則匹配的路徑會被拒絕，包括在該處建立新檔案。拒絕需要 Claude Code v2.1.208 或更新版本。

• 編輯前讀取：Claude 在編輯檔案前在目前對話中讀取該檔案，而以 PARTIAL view 通知中斷的讀取不計算在內。Claude Opus 4.6、Claude Haiku 4.5 和較舊的模型始終需要讀取。較新的模型可以在讀取不需要權限提示且 Read 工具可用時編輯未讀檔案。
• 匹配：old_string 必須在檔案中完全按照書寫方式出現。單一個空白字元或縮排差異足以導致不匹配。
• 唯一性：old_string 必須恰好出現一次。當它出現多次時，Claude 要麼提供更長的字串，其中包含足夠的周圍內容以確定一個出現位置，要麼設定 replace_all: true 以替換所有出現位置。

在 Claude 最後讀取檔案後，磁碟上變更的檔案仍然可以編輯，當 old_string 與目前內容完全且明確匹配，且 Claude Code 可以讀取檔案而無需提示時。針對檔案的目前內容進行匹配可保持安全，結果會注意到檔案包含其他變更，因此 Claude 在依賴周圍內容的編輯前重新讀取它。在任何其他情況下，例如過時的 old_string 或不使用 replace_all 而匹配多次的情況，Claude 在編輯前再次讀取檔案。未讀和已變更檔案的寬鬆處理需要 Claude Code v2.1.208 或更新版本；在此之前，Claude Code 拒絕對它在對話中未讀過或在讀取後在磁碟上變更的任何檔案進行編輯。

使用 Bash 檢視檔案也滿足編輯前讀取要求，當命令是 cat、nl、bat、batcat、head、tail、sed -n 'X,Yp'、grep、egrep、fgrep 或 rg 在單一檔案上且沒有管道或重新導向時。管道輸出和其他 Bash 命令不計入編輯前讀取檢查。

使用 Bash 檢視檔案僅影響編輯資格，不影響權限。請參閱 Read 和 Edit 權限規則，了解您的 Read 和 Edit 拒絕規則涵蓋哪些 Bash 命令。

EndConversation 工具行為

EndConversation 工具會結束目前的工作階段。Claude 只在兩種情況下使用它：

• 作為對持續濫用輸入的最後手段，在嘗試重新導向對話失敗且在較早的訊息中發出明確警告之後
• 當您明確要求查看工具演示並確認您想要結束工作階段時

一般的挫折感、粗言穢語或任務進行不順利都不符合條件，對有害內容的請求也不符合，Claude 會拒絕這些請求而不是結束工作階段。Claude Code 遵循與 claude.ai 相同的方法，後者可以結束少數聊天。

Claude 結束互動式工作階段後，工作階段會被鎖定。新的提示和大多數命令會傳回 Claude ended this conversation. Start a new session (or /clear) to continue.，只有 /clear、/resume、/help、/exit 和 /feedback 仍然可以執行。Claude Code 會在工作階段的文字記錄中記錄結束，因此恢復已結束的工作階段會恢復鎖定；工作階段的歷史記錄不會被刪除。

在非互動模式中使用 -p 旗標恢復已結束的工作階段會出錯並以代碼 1 結束，因此指令碼不會將已結束的執行讀取為成功。

該工具永遠不會提示要求權限，PreToolUse hooks 也不會為其執行。只要任何其他工具仍然存在，您就無法阻止它：命名 EndConversation 的拒絕和要求規則無效，--disallowedTools 和 --tools 清單都無法移除它。此豁免是刻意的：該工具除了結束對話外什麼都不做，永遠不會讀取或修改檔案或資料，這種保障措施只有在應用它的工作階段無法將其關閉時才能成立。當您的拒絕規則移除所有其他工具並且也符合 EndConversation 時（如 "*" 所做的那樣），Claude Code 也會移除它，而不是將其作為唯一的工具，除非允許規則明確命名 EndConversation。移除所有其他工具但不符合 EndConversation 的拒絕清單會將其保留在原位。

子代理永遠不會獲得該工具。共享主對話工具清單的背景工作會看到它，但在那裡呼叫它不會結束任何東西。

該工具只在以下所有條件都成立時才會出現：

• 版本：Claude Code v2.1.213 或更新版本。
• 模型：工作階段的模型是 Claude Opus 4.8、Claude Sonnet 5、Claude Fable 5 或這些系列之一的更新版本。
• 介面：互動式終端工作階段，包括 IDE 整合終端中的 claude 工作階段，這是 JetBrains 外掛程式執行它的方式。其他介面不包括該工具，例如：
  • 非互動式 -p 執行
  • 透過 Agent SDK TypeScript 和 Python 套件的工作階段
  • VS Code 擴充功能面板，它包含自己的 CLI
  • GitHub Actions
  • 網路上的 Claude Code
• 啟動模式：不是 --bare 工作階段。裸機模式只載入 shell 和檔案工具，因此該工具永遠不會在那裡註冊。
• 提供者：在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用，或在透過雲端閘道登入的工作階段上不可用。

Glob 工具行為

Glob 工具按名稱模式尋找檔案。在 Windows 上，它是預設工具集的一部分。在 macOS、Linux 和 WSL 上，Claude Code 會將 Glob 和 Grep 排除在預設工具集之外，Claude 改為透過 Bash 工具使用 find 和 grep 進行搜尋。在 Claude 的 shell 中，這兩個命令會執行 bfs 和 ugrep 的嵌入版本，搜尋會透過 Bash 呼叫到達您的 hooks 和權限規則。

在 macOS、Linux 和 WSL 上，您可以在以下情況下取回 Glob 和 Grep 工具：

• 您在啟動工作階段時在 --tools 或 --allowedTools 中命名 Glob 或 Grep，或在等效的 Agent SDK 選項中命名。使用 --tools 時，您會取得列出的工具，在 --allowedTools 中命名任一工具會同時復原兩者。設定檔中的允許規則沒有此效果。
• 權限 拒絕規則、--disallowedTools 旗標或 --restricted 會從工作階段中移除 Bash。
• 子代理 在其 tools 欄位中列出 Glob 或 Grep 並排除 Bash。列出的工具僅針對該子代理返回，或當它透過 --agent 或 agent 設定作為主工作階段代理執行時，針對整個工作階段返回。

Glob 支援標準 glob 語法，包括 ** 用於遞迴目錄匹配：

• **/*.js 符合任何深度的所有 .js 檔案
• src/**/*.ts 符合 src/ 下的所有 .ts 檔案
• *.{json,yaml} 符合目前目錄中的 .json 和 .yaml 檔案

結果按修改時間排序，上限為 100 個檔案。如果達到上限，Claude 會在結果中看到截斷旗標，並可以縮小模式。

Glob 預設不遵守 .gitignore，因此它會找到被 gitignore 的檔案以及追蹤的檔案。這與 Grep 不同，後者會跳過被 gitignore 的檔案。若要讓 Glob 遵守 .gitignore，請在啟動 Claude Code 前設定 CLAUDE_CODE_GLOB_NO_IGNORE=false。

Claude Code 在檢查搜尋目錄是否存在之前，會先決定 Glob 呼叫的權限。它仍會對 工作目錄 外遺失的 path 執行讀取權限檢查，因此路徑的權限提示並不表示該路徑存在。

包含空位元組的 pattern 或 path 值會傳回錯誤，要求 Claude 移除它。

Grep 工具行為

Grep 工具搜尋檔案內容中的模式。Glob 按名稱尋找檔案，而 Grep 在檔案內尋找行。在 macOS、Linux 和 WSL 上，Grep 在與 Glob 相同的條件下預設不存在。請參閱 Glob 工具行為，了解何時兩種工具都可用。

Grep 是基於 ripgrep 建立的，並使用 ripgrep 的正規表達式語法，而不是 POSIX grep。包含正規表達式元字元的模式需要逃脫。例如，在 Go 程式碼中尋找 interface{} 需要使用模式 interface\{\}。

ripgrep 拒絕的模式、glob 或檔案類型會傳回包含 ripgrep 診斷的錯誤，以便 Claude 可以更正輸入並再次搜尋。在 v2.1.208 之前，Claude Code 將被拒絕的輸入報告為 No files found，而不是錯誤，即使搜尋的文字存在於目標檔案中。

三種輸出模式控制傳回的內容：

• files_with_matches：僅檔案路徑，無行內容。這是預設值。
• content：匹配的行及檔案和行號。當工具的 offset 參數指向模式的最後一個匹配項之後（該模式有匹配項時），Grep 會傳回 No entries at this offset，因此 Claude 會擴大或重設 offset，而不是得出模式不匹配的結論。
• count：每個檔案的匹配計數，後面是所有匹配檔案的總計。總計涵蓋每個匹配項，即使工具的 head_limit 或 offset 參數截斷了列出的每個檔案項目。在 v2.1.208 之前，總計只加總列出的項目。

Claude 可以使用 glob 參數（例如 **/*.tsx）按檔案範圍限制結果，或使用 type 參數（例如 py 或 rust）按語言限制結果。預設情況下，模式在單一行內匹配。Claude 可以設定 multiline: true 以跨越行邊界進行匹配。

Grep 遵守 .gitignore，因此被 gitignore 的檔案會被跳過。若要搜尋被 gitignore 的檔案，Claude 會直接傳遞其路徑。

Claude Code 在檢查搜尋 path 是否存在之前決定 Grep 呼叫的權限。它仍會對 工作目錄 外的遺失 path 執行讀取權限檢查，因此路徑的權限提示並不意味著該路徑存在。

LSP tool 行為

LSP tool 從執行中的語言伺服器為 Claude 提供程式碼智慧。在每次檔案編輯後，它會自動報告型別錯誤和警告，讓 Claude 可以在沒有單獨建置步驟的情況下修復問題。Claude 也可以直接呼叫它來導覽程式碼：

• 跳至符號的定義
• 尋找符號的所有參考
• 取得位置的型別資訊
• 列出檔案中的符號
• 在工作區中按名稱搜尋符號
• 尋找介面的實作
• 追蹤呼叫階層

Claude Code 會保持 tool 為非作用中狀態，直到您為您的語言安裝程式碼智慧 plugin。在雲端工作階段中，Claude Code 不會啟動 plugin 語言伺服器，所以 LSP tool 在那裡保持非作用中。Claude Code 從 plugin 取得語言伺服器的設定，您需要自行安裝伺服器二進位檔。

Claude Code 會針對無法啟動其語言伺服器的檔案上的每個 LSP 呼叫傳回錯誤結果。

Monitor 工具

Monitor 工具讓 Claude 在背景中監視某些內容，並在其變更時做出反應，而無需暫停對話。請要求 Claude：

• 追蹤日誌檔案並在錯誤出現時標記
• 輪詢 PR 或 CI 工作，並在其狀態變更時報告
• 監視目錄中的檔案變更
• 追蹤您指向的任何長時間執行指令碼的輸出
• 連接到 WebSocket 摘要並在每條訊息到達時報告

對於大多數監視，Claude 會編寫一個小指令碼，在背景中執行它，並在每行輸出到達時接收。對於已經推送事件的伺服器，Claude 可以開啟 WebSocket 而不是執行指令碼。

您可以在同一工作階段中繼續工作，Claude 會在事件到達時插入。

透過要求 Claude 取消監視或結束工作階段來停止監視。當您停止啟動監視的 子代理（例如來自 /tasks）時，這些監視會隨之停止。

當 Monitor 執行命令時，它使用與 Bash 相同的權限規則，因此您為 Bash 設定的 allow 和 deny 模式也適用於此處。當 自動模式 處於活動狀態時，Claude Code 會擱置命名 Monitor 本身的允許規則，以及它捨棄的其他 廣泛允許規則，因此分類器以與檢查 Bash 命令相同的方式檢查 Monitor 命令。

WebSocket 來源 有其自己的核准提示，分類器也會在自動模式中決定。

該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。當設定 DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 時，它也不可用。

外掛程式可以宣告在外掛程式處於活動狀態時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 外掛程式監視。

WebSocket 來源

當伺服器已經透過 WebSocket 推送事件時，Claude 可以直接連接到它，而不是編寫輪詢指令碼。每種套接字活動要麼變成一個事件，要麼結束監視：

• 文字訊息：每一條都變成一個事件，即使訊息跨越多行。
• 二進位訊息：不會通過。Claude 會收到一個佔位符行，例如 [binary frame, 512 bytes]。
• 大於 1 MiB 的訊息：監視結束，因此請訂閱存在的篩選摘要。
• 套接字關閉：監視結束，Claude 會收到關閉代碼。

WebSocket 監視採用 ws 輸入代替 command，單一 Monitor 呼叫無法結合兩者。ws 輸入有兩個欄位：

timeout_ms 和 persistent 輸入的行為與它們對命令的行為相同：監視在截止時間結束，除非設定 persistent，且 TaskStop 會提前取消它。

開啟 WebSocket 會提示核准；在 自動模式 中，分類器會改為決定。提示不提供跳過相同主機的未來提示的選項。

Claude Code 拒絕指向私人、連結本機或雲端中繼資料位址的 URL，包括解析為該位址的主機名稱。它也拒絕 sandbox.network.deniedDomains 中的主機，以及當在受管設定中設定 allowManagedDomainsOnly 時，任何在受管允許清單外的主機。

NotebookEdit 工具行為

NotebookEdit 一次修改一個 Jupyter notebook 儲存格，按其 cell_id 定位儲存格。它不像 Edit 在純文字檔案上那樣跨 notebook 執行字串替換。

三個編輯模式控制目標儲存格發生的情況：

• replace：覆寫儲存格的來源。這是預設值。
• insert：在目標後新增新儲存格。沒有 cell_id 時，新儲存格位於 notebook 的開始。需要 cell_type 設定為 code 或 markdown。
• delete：移除目標儲存格。

權限規則使用 Edit(...) 路徑格式。像 Edit(notebooks/**) 這樣的規則涵蓋該目錄中檔案上的 NotebookEdit 呼叫。

PowerShell 工具

PowerShell 工具讓 Claude 能夠原生執行 PowerShell 命令。在 Windows 上，這表示命令在 PowerShell 中執行，而不是透過 Git Bash 路由。工具的可用性取決於您的平台：

• Windows 未安裝 Git Bash：工具會自動啟用。
• Windows 已安裝 Git Bash：工具在 claude.ai 和 Console 帳戶上預設為開啟；在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 工作階段中，設定 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 以啟用它，或設定 0 以關閉它。
• Linux、macOS 和 WSL：工具是選擇性加入。

您的 PreToolUse hooks 在 tool_input.command 中接收工具的命令字串，欄位與 Bash 工具相同。

在檢查 shell 命令的 hooks 中比對 Bash|PowerShell；PowerShell hook 輸入部分說明為什麼單獨比對 Bash 是不夠的。

啟用 PowerShell 工具

在您的環境或 settings.json 中設定 CLAUDE_CODE_USE_POWERSHELL_TOOL=1：

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
  }
}

在 Windows 上，將變數設定為 0 以關閉工具。在 Linux、macOS 和 WSL 上，工具需要 PowerShell 7 或更新版本：安裝 pwsh 並確保它在您的 PATH 中。

在 Windows 上，Claude Code 會自動偵測 PowerShell 7+ 的 pwsh.exe，並回退到 PowerShell 5.1 的 powershell.exe。啟用工具時，Claude 會將 PowerShell 視為主要 shell。當安裝了 Git Bash 時，Bash 工具仍可用於 POSIX 指令碼。

Claude Code 以程序範圍只啟動 PowerShell 搭配 -ExecutionPolicy Bypass，因此 .ps1 指令碼和模組匯入可在預設 Windows 安裝上運作，無需變更機器的原則。程序範圍略過不會覆寫群組原則 MachinePolicy 或 UserPolicy，因此企業原則仍然適用。若要改為遵守機器的有效執行原則，請設定 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1。

設定、hooks 和 skills 中的 shell 選擇

三個額外的設定控制 PowerShell 的使用位置：

• settings.json 中的 "defaultShell": "powershell"：透過 PowerShell 路由互動式 ! 命令。需要啟用 PowerShell 工具。
• 個別 command hooks 上的 "shell": "powershell"：在 PowerShell 中執行該 hook。Hooks 直接啟動 PowerShell，因此無論 CLAUDE_CODE_USE_POWERSHELL_TOOL 為何都能運作。
• skill frontmatter 中的 shell: powershell：在 PowerShell 中執行 !`command` 區塊。需要啟用 PowerShell 工具。

Bash 工具部分所述的相同主工作階段工作目錄重設行為適用於 PowerShell 命令，包括 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR 環境變數。

自 v2.1.196 起，來自 grep、rg、egrep、fgrep、findstr 和 git grep 的結束代碼 1 表示無符合項目。來自 git diff 的結束代碼 1 表示存在差異。這兩個結果都不會向 Claude 報告為命令失敗。對於 robocopy，結束代碼 0 到 7 是資訊性結果，例如複製的檔案或偵測到的額外檔案。結束代碼 8 或更高視為失敗。

Windows 編碼和結束代碼

在 Windows 上，下列 PowerShell 編碼和結束代碼行為需要 Claude Code v2.1.214 或更新版本：

• 使用 > 和 >> 的重新導向在 PowerShell 5.1 上寫入 UTF-8 檔案
• Claude Code 將管道傳送到原生命令標準輸入的文字編碼為 UTF-8
• Claude Code 擷取錯誤輸出而不含 ANSI 逸出序列
• 其子程序等待標準輸入的命令會收到檔案結尾而不是掛起
• 來自 where.exe 的結束代碼 1 表示無符合項目，來自 fc.exe 和 diff.exe 的結束代碼 1 表示檔案不同，因此當命令產生輸出時，Claude Code 會將該結束代碼視為有效的否定答案，而不是命令錯誤。Claude Code 仍會將靜音形式（例如 where.exe /Q 或重新導向至 $null）報告為結束代碼 1 時的失敗

在 v2.1.214 之前，PowerShell 5.1 上的 > 寫入 UTF-16LE 檔案，非 ASCII 管道輸入到達為 ?，而 Python 指令碼在列印非 ASCII 字元時可能會因 UnicodeEncodeError 而當機。

預覽限制

PowerShell 工具在預覽期間有下列已知限制：

• PowerShell 設定檔未載入
• 在 Windows 上，不支援沙箱化

Read 工具行為

Read 工具接受檔案路徑並傳回包含行號的內容。Claude 被指示始終傳遞絕對路徑。

根據預設，Read 從檔案開始處傳回內容。當整個檔案讀取超過權杖限制時，Read 會傳回第一頁並顯示 PARTIAL view 通知，告訴 Claude 它收到了多少檔案內容，以及如何使用 offset 和 limit 讀取更多內容。傳遞明確 offset 或 limit 的讀取操作如果仍然超過權杖限制，會傳回錯誤。

具有明確 limit 的讀取操作會在選定的行數超過權杖限制可能容納的內容時立即停止，並傳回錯誤而不載入其餘範圍。錯誤會告訴 Claude 使用較小的 limit，或者當單一行非常大時，改為使用 Grep 搜尋特定內容。在 v2.1.208 之前，Claude Code 會在拒絕前將整個範圍載入記憶體，因此讀取具有極長單一行的檔案可能會導致記憶體不足。

讀取空檔案會傳回通知，說明檔案存在但內容為空，而超過最後一行的 offset 會傳回通知，提供檔案的行數。在 v2.1.208 之前，讀取空檔案會傳回超過末尾的通知。

Read 處理純文字以外的多種檔案類型：

• 影像：PNG、JPG 和其他影像格式會以 Claude 可以看到的視覺內容形式傳回，而不是原始位元組。Claude Code 會在傳送前調整大小並重新壓縮大型影像以符合模型的影像大小限制，因此 Claude 可能會看到大型螢幕擷取畫面的縮小版本。自 v2.1.196 起，在調整大小後仍大於 500KB 的影像會以降低品質的 JPEG 格式重新編碼，其像素尺寸保持不變。如果 Claude 在大型影像中遺漏了細微的像素級細節，請要求它先裁剪感興趣的區域，例如透過 Bash 使用 ImageMagick。
• PDF：Claude 會完整讀取短 .pdf 檔案。對於超過 10 頁的 PDF，它會使用 pages 參數（例如 "1-5"）按範圍讀取，一次最多 20 頁。
• Jupyter 筆記本：.ipynb 檔案會傳回所有儲存格及其輸出，包括程式碼、markdown 和視覺化。Claude Code 拒絕讀取超過 100 MB 的筆記本檔案；錯誤會告訴 Claude 如何改為讀取筆記本的一部分，例如使用 shell 命令讀取儲存格的切片。

Read 只讀取檔案，不讀取目錄。Claude 使用 shell 命令（例如 ls）列出目錄內容。

SendFeedback 工具行為

Claude 起草的回饋是 Claude 為您撰寫的關於 Claude Code 的回饋報告。它需要 Claude Code v2.1.238 或更新版本。Claude Code 會將每份草稿保存在您的機器上的 ~/.claude/feedback/drafts/ 下，在您發送之前，任何內容都不會到達 Anthropic。Claude 在以下情況下會使用 SendFeedback 工具起草一份：

• 工具或命令持續失敗
• 它無法幫助您要求的事項
• 您指出它犯的錯誤，或它自己發現了一個
• 您要求它提交回饋

當 Claude 起草時您看到的內容

Claude 將草稿加入佇列後，您會在提示上方看到一張卡片，顯示草稿的標題。按 1 查看草稿，按 2 兩次以按原樣發送，或按 0 關閉它。已關閉的草稿會保留在您的佇列中。關閉卡片後，Claude Code 會詢問是否關閉 Claude 起草的回饋。一旦您拒絕兩次，它就會停止詢問。

預設情況下，您在一個工作階段中最多看到三張卡片；Anthropic 可以從伺服器調整該限制，無需發佈。超過限制後，以及每當您將 feedbackDrafts 設定為 quiet 時，您只會在提示頁尾看到佇列中草稿的計數。

查看和編輯草稿

執行不帶引數的 /feedback 以開啟您的佇列。它列出來自所有工作階段的每份佇列中的草稿，包括您關閉或從未看到其卡片的草稿。選擇一份草稿以開啟它進行查看，您可以：

• 編輯標題、區域和詳細資訊
• 將 Send transcript 設定為 yes 或 no。當 Claude 將草稿加入佇列的工作階段中的文字記錄仍然可用時，它會以 yes 開始，這會將該對話發送給 Anthropic；no 只發送報告
• 發送草稿、捨棄它，或將其保留在佇列中以供稍後使用

若要自己撰寫報告，請按 w 以開啟標準回饋對話框。/feedback 後面跟著文字，以及 /bug，會直接開啟該對話框。

發送草稿

當您發送草稿時，Claude Code 會以與 /feedback 報告相同的方式提交它，具有相同的保留期，並從您的機器中刪除草稿。當您從卡片發送時，它會顯示 ✓ Sent；當您從佇列發送時，它會關閉並顯示收據 ID。

報告包含：

• 您的標題、區域和詳細資訊
• 環境資訊，例如您的 Claude Code 版本、作業系統和模型
• 最近 API 請求的 ID
• 對話文字記錄，當您在查看畫面上將 Send transcript 保留為 yes 時。從卡片發送永遠不會包含文字記錄

Claude Code 會將您的工作目錄保留在本機草稿中，以便它可以找到文字記錄，並且不會發送該目錄。

在零資料保留的組織中，Claude Code 會將該工具排除在外，就像它對 /feedback 所做的那樣。如果此類組織中的工作階段仍然提供該工具，草稿會保留在您的機器上，發送會失敗並顯示 Feedback collection is not available for organizations with custom data retention policies.

捨棄或保留草稿

當您捨棄草稿時，Claude Code 會從您的機器中刪除它。您在佇列中保留的草稿會在 30 天後過期，或在 cleanupPeriodDays 更短時過期。佇列在所有工作階段中最多保留 10 份草稿，當 Claude 將第 11 份加入佇列時，Claude Code 會刪除最舊的。當您執行 /exit 且工作階段中的草稿仍在佇列中時，Claude Code 會詢問您是否在退出前查看或捨棄它們。

關閉 Claude 起草的回饋

在 /config 中將 Claude-drafted feedback 設定為 off，這會寫入 feedbackDrafts 設定，或為一個工作階段設定 CLAUDE_CODE_SEND_FEEDBACK=0。使用任一方式，Claude 都無法將草稿加入佇列。若要在沒有卡片的情況下繼續起草，請改為將 feedbackDrafts 設定為 quiet。管理員可以在受管設定中設定 feedbackDrafts，這優先於您自己的設定。

沒有 Claude 起草回饋的工作階段

Claude Code 在使用 Claude API 而非雲端提供者的您自己機器上的互動式終端工作階段中包含該工具。它將該工具排除在外：

• 非互動式 -p 執行和代理 SDK 工作階段，這些沒有螢幕來查看佇列
• 雲端工作階段，例如 Claude Code on the web，無法寫入您機器上的佇列
• Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 或 Microsoft Foundry 上的工作階段
• 您設定 CLAUDE_CODE_SEND_FEEDBACK=0 或 DISABLE_FEEDBACK_COMMAND=1 的工作階段，將 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 設定為任何非空值，或關閉功能旗標擷取
• 已關閉產品回饋的組織，以及零資料保留的組織

Task 工具可用性

Task 追蹤工具 TaskCreate、TaskGet、TaskUpdate、TaskList 和 TodoWrite 預設僅在 Claude 3.x 模型、Opus 4 至 4.7、Sonnet 4 至 4.6 和 Haiku 4.5 上可用。只要工具可用，您就會獲得四個 Task 工具，或當您設定 CLAUDE_CODE_ENABLE_TASKS=0 時改為 TodoWrite。

在所有其他模型上，Claude Code 會排除這些工具，除非您選擇加入。同樣的情況也適用於 Claude Code 無法識別的模型 ID，例如透過 LLM 閘道提供的自訂模型名稱。在較新的模型上，Claude 可以在沒有書面檢查清單的情況下追蹤多步驟工作，而工具的定義和提醒會佔用上下文。沒有這些工具，Claude 在工作時不會向任務清單添加任何內容。

如果您想在預設情況下沒有這些工具的模型上使用它們，請執行以下其中一項操作：

• 在啟動 Claude Code 之前匯出 CLAUDE_CODE_ENABLE_TODO_TOOLS=1，例如 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude。Claude Code 隨後會在每個模型和每個提供者上提供相同的工具
• 在 --allowedTools 中命名其中一個工具，例如 claude --allowedTools TaskCreate
• 在 --tools 中列出工具，這會將工作階段的內建工具限制為其命名的工具。將您想要的工具與您使用的其他內建工具一起包含
• 在 Agent SDK 中，allowedTools 和 tools 選項的工作方式與這兩個旗標相同

在背景工作階段和網路上的 Claude Code 中，Claude Code 在每個模型上提供相同的工具，無論是否列出。

Claude Code 只有在您的工作階段具有工具時才會向子代理提供工具，即使子代理執行不同的模型也是如此。同程序代理團隊隊友會以相同方式跟隨您的工作階段，而在其自己的分割窗格中的隊友會作為單獨的 Claude Code 程序執行，因此其自己的模型會決定。沒有 Task 工具，代理會透過訊息而不是共用任務清單與其團隊協調。

此處描述的預設集合適用於 Claude Code v2.1.268 及更新版本。

WebFetch 工具行為

WebFetch 接受一個 URL 和一個描述要提取內容的提示。它會擷取頁面，當伺服器返回 HTML 時將回應轉換為 Markdown，並使用一個小型、快速的模型針對內容執行提示。對於大多數擷取，Claude 會收到該模型的答案，而不是原始頁面。轉換步驟無法設定。

這使得 WebFetch 在設計上是有損的。提取提示決定了什麼會到達 Claude，所以一個說頁面沒有提及某事的結果可能只是意味著提示沒有詢問它。要求 Claude 使用更具體的提示再次擷取，或透過 Bash 使用 curl 來取得未處理的頁面。

有幾個行為會影響 Claude 收到的回應：

• HTTP URL 會自動升級為 HTTPS。
• 大型頁面會在處理前被截斷至固定字元限制。
• WebFetch 預設會快取每個回應 15 分鐘，所以重複擷取相同 URL 會快速返回。在 Claude Code v2.1.233 或更新版本上，設定 CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS 以變更 WebFetch 保留每個回應的時間長度。
• 一個頁面如果在五分鐘內未完成下載（包括 WebFetch 跟隨的任何重新導向），會因為截止時間錯誤而失敗。在 Claude Code v2.1.268 或更新版本上，設定 CLAUDE_CODE_WEBFETCH_DEADLINE_MS 以變更限制，或設定為 0 以移除它。
• 當 URL 重新導向到不同的主機時，WebFetch 會返回一個文字結果，命名原始 URL 和重新導向目標，而不是跟隨它。Claude 隨後會使用第二個 WebFetch 呼叫擷取新 URL。
• 當提取步驟遇到過載的 API 時，Claude Code 會以退避方式重試它；仍然失敗的擷取會返回錯誤結果。在 v2.1.212 之前，API 錯誤文字可能會作為提取的頁面內容到達 Claude。

在手動和 acceptEdits 權限模式中，WebFetch 會在擷取前提示，除非您的 權限規則已允許或拒絕該域名，以及一組內建的預先批准文件域名可以無提示擷取。無論您的規則允許什麼，擷取也必須先通過 WebFetch 域名安全檢查；該部分涵蓋檢查發送的內容和跳過它的設定。提示提供三個選項：

• 是：僅批准此擷取。下一個 WebFetch 呼叫會再次提示，即使是相同的域名。
• 是，且不再詢問 <domain>：批准擷取並將 WebFetch(domain:...) 允許規則保存到該域名的 .claude/settings.local.json 以供該儲存庫使用。請參閱 已保存的批准如何持續。當您的組織設定 allowManagedPermissionRulesOnly 時，Claude Code 會隱藏此選項。
• 否，並告訴 Claude 應該如何不同地做：拒絕擷取。

若要提前允許域名而不提示，請新增允許規則，例如 WebFetch(domain:example.com)；WebFetch(domain:*) 允許每個域名。auto 和 bypassPermissions 權限模式會跳過提示，除非明確的 ask 規則符合該域名。

deny、ask 或 allow 中的明確 WebFetch(domain:...) 規則優先於預先批准的集合，所以您可以阻止預先批准的域名或要求提示。

WebFetch 設定一個以 Claude-User 開頭的 User-Agent 標頭，以及一個 Accept 標頭，優先使用 Markdown 而不是 HTML，以便支援內容協商的伺服器可以直接返回 Markdown。

沙箱化命令不會繼承 WebFetch 的內建預先批准文件域名集合。若要讓沙箱化命令無提示地到達域名，請將域名新增到 allowedDomains 或使用 WebFetch(domain:...) 規則允許它，沙箱也會遵守。WebFetch 不會反過來讀取沙箱允許清單，所以將域名新增到沙箱或組織網路允許清單不會阻止 WebFetch 提示它。

WebSearch 工具行為

WebSearch 針對 Anthropic 的網路搜尋後端執行查詢，並傳回結果標題和 URL。它不會擷取結果頁面。若要讀取 Claude 在搜尋結果中找到的頁面，它會後續使用 WebFetch。

該工具每次呼叫最多可發出八個後端搜尋，在傳回結果前在內部精煉搜尋。Claude 可以使用 allowed_domains 限制結果範圍以僅包含特定主機，或使用 blocked_domains 排除它們。這兩個清單無法在單一呼叫中結合。

當搜尋請求擊中過載的 API 時，Claude Code 會以退避方式重試；仍然失敗的呼叫會傳回錯誤結果。在 v2.1.212 之前，API 錯誤文字可能會作為搜尋結果傳達給 Claude。

WebSearch 權限規則不採用指定符。allow 或 deny 中的單純 WebSearch 項目是唯一形式。

搜尋後端不可設定。若要使用不同的提供者進行搜尋，請新增公開搜尋工具的 MCP 伺服器。

工作階段搜尋限制

一個工作階段最多可進行 200 次 WebSearch 呼叫，計算跨越主對話和它產生的每個子代理，因此平行研究展開所進行的搜尋會計入相同的限制。該限制需要 Claude Code v2.1.212 或更新版本。當 Claude 達到限制時，進一步的呼叫會傳回通知，告訴 Claude 繼續使用它已經收集的資訊，而不是會邀請重試的錯誤。您看不到通知：受限的呼叫在對話中顯示為未執行任何操作的搜尋，如果 Claude 需要更多搜尋，通知會告訴它要求您提高限制。

設定 CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION 環境變數以變更上限；它接受正整數，因此上限可以提高但無法關閉。執行 /clear 會重設計數。如果仍然可以產生子代理的工作（例如執行中的工作流程）在清除後存留，計數會改為進行。

Write 工具行為

Write 工具會建立新檔案或以提供的完整內容覆寫現有檔案。它不會附加或合併。

Claude 是否必須在目前對話中讀取現有檔案後才能覆寫該檔案，取決於模型和檔案：

• Claude Opus 4.6、Claude Haiku 4.5 和較舊的模型始終需要讀取，因此對未讀取的現有檔案進行 Write 會失敗並出現錯誤。
• 較新的模型可以在與讀取前編輯相同的條件下覆寫他們在此工作階段中從未讀取的檔案：讀取它不需要權限提示，且 Read 工具可用。
• Jupyter 筆記本和 Claude 僅部分讀取且帶有PARTIAL view 通知的檔案，在每個模型上都需要讀取。

此限制不適用於新檔案。在 v2.1.228 之前，每個模型都需要在覆寫現有檔案前進行讀取。

使用 Bash 檢視檔案也滿足此要求，遵循編輯工具行為中描述的相同規則。

對於現有檔案的部分變更，Claude 使用 Edit 而不是 Write。

檢查哪些工具可用

您的確切工具集取決於您的提供者、平台和設定。若要檢查在執行中的工作階段中載入了什麼，請直接詢問 Claude：

What tools do you have access to?

Claude 提供對話摘要。如需確切的 MCP 工具名稱，請執行 /mcp。

另請參閱

• MCP servers：透過連接外部伺服器新增自訂工具
• 權限：權限系統、規則語法和工具特定模式
• Subagents：為 subagents 設定工具存取
• Hooks：在工具執行前後執行自訂命令