Skip to content
OpenCode
首页文档

智能体

配置和使用专用智能体。

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

您可以在会话期间切换代理，或使用 @ 提及来调用它们。

类型

OpenCode 中有两种类型的代理：主代理和子代理。

主代理

主代理是您直接交互的主要助手。您可以使用 Tab 键或您配置的 switch_agent 快捷键在它们之间循环切换。这些代理处理您的主要对话，并且可以访问所有已配置的工具。

OpenCode 附带两个内置的主代理：Build 和 Plan。我们将在下面介绍它们。

子代理

子代理是专门的助手，主代理可以调用它们来执行特定任务。您也可以通过**@提及**它们来手动调用。

OpenCode 附带两个内置的子代理：General 和 Explore。我们将在下面介绍它们。

内置代理

OpenCode 附带两个内置的主代理和两个内置的子代理。

Build

模式: primary

Build 是默认的主代理，启用了所有工具。这是用于开发工作的标准代理，您需要完全访问文件操作和系统命令。

Plan

模式: primary

一个为规划和分析设计的受限代理。我们使用权限系统为您提供更多控制权，并防止意外更改。 默认情况下，以下所有权限都设置为 ask：

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

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

通用型

模式: subagent

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

探索型

模式: 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 配置文件中配置 agent：

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 文件来定义 agent。将它们放置在：

  • 全局：~/.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
---


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 文件的名称将成为 agent 的名称。例如，review.md 会创建一个名为 review 的 agent。

选项

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

描述

使用 description 选项来简要描述代理的功能以及何时使用它。

opencode.json
{
  "agent": {
    "review": {
      "description": "审查代码以检查最佳实践和潜在问题"
    }
  }
}

这是一个必需的配置选项。

温度

使用 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": "有限迭代的快速推理",
      "prompt": "你是一个快速思考者。用最少的步骤解决问题。",
      "maxSteps": 5
    }
  }
}

当达到限制时，代理会收到一个特殊的系统提示，指示其用工作摘要和推荐的剩余任务来响应。

禁用

设置为 true 以禁用该代理。

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

提示词

使用 prompt 配置为此代理指定自定义系统提示词文件。提示词文件应包含针对代理用途的特定指令。

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

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

模型

使用 model 配置来覆盖此 agent 的模型。这对于使用针对不同任务优化的不同模型非常有用。例如，使用更快的模型进行规划，使用能力更强的模型进行实现。

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 配置来控制此 agent 可用的工具。您可以通过将特定工具设置为 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: 仅代码审查，不进行编辑
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": "使用高推理力度处理复杂问题的代理",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

这些附加选项是特定于模型和提供者的。请查阅您的提供者文档以了解可用参数。

创建代理

您可以使用以下命令创建新的代理：

Terminal window
opencode agent create

这个交互式命令将：

  1. 询问将代理保存在何处；全局保存或项目特定保存。
  2. 询问代理应执行任务的描述。
  3. 生成适当的系统提示和标识符。
  4. 让您选择代理可以访问哪些工具。
  5. 最后，创建一个包含代理配置的 markdown 文件。

使用场景

以下是不同代理的一些常见使用场景。

  • 构建代理：启用所有工具进行完整的开发工作
  • 规划代理：进行分析和规划，但不进行更改
  • 评审代理：进行代码评审，具有只读访问权限以及文档工具
  • 调试代理：专注于调查，启用 bash 和读取工具
  • 文档代理：文档编写，具有文件操作功能但无系统命令

示例

以下是一些您可能会觉得有用的智能体示例。

文档编写智能体

~/.config/opencode/agent/docs-writer.md
---
description: 编写和维护项目文档
mode: subagent
tools:
  bash: false
---


你是一名技术文档工程师。请创建清晰、全面的文档。


重点关注：


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

安全审计智能体

~/.config/opencode/agent/security-auditor.md
---
description: 执行安全审计并识别漏洞
mode: subagent
tools:
  write: false
  edit: false
---


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


寻找：


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