智能体

智能体是专门用于特定任务和工作流程的 AI 助手。它们允许你创建具有自定义提示词、模型和工具访问权限的专用工具。

类型

OpenCode 中有两种类型的智能体：主智能体和子智能体。

主智能体

主智能体是直接交互的主要助手。你可以使用 Tab 键或配置的 switch_agent 快捷键在它们之间切换。

OpenCode 附带两个内置主智能体：Build 和 Plan。

子智能体

子智能体是主智能体可以为特定任务调用的专业助手。你也可以通过在消息中 @ 提及 它们来手动调用。

OpenCode 附带三个内置子智能体：General、Explore 和 Scout。

内置智能体

OpenCode 附带两个内置主智能体和三个内置子智能体。

使用 Build

模式: primary

Build 是默认的主智能体，启用了开发工作的所有工具。

使用 Plan

模式: primary

一个专为规划和分析设计的受限智能体。默认情况下，file edits 和 bash 设置为 ask。适用于分析代码而不进行修改。

使用 General

模式: subagent

一个通用智能体，用于研究复杂问题和执行多步骤任务。具有并行工作的完整工具访问权限。

使用 Explore

模式: subagent

一个快速的只读智能体，用于探索代码库。使用它可以快速查找文件、搜索代码或回答关于代码库的问题。

使用 Scout

模式: subagent

一个用于外部文档和依赖研究的只读智能体。使用它来检查库源码或将本地代码与上游实现进行交叉参考。

使用 Compaction

模式: primary | 隐藏

系统智能体，将长上下文压缩为更小的摘要。在需要时自动运行。

使用 Title

模式: primary | 隐藏

系统智能体，生成会话标题。自动运行。

使用 Summary

模式: primary | 隐藏

系统智能体，创建会话摘要。自动运行。

使用方法

对于主智能体，在会话期间使用 Tab 键在它们之间切换。
子智能体可以通过以下方式调用：
- 由主智能体根据其描述自动调用
- 通过 @ 提及子智能体手动调用：@general help me search for this function
会话之间导航：当子智能体创建子会话时：
- session_child_first（默认：Leader+Down）进入第一个子会话
- session_child_cycle（默认：Right）循环到下一个子会话
- session_parent（默认：Up）返回父会话

配置

智能体可以通过两种方式配置：

JSON

在 opencode.json 中配置智能体：

{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Markdown

使用 markdown 文件定义智能体：

全局：~/.config/opencode/agents/
项目级：.opencode/agents/

---
description: Reviews code for quality
mode: subagent
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on security, performance, and maintainability.

配置选项

Description

必填 - 智能体功能的简要描述。

Temperature

用 temperature 控制随机性：

0.0-0.2：非常专注，适合代码分析
0.3-0.5：平衡，适合一般开发
0.6-1.0：更有创意，适合头脑风暴

Max Steps

控制强制文本响应之前的最大智能体迭代次数。

{
  "agent": {
    "quick-thinker": {
      "steps": 5
    }
  }
}

Disable

设置 disable: true 禁用智能体。

Prompt

指定自定义系统提示词文件：

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Model

为此智能体覆盖模型：

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

Permissions

配置权限以管理智能体可以执行的操作：

"ask" — 运行前请求批准
"allow" — 无需批准直接允许
"deny" — 禁用该工具

可用权限键：read、edit、glob、grep、list、bash、task、external_directory、todowrite、webfetch、websearch、lsp、skill、question、doom_loop

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Mode

控制智能体模式：primary、subagent 或 all。

Hidden

使用 hidden: true 从 @ 自动补全菜单中隐藏子智能体。适用于仅通过编程方式调用的内部智能体。

Task Permissions

控制智能体可以通过 Task 工具调用哪些子智能体：

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Color

使用 color（十六进制或主题色：primary、secondary、accent、success、warning、error、info）自定义智能体的视觉外观。

Top P

控制随机性的温度替代方案（0.0 到 1.0）。

Additional

任何其他选项直接传递给 provider，用于模型特定的功能。

创建智能体

使用以下命令创建新智能体：

opencode agent create

这个交互式命令将：

询问保存位置（全局或项目）
询问智能体描述
生成系统提示词和标识符
让你选择权限
创建 markdown 文件

示例

文档助手

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

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

安全审计员

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---

You are a security expert. Look for input validation vulnerabilities, authentication flaws, data exposure risks.