---
title: 代理
description: 設定和使用專門的代理。
---

代理是專門的 AI 助理，可以針對特定任務和工作流程進行設定。它們允許您建立具有自定義提示、模型和工具存取權限的專用工具。

:::tip
使用計畫代理來分析程式碼並審閱建議，而無需進行任何程式碼變更。
:::

您可以在工作階段期間在代理之間切換，或使用 `@` 提及來呼叫它們。

---

## 類型

opencode 中有兩種類型的代理；主要代理和子代理。

---

### 主要代理

主要代理是與您直接互動的主要助理。您可以使用 **Tab** 鍵或您設定的 `switch_agent` 鍵綁定循環切換它們。這些代理處理您的主要對話。工具存取是透過權限設定的 - 例如，「Build」啟用了所有工具，而「Plan」則受到限制。

:::tip
您可以在工作階段期間使用 **Tab** 鍵在主要代理之間切換。
:::

opencode 附帶兩個內建的主要代理：**Build** 和 **Plan**。我們將在下面看看這些。

---

### 子代理

子代理是主要代理可以呼叫來執行特定任務的專業助理。您也可以透過在訊息中 **@提及** 它們來手動呼叫它們。

opencode 附帶兩個內建子代理：**General** 和 **Explore**。我們將在下面看看這個。

---

## 內建

opencode 附帶兩個內建主代理和兩個內建子代理。

---

### 使用 Build (構建)

_模式_：`primary`

Build 是啟用所有工具的**預設**主要代理。這是用於需要完全存取檔案操作和系統指令的開發工作的標準代理。

---

### 使用 Plan (計畫)

_模式_：`primary`

專為規劃和分析而設計的受限代理。我們使用權限系統為您提供更多控制並防止意外變更。
預設情況下，以下所有項均設定為 `ask`：

- `file edits`：所有寫入、修補和編輯
- `bash`：所有 bash 指令

當您希望 LLM 分析程式碼、建議變更或建立計畫而不對程式碼庫進行任何實際修改時，此代理非常有用。

---

### 使用 General (一般)

_模式_：`subagent`

用於研究複雜問題和執行多步驟任務的通用代理。具有完整的工具存取權限（待辦事項除外），因此可以在需要時變更檔案。使用它可以並行執行多個工作單元。

---

### 使用 Explore (探索)

_模式_：`subagent`

用於探索程式碼庫的快速唯讀代理。無法修改檔案。當您需要按模式快速尋找檔案、搜尋程式碼中的關鍵字或回答有關程式碼庫的問題時，請使用此功能。

---

### 使用 Compact (壓縮)

_模式_：`primary`

隱藏的系統代理，將長上下文壓縮為較小的摘要。它會在需要時自動執行，並且無法在 UI 中選擇。

---

### 使用 Title (標題)

_模式_：`primary`

生成短工作階段標題的隱藏系統代理。它會自動執行，並且無法在 UI 中選擇。

---

### 使用 Summarize (摘要)

_模式_：`primary`

建立工作階段摘要的隱藏系統代理。它會自動執行，並且無法在 UI 中選擇。

---

## 用法

1. 對於主要代理，請在工作階段期間使用 **Tab** 鍵循環切換它們。您也可以使用設定的 `switch_agent` 鍵綁定。

2. 可以呼叫子代理：
   - **自動**由主要代理根據其描述執行專門任務。
   - 透過在訊息中 **@提及** 子代理手動進行。例如：

     ```txt frame="none"
     @general help me search for this function
     ```

3. **工作階段之間導航**：當子代理建立自己的子工作階段時，您可以使用以下指令在父工作階段和所有子工作階段之間導航：
   - **\<Leader>+Right**（或您設定的 `session_child_cycle` 鍵綁定）向前循環父級 → 子級 1 → 子級 2 → ... → 父級
   - **\<Leader>+Left**（或您設定的 `session_child_cycle_reverse` 鍵綁定）向後循環父級 ← 子級 1 ← 子級 2 ← ... ← 父級

   這使您可以在主要對話和專門的子代理工作之間無縫切換。

---

## 設定

您可以自定義內建代理或透過設定建立您自己的代理。可以透過兩種方式設定代理：

