Skip to content
OpenCode 中文文档
HomeDocs

智能体

配置并使用专门的智能体。

智能体是专门的 AI 助手，可以针对特定的任务和工作流进行配置。它们允许你创建具有自定义提示词、模型和工具访问权限的专用工具。

你可以在会话期间切换智能体，或者通过 @ 提及来调用它们。

类型

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

主智能体

主智能体是你直接与之交互的主要助手。你可以使用 Tab 键或你配置的 switch_agent 按键绑定来循环切换它们。这些智能体处理你的主要对话，并且可以访问所有配置的工具。

OpenCode 带有两个内置的主智能体：Build 和 Plan。我们将在下面详细介绍。

子智能体

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

OpenCode 带有两个内置的子智能体：General 和 Explore。我们将在下面详细介绍。

内置智能体

OpenCode 带有两个内置的主智能体和两个内置的子智能体。

Build

模式: primary

Build 是 默认 的主智能体，启用了所有工具。这是进行开发工作的标准智能体，你需要对文件操作和系统命令拥有完全访问权限。

Plan

模式: primary

这是一个受限智能体，专为规划和分析而设计。我们使用权限系统为你提供更多控制权，并防止意外更改。默认情况下，以下所有内容都设置为 ask (询问)：

  • file edits: 所有写入、补丁和编辑
  • bash: 所有 bash 命令

当你希望 LLM 分析代码、建议更改或创建计划而不对代码库进行任何实际修改时，此智能体非常有用。

General

模式: subagent

一个通用智能体，用于研究复杂问题、搜索代码和执行多步骤任务。当你搜索关键词或文件，并且不确定在前几次尝试中能否找到匹配项时，请使用此智能体。

Explore

模式: subagent

一个快速智能体，专门用于探索代码库。当你需要通过模式快速查找文件、搜索代码关键词或回答有关代码库的问题时，请使用此智能体。

使用方法

  1. 对于主智能体，在会话期间使用 Tab 键循环切换它们。你也可以使用你配置的 switch_agent 按键绑定。

  2. 可以调用子智能体：

    • 由主智能体根据其描述为专门任务 自动调用。

    • 在你的消息中通过 @ 提及 子智能体来手动调用。例如：

      @general 帮我搜索这个函数

  3. 会话间导航: 当子智能体创建自己的子会话时，你可以在父会话和所有子会话之间进行导航，使用：

    • <Leader>+Right (或你配置的 session_child_cycle 按键绑定) 在 父会话 → 子会话1 → 子会话2 → … → 父会话 之间循环切换。
  • <Leader>+Left (或你配置的 session_child_cycle_reverse 按键绑定) 在 父会话 ← 子会话1 ← 子会话2 ← … ← 父会话 之间循环切换。

这允许你在主对话和专门的子智能体工作之间无缝切换。

配置

你可以通过配置来自定义内置智能体或创建自己的智能体。可以通过两种方式配置智能体：

JSON

在你的 opencode.json 配置文件中配置智能体：

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": "审查代码的最佳实践和潜在问题",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "你是一个代码审查员。专注于安全性、性能和可维护性。",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

你也可以使用 Markdown 文件定义智能体。将它们放置在：

  • 全局：~/.config/opencode/agent/
  • 项目特定：.opencode/agent/
~/.config/opencode/agent/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
---


你正处于代码审查模式。请关注：


- 代码质量和最佳实践
- 潜在的错误和边缘情况
- 性能影响
- 安全考虑


提供建设性的反馈，而不要直接进行更改。

Markdown 文件名即为智能体名称。例如，review.md 会创建一个 review 智能体。

选项

让我们详细看看这些配置选项。

描述

使用 description 选项提供关于智能体用途以及何时使用它的简短描述。

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

这是一个必填配置项。

温度

通过 temperature 配置控制 LLM 响应的随机性和创造力。

较低的值使响应更加集中和确定，而较高的值则增加创造力和变异性。

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: 更加富有创意和多样的响应，对头脑风暴和探索非常有用
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。

