Agents Troubleshooting Task Tool FAQ

Agent 疑難排解指南：常見問題與解決方案

使用 Claude Code Agents 時遇到的常見問題及其解決方法。涵蓋逾時、結果不完整、平行執行失敗等問題的診斷與修復。

• 更新於 • 12 分鐘閱讀 • 作者：Claude World

使用 Claude Code 的 Agent tool（v2.1.63 之前稱為 Task tool；下方的 Task({...}) 範例使用這個仍受支援的別名）和 agents 時，你可能會遇到一些常見問題。本指南涵蓋最頻繁的問題及其解決方案。

2026 年 10 月 21 日更新： 依 Claude Code v2.1.305 更新——subagent 現在預設在背景執行、TaskOutput 已移除（v2.1.277）、內建 Explore agent 改用主對話的模型而非 Haiku、haiku 現在指 Haiku 5.5，模型、同時執行上限與錯誤訊息的建議也已改為現行行為。

常見問題分類

類型典型症狀常見原因
啟動問題Agent 無法啟動、立即失敗權限、配置、路徑錯誤
逾時問題Agent 執行時間過長Context 過大、任務複雜、資源限制
結果問題結果不完整、不正確Prompt 模糊、Context 不足
平行問題Agents 未平行執行錯誤的呼叫方式、資源競爭
效能問題速度慢、記憶體消耗大模型選擇、任務設計

問題 1：Agent 無法啟動或立即失敗

症狀

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore auth module"
})
// 錯誤: "Failed to start agent" 或立即返回錯誤

可能原因與解決方案

原因 1：工作目錄錯誤

問題：當前目錄不是專案根目錄。

解決：

# 確認你在專案根目錄
pwd
# 應該看到專案路徑，例如 /Users/you/projects/my-app

# 如果不在，切換到正確目錄
cd /path/to/your/project

原因 2：Git Repository 未初始化

問題：某些 agent 功能需要 git 歷史記錄。

解決：

# 初始化 git repo
git init
git add .
git commit -m "Initial commit"

原因 3：檔案權限問題

問題：Claude Code 無法讀取專案檔案。

解決：

# 檢查檔案權限
ls -la

# 如果需要，修復權限
chmod -R +r ./

原因 4：模型不可用

問題：你無法使用指定的模型——組織的 availableModels 允許清單排除了它、雲端供應商帳號尚未啟用它，或你的 Claude Code 版本低於該模型的需求（Opus 5.5 需要 v2.1.280+、Sonnet 5.5 需要 v2.1.284+、Haiku 5.5 需要 v2.1.293+）。Opus 本身不需要特殊許可：Opus 5.5 是 Pro、Max、Team、Enterprise 與 Anthropic API 的預設模型。

解決：如果錯誤訊息說你的版本不支援該模型，請執行 claude update。若是組織限制的模型，Claude Code 會改用允許的模型執行該 agent 並顯示通知；執行 /tasks 可查看每個 agent 實際使用的模型。

// 指定你的方案或供應商允許的模型，
// 或省略 `model`，沿用主對話的模型
Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // 在 Anthropic API 上為 Sonnet 5.5
  prompt: "Your task"
})

問題 2：Agent 執行逾時

症狀

Agent 執行超過預期時間（例如 2 分鐘以上），沒有返回結果。

可能原因與解決方案

原因 1：任務範圍太廣

問題：Prompt 太模糊，導致 agent 掃描整個專案。

壞例子：

Task({
  subagent_type: "Explore",
  prompt: "Analyze everything about this codebase"  // 太廣泛
})

好例子：

Task({
  subagent_type: "Explore",
  prompt: "Explore authentication module (thoroughness: medium). Find JWT handling and session management."
})

原因 2：使用過高的徹底程度

問題：very thorough 等級適用於小範圍，對整個專案來說太慢。

解決：

// 對大範圍使用 medium 或 quick
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore entire codebase structure (thoroughness: quick)"
})

// 對小範圍使用 very thorough
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Deep dive into auth/login.ts (thoroughness: very thorough)"
})

原因 3：Context 過大

問題：Agent 需要處理的檔案太多。

解決：分割任務

// 壞：一次處理所有模組
Task({ prompt: "Analyze all API endpoints" })

// 好：分開處理
Task({ prompt: "Analyze user-related API endpoints" })
Task({ prompt: "Analyze payment-related API endpoints" })
Task({ prompt: "Analyze admin-related API endpoints" })