---

### JSON

在 `opencode.json` 設定檔中設定代理：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}
```

---

### Markdown

您也可以使用 Markdown 檔案定義代理。將它們放入：

- 全域：`~/.config/opencode/agents/`
- 每個專案：`.opencode/agents/`

```markdown title="~/.config/opencode/agents/review.md"
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.
```

Markdown 檔名成為代理名稱。例如，`review.md` 建立 `review` 代理。

---

## 選項

讓我們詳細看看這些設定選項。

---

### 描述 (Description)

使用 `description` 選項提供代理的作用以及何時使用它的簡要描述。

```json title="opencode.json"
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}
```

這是一個**必需的**設定選項。

---

### 溫度 (Temperature)

使用 `temperature` 設定控制 LLM 回應的隨機性和創造性。

較低的值使回應更加集中和確定，而較高的值則增加創造力和可變性。

```json title="opencode.json"
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}
```

溫度值的範圍通常為 0.0 到 1.0：

- **0.0-0.2**：非常集中且確定的回應，非常適合程式碼分析和規劃
- **0.3-0.5**：具有一定創造力的平衡回應，適合一般開發任務
- **0.6-1.0**：更有創意和多樣化的反應，有助於腦力激盪和探索

```json title="opencode.json"
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}
```

如果未指定溫度，opencode 將使用特定於模型的預設值；大多數模型通常為 0，Qwen 模型為 0.55。

---

### 最大步數 (Steps)

控制代理在被迫僅使用文字回應之前可以執行的最大代理迭代次數。這允許希望控制成本的使用者對代理操作設定限制。

如果未設定，代理將繼續迭代，直到模型選擇停止或使用者中斷工作階段。

```json title="opencode.json"
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}
```

當達到限制時，代理會收到特殊的系統提示，指示其回應其工作摘要和建議的剩餘任務。

:::caution
舊版 `maxSteps` 欄位已棄用。請改用 `steps`。
:::

---

### 禁用 (Disable)

設定為 `true` 以禁用代理。

```json title="opencode.json"
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}
```

---

### 提示 (Prompt)

使用 `prompt` 設定為此代理指定自定義系統提示檔案。提示檔案應包含特定於代理目的的說明。

```json title="opencode.json"
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}
```

該路徑是相對於設定檔所在位置的。因此，這適用於全域 opencode 設定和專案特定設定。

---

### 模型 (Model)

使用 `model` 設定覆蓋此代理的模型。對於使用針對不同任務最佳化的不同模型很有用。例如，更快的規劃模型、更強大的實作模型。

:::tip
如果您不指定模型，主代理將使用 [全域設定的模型](/docs/config#models)，而子代理將使用呼叫子代理的主代理的模型。
:::

```json title="opencode.json"
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}
```

opencode 設定中的模型 ID 使用格式 `provider/model-id`。例如，如果您使用 [OpenCode Zen](/docs/zen)，則您將使用 `opencode/gpt-5.1-codex` 來表示 GPT 5.1 Codex。

---

### 工具 (Tools)

使用 `tools` 設定控制此代理中可用的工具。您可以透過將特定工具設定為 `true` 或 `false` 來啟用或禁用特定工具。

```json title="opencode.json" {3-6,9-12}
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}
```

:::note
特定於代理的設定會覆蓋全域設定。
:::

您也可以使用萬用字元同時控制多個工具。例如，要禁用 MCP 伺服器中的所有工具：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}
```

[了解有關工具的更多資訊](/docs/tools)。

---

### 權限 (Permissions)

您可以設定權限來管理代理可以執行的操作。目前，`edit`、`bash` 和 `webfetch` 工具的權限可以設定為：