最大步数

控制智能体在被强制仅以文本响应之前可以执行的最大迭代次数。这允许希望控制成本的用户限制智能体的操作。

如果未设置此项，智能体将继续迭代，直到模型选择停止或用户中断会话。

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

达到限制时，智能体会收到一条特殊的系统提示，指示其总结其工作并推荐剩余任务。

禁用

设置为 true 以禁用该智能体。

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

提示词

使用 prompt 配置为该智能体指定自定义系统提示词文件。提示词文件应包含针对智能体用途的特定指令。

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

此路径相对于配置文件所在的位置。因此，这既适用于全局 OpenCode 配置，也适用于项目特定配置。

模型

使用 model 配置来覆盖此智能体的模型。适用于为不同任务使用优化的不同模型。例如，使用更快的模型进行规划，使用更强大的模型进行实现。

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

OpenCode 配置中的模型 ID 使用 provider/model-id 格式。例如，如果你正在使用 OpenCode Zen，你会为 GPT 5.1 Codex 使用 opencode/gpt-5.1-codex。

工具

使用 tools 配置控制此智能体可使用的工具。你可以通过将特定工具设置为 true 或 false 来启用或禁用它们。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

你还可以使用通配符同时控制多个工具。例如，要禁用来自某个 MCP 服务器的所有工具：

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

了解更多关于工具的信息。

权限

你可以配置权限来管理智能体可以采取的操作。目前，edit、bash 和 webfetch 工具的权限可以配置为：

  • "ask" — 在运行工具前提示审批
  • "allow" — 允许所有操作而无需审批
  • "deny" — 禁用该工具
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

你可以为每个智能体覆盖这些权限。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

你也可以在 Markdown 智能体中设置权限。

~/.config/opencode/agent/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "git diff": allow
    "git log*": allow
    "*": ask
  webfetch: deny
---


仅分析代码并建议更改。

你可以为特定的 bash 命令设置权限。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask"
        }
      }
    }
  }
}

这可以使用 glob 模式。

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

你还可以使用 * 通配符来管理所有命令的权限。特定规则可以覆盖 * 通配符。

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

了解更多关于权限的信息。

模式

使用 mode 配置控制智能体的模式。mode 选项用于确定智能体的使用方式。

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

mode 选项可以设置为 primary、subagent 或 all。如果未指定 mode，则默认为 all。

附加选项

你在智能体配置中指定的任何其他选项都将直接传递给提供商作为模型选项。这允许你使用提供商特定的功能和参数。

例如，对于 OpenAI 的推理模型，你可以控制推理力度：

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

这些附加选项是模型和提供商特定的。请查看你的提供商文档以获取可用参数。

创建智能体

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

Terminal window
opencode agent create

这个交互式命令将：

  1. 询问保存智能体的位置：全局或项目特定。
  2. 描述智能体应该做什么。
  3. 生成适当的系统提示词和标识符。
  4. 让你选择智能体可以访问哪些工具。
  5. 最后，创建一个包含智能体配置的 Markdown 文件。

使用场景

以下是不同智能体的一些常见使用场景。

  • Build 智能体: 启用所有工具的完整开发工作
  • Plan 智能体: 仅进行分析和规划而不进行更改
  • Review 智能体: 具有只读访问权限以及文档工具的代码审查
  • Debug 智能体: 侧重于调查，启用 bash 和读取工具
  • Docs 智能体: 编写文档，具有文件操作但没有系统命令

示例

这里有一些你可能会觉得有用的示例智能体。

文档智能体

~/.config/opencode/agent/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---


你是一名技术作家。请编写清晰、全面的文档。


侧重于：


- 清晰的解释
- 适当的结构
- 代码示例
- 用户友好的语言

安全审计员

~/.config/opencode/agent/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---


你是一名安全专家。侧重于识别潜在的安全问题。


寻找：


- 输入验证漏洞
- 身份验证和授权缺陷
- 数据泄露风险
- 依赖项漏洞
- 配置安全问题