原因 4：使用背景任務但未檢查

問題：Agent 在背景執行，你以為逾時了。在沒有任何設定的情況下，Claude 從主對話啟動的 agent 預設就在背景執行（互動式終端機 session 自 v2.1.232 起），所以對話記錄安靜下來，通常代表 agent 還在工作。

解決：執行 /tasks 查看執行中與剛完成的 agent，以及各自使用的模型。結果會在之後的回合以完成通知送達 Claude；在那之前詢問進度，Claude 會回報 agent 仍在執行。

// 啟動背景任務
Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: "Comprehensive security audit",
  run_in_background: true
})

// TaskOutput 已在 v2.1.277 移除：結果會以完成通知送達。
// 用 /tasks 查看進度；在 /tasks 中按 x 可停止執行
// （Claude 則使用 TaskStop）。

問題 3：Agent 回傳結果不完整

症狀

Agent 返回的結果缺少預期的內容，或只回答了一部分問題。

可能原因與解決方案

原因 1：Prompt 模糊

問題：Agent 不確定要找什麼。

壞例子：

Task({
  prompt: "Look at the auth code and tell me what you think"  // 太模糊
})

好例子：

Task({
  prompt: `
    Analyze authentication module (src/auth/).
    Report specifically on:
    1. JWT secret storage (how is it stored?)
    2. Session management (what strategy?)
    3. Password hashing (which algorithm?)

    Format as a bulleted list.
  `
})

原因 2：單次請求太多問題

問題：Prompt 包含太多要求，agent 遺漏了一些。

解決：分多次請求

// 壞：一次詢問所有事
Task({
  prompt: "Analyze auth, payments, user management, admin panel, and reporting"
})

// 好：分開詢問
Task({ prompt: "Analyze authentication system" })
Task({ prompt: "Analyze payment system" })
Task({ prompt: "Analyze user management" })

原因 3：Context 不足

問題：Agent 沒有足夠的上下文理解你的需求。

解決：提供更多背景

Task({
  prompt: `
    Context: We're migrating from REST to GraphQL.
    Current state: All endpoints are in src/api/v1/

    Task: Find all REST endpoints and list which ones still need migration.
  `
})

原因 4：探索範圍錯誤

問題：Explore agent 的徹底程度等級不當。

解決：

// 對快速概覽使用 quick
Task({
  subagent_type: "Explore",
  prompt: "List all files in src/auth/ (thoroughness: quick)"
})

// 對深度分析使用 medium 或 very thorough
Task({
  subagent_type: "Explore",
  prompt: "Analyze authentication flow in detail (thoroughness: medium)"
})

問題 4：Parallel Agents 沒有平行執行

症狀

你啟動了多個 agents，但它們似乎依序執行而非平行。

可能原因與解決方案

原因 1：錯誤的呼叫方式

問題：在迴圈中依序呼叫 Task，而不是同時呼叫。這只會讓在前景執行的 agent 依序執行，因為 Claude 會等每個結果回來才進行下一次呼叫。在沒有任何設定的情況下，Claude 從主對話啟動的 agent 現在預設在背景執行並同時運作（互動式終端機 session 自 v2.1.232 起）；Claude 仍可在 claude -p 與 Agent SDK 中等待它們，互動式 session 則要先用 CLAUDE_CODE_FORK_SUBAGENT=0 關閉 fork 模式才能等待，而設定 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 時，Claude 會等待每一個 agent。

壞例子：

// 這會依序執行
const agents = ['auth', 'payment', 'user']
for (const topic of agents) {
  Task({ prompt: `Analyze ${topic}` })  // 依序執行！
}

好例子：

// 這會平行執行
Task({ prompt: "Analyze auth" })
Task({ prompt: "Analyze payment" })
Task({ prompt: "Analyze user" })
// 同時啟動，平行執行

原因 2：資源競爭

問題：太多 agents 同時執行，導致資源不足。此外，一個 session 中已有 20 個 agent 在執行時，Claude Code 會拒絕再啟動新的（Concurrent subagent limit reached；可用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 調整上限），而且每個 agent 都會消耗與主對話相同的用量額度。

解決：限制平行數量

// 壞：10 個平行 agents
for (let i = 0; i < 10; i++) {
  Task({ prompt: `Task ${i}` })
}