- `"ask"` — 執行工具之前提示批准
- `"allow"` — 未經批准允許所有操作
- `"deny"` — 禁用該工具

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}
```

您可以覆蓋每個代理的這些權限。

```json title="opencode.json" {3-5,8-10}
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}
```

您還可以在 Markdown 代理中設定權限。

```markdown title="~/.config/opencode/agents/review.md"
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.
```

您可以設定特定 bash 指令的權限。

```json title="opencode.json" {7}
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}
```

這可以採用全域模式。

```json title="opencode.json" {7}
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}
```

您也可以使用 `*` 萬用字元來管理所有指令的權限。
由於最後一個匹配規則優先，因此將 `*` 萬用字元放在前面，將特定規則放在後面。

```json title="opencode.json" {8}
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}
```

[了解有關權限的更多資訊](/docs/permissions)。

---

### 模式 (Mode)

使用 `mode` 設定控制代理的模式。 `mode` 選項用於確定如何使用代理。

```json title="opencode.json"
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}
```

`mode` 選項可設定為 `primary`、`subagent` 或 `all`。如果未指定 `mode`，則預設為 `all`。

---

### 隱藏 (Hidden)

使用 `@` 從 `hidden: true` 自動完成選單隱藏子代理。對於只能由其他代理透過任務工具以程式化方式呼叫的內部子代理很有用。

```json title="opencode.json"
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}
```

這僅影響自動完成選單中的使用者可見性。如果權限允許，模型仍然可以透過任務工具呼叫隱藏代理。

:::note
僅適用於 `mode: subagent` 代理。
:::

---

### 任務權限 (Task Permissions)

使用 `permission.task` 控制代理可以透過任務工具呼叫哪些子代理。使用 glob 模式進行靈活匹配。

```json title="opencode.json"
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}
```

當設定為 `deny` 時，子代理將從任務工具描述中完全刪除，因此模型不會嘗試呼叫它。

:::tip
規則按順序評估，**最後匹配的規則獲勝**。在上面的範例中，`orchestrator-planner` 匹配 `*`（拒絕）和 `orchestrator-*`（允許），但由於 `orchestrator-*` 位於 `*` 之後，因此結果為 `allow`。
:::

:::tip
使用者始終可以透過 `@` 自動完成選單直接呼叫任何子代理，即使代理的任務權限會拒絕它。
:::

---

### 顏色 (Color)

使用 `color` 選項自定義代理在 UI 中的視覺外觀。這會影響代理在介面中的顯示方式。

使用有效的十六進位顏色（例如 `#FF5733`）或主題顏色：`primary`、`secondary`、`accent`、`success`、`warning`、`error`、`info`。

```json title="opencode.json"
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}
```

---

### Top P

使用 `top_p` 選項控制回應多樣性。控制隨機性的溫度替代方案。

```json title="opencode.json"
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}
```

值範圍從 0.0 到 1.0。較低的值更加集中，較高的值更加多樣化。

---

### 額外選項 (Extra)

您在代理設定中指定的任何其他選項都將作為模型選項**直接**傳遞給供應商。這允許您使用特定於供應商的功能和參數。

例如，使用 OpenAI 的推理模型，您可以控制推理工作：

```json title="opencode.json" {6,7}
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}
```

這些附加選項是特定於模型和供應商的。檢查供應商的文件以獲取可用參數。

:::tip
執行 `opencode models` 查看可用模型的列表。
:::

---

## 建立代理

您可以使用以下指令建立新代理：

```bash
opencode agent create
```

此互動式指令將：

1. 詢問代理保存在哪裡；全域或特定專案。
2. 描述代理應該做什麼。
3. 生成適當的系統提示和標識符。
4. 讓您選擇代理可以存取哪些工具。
5. 最後，使用代理設定建立一個 markdown 檔案。

---

## 使用案例

以下是不同代理的一些常見使用案例。

- **Build 代理**：啟用所有工具的完整開發工作
- **Plan 代理**：分析規劃，不做改動
- **Review 代理**：具有唯讀存取權限和文件工具的程式碼審查
- **Debug 代理**：專注於啟用 bash 和讀取工具的調查
- **Docs 代理**：使用檔案操作但不使用系統指令的文件編寫

---

## 範例

以下是一些您可能會覺得有用的範例代理。

:::tip
您有想要分享的代理嗎？ [提交 PR](https://github.com/anomalyco/opencode)。
:::

---

### 文件代理

```markdown title="~/.config/opencode/agents/docs-writer.md"
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language
```

---

### 安全稽核員

```markdown title="~/.config/opencode/agents/security-auditor.md"
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues
```