// 好：分批執行（每批 3-5 個）
// 批次 1
Task({ prompt: "Task 1" })
Task({ prompt: "Task 2" })
Task({ prompt: "Task 3" })
// 等待完成，然後批次 2
Task({ prompt: "Task 4" })
Task({ prompt: "Task 5" })
Task({ prompt: "Task 6" })

原因 3：Agents 有相依性

問題：後面的 agent 依賴前面的 agent 結果。

解決：分階段執行

// 階段 1：平行探索（獨立）
Task({ prompt: "Map file structure" })
Task({ prompt: "Find API endpoints" })
Task({ prompt: "List database models" })
// 等待完成

// 階段 2：使用階段 1 結果
Task({ prompt: "Based on structure found, analyze auth flow" })

問題 5：Agent 效能差或記憶體消耗大

症狀

Agent 執行緩慢，或系統記憶體使用量飆升。

可能原因與解決方案

原因 1：使用錯誤的模型

問題：簡單任務使用了昂貴的模型。

解決：選擇適當的模型

// 壞：簡單搜尋用 Opus
Task({
  subagent_type: "Explore",
  model: "opus",  // 太昂貴
  prompt: "Find login function"
})

// 好：簡單搜尋用 Haiku
Task({
  subagent_type: "Explore",
  model: "haiku",  // 快速且便宜
  prompt: "Find login function (thoroughness: quick)"
})

Explore 已不再預設使用 Haiku：自 v2.1.198 起，內建的 Explore agent 使用主對話的模型——在 Pro、Max、Team、Enterprise 與 Anthropic API 上預設為 Opus 5.5（若主 session 在 Claude 訂閱或 Anthropic Console 帳號上執行 Fable，Explore 則改用 Opus）。想讓搜尋保持便宜，可以像上面一樣傳入 model: "haiku"，或自行定義一個 model: haiku 的 Explore agent。在 Anthropic API 上，haiku 現在對應 Haiku 5.5；在 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry 與 Claude Platform on AWS 上仍是 Haiku 4.5。

原因 2：Context 過載

問題：Agent 載入了太多不必要的檔案。

解決：縮小範圍

// 壞：探索整個 monorepo
Task({
  prompt: "Analyze entire monorepo"
})

// 好：聚焦特定套件
Task({
  prompt: "Analyze packages/auth/ only"
})

原因 3：重複工作

問題：多個 agents 重複分析相同的檔案。

解決：協調任務

// 壞：重複探索
Task({ prompt: "Analyze auth for security" })
Task({ prompt: "Analyze auth for performance" })
Task({ prompt: "Analyze auth for code quality" })
// 三次讀取相同檔案

// 好：分工
Task({ prompt: "Explore auth module (thoroughness: medium)" })
// 然後使用結果進行不同分析

原因 4：未使用 Explore Agent

問題：使用 general-purpose agent 做檔案搜尋。

解決：

// 壞：用 general-purpose 搜尋檔案
Task({
  subagent_type: "general-purpose",
  prompt: "Find all files with 'auth' in the name"
})

// 好：用 Explore agent
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Find all auth-related files (thoroughness: quick)"
})

問題 6：選擇錯誤的 Agent 類型

症狀

結果不符合預期，或 agent 似乎不適合任務。

Agent 選擇指南

任務正確的 Agent錯誤的 Agent
檔案搜尋Explore（搭配 model: "haiku"）general-purpose
程式碼審查code-reviewerExplore
安全稽核security-auditorcode-reviewer
測試分析test-runnergeneral-purpose
除錯debuggerExplore
重構refactor-assistantgeneral-purpose

內建的只有 Explore、Plan 和 general-purpose（以及少數輔助 agent）。code-reviewer、security-auditor、test-runner、debugger 與 refactor-assistant 都是你在 .claude/agents/ 或 ~/.claude/agents/ 中自行定義、或由 plugin 提供的自訂 agent。如果 Claude 找不到某個 agent，請檢查它的 frontmatter：檔案沒有 name、有 name 卻沒有 description，或 YAML 無法解析時，Claude Code 會略過該檔案，且 session 中不會出現任何訊息。claude plugin validate .claude/agents 會標出無法解析的 frontmatter，claude --debug 則會在除錯記錄中記下大部分被略過的原因。若要審查程式碼，Claude Code 也內建 /code-review（別名 /review）與 /security-review。

範例

// ❌ 錯誤：用 Explore 做安全稽核
Task({
  subagent_type: "Explore",
  prompt: "Check for security vulnerabilities"
})

// ✅ 正確：用 security-auditor
Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: "Audit for security vulnerabilities"
})

問題 7：Agent 結果難以理解

症狀

Agent 返回的結果格式混亂，或難以整合到你的工作流程。

解決方案

方案 1：要求特定格式

Task({
  prompt: `
    Analyze the authentication module.

    Format your response as:
    ## Overview
    [2-3 sentences]

    ## Findings
    - [Bullet point 1]
    - [Bullet point 2]

    ## Recommendations
    1. [Recommendation 1]
    2. [Recommendation 2]
  `
})

方案 2：要求輸出 JSON

Task({
  prompt: `
    List all API endpoints.

    Respond in this JSON format:
    {
      "endpoints": [
        {"path": "/api/users", "method": "GET", "auth": true},
        {"path": "/api/users", "method": "POST", "auth": true}
      ]
    }
  `
})

方案 3：分階段收集結果

// 階段 1：收集原始資料
const rawData = Task({ prompt: "List all endpoints" })

// 階段 2：格式化
Task({
  prompt: `
    Format this data as a markdown table:
    ${rawData}

    Columns: Path, Method, Auth Required, Description
  `
})

診斷工具與技巧

技巧 1：逐步簡化

如果 agent 失敗，逐步簡化任務：

// 步驟 1：最小可行任務
Task({ prompt: "List files in src/" })

// 步驟 2：稍微複雜
Task({ prompt: "List files in src/auth/" })

// 步驟 3：完整任務
Task({ prompt: "Analyze auth module structure" })

技巧 2：使用 Verbose 模式

在問題診斷時，添加更多背景：

Task({
  prompt: `
    [VERBOSE MODE]
    I'm trying to understand why X fails.

    Please:
    1. List all files you examined
    2. Show your reasoning step-by-step
    3. Report any errors encountered

    Task: [your actual task]
  `
})

技巧 3：對照測試

同時使用不同 agent 比較結果：

// Agent 1
const result1 = Task({
  subagent_type: "Explore",
  prompt: "Find all auth functions"
})

// Agent 2
const result2 = Task({
  subagent_type: "general-purpose",
  prompt: "Find all auth functions"
})

// 比較結果差異

何時尋求幫助

如果以上解決方案都無法解決你的問題：

  1. 檢查 Claude Code 版本：

    claude --version

    確保使用最新版本。

  2. 查看 GitHub Issues： https://github.com/anthropics/claude-code/issues

  3. 加入社群：

  4. 回報 Bug： 在回報時包含：

    • Claude Code 版本
    • 作業系統
    • 完整的錯誤訊息
    • 重現步驟
    • 最小可重現範例

快速參考：常見錯誤碼

錯誤碼含義解決方案
ENOENT找不到指定路徑檢查檔案路徑是否正確
EACCES權限被拒絕檢查檔案權限
ETIMEDOUT執行逾時縮小任務範圍或降低徹底程度
ENOMEM記憶體不足減少平行 agents 數量
ECONNREFUSEDAPI 連線失敗檢查網路連線和 API Key
Agent '…' would be spawned with zero toolsagent 的 tools 清單中沒有任何項目對應到可用的工具修正工具名稱，或移除 tools 以沿用預設工具集
Concurrent subagent limit reached已有 20 個 agent 在執行（預設上限）等部分 agent 完成，或調高 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS
Agent terminated early due to an API error用量上限或伺服器錯誤使 agent 中途停止排除根本的錯誤後，請 Claude 重試或恢復（resume）該 agent

預防性最佳實踐

避免問題的最佳方法：

  1. 從小任務開始：先測試簡單任務，確認 agent 正常工作
  2. 使用適當的模型：Haiku 用於搜尋（在 Anthropic API 上為 Haiku 5.5），Sonnet 5.5 用於日常實作，Opus 5.5（預設模型）用於困難的推理
  3. 保持 Prompt 清晰：明確說明你想找什麼
  4. 分階段工作：探索 → 分析 → 實作
  5. 監控資源：留意記憶體和 CPU 使用量
  6. 保存工作結果：定期提交 git，避免遺失進度

遇到其他問題？在 Discord 的 #help 頻道提問，社群很樂意協助！