跳至内容
OpenCode
app.header.homeapp.header.docs

代理

配置和使用专用代理。

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

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

类型

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

主代理

主代理是您直接交互的主要助手。您可以使用 Tab 键或您配置的 switch_agent 快捷键来切换它们。这些代理处理您的主要对话。工具访问通过权限配置——例如，Build 启用了所有工具，而 Plan 则受限。

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

子代理

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

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

内置

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

使用 Build

模式：primary

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

使用 Plan

模式：primary

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

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

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

使用 General

模式：subagent

一个通用的代理，用于研究复杂问题和执行多步任务。拥有完整的工具访问权限（除了 todo），因此在需要时可以进行文件更改。使用此代理可以并行运行多个工作单元。

使用 Explore

模式：subagent

一个快速、只读的代理，用于探索代码库。无法修改文件。当您需要通过模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时，请使用此代理。

使用 Compaction

模式：primary

隐藏的系统代理，将长上下文压缩成更小的摘要。它在需要时自动运行，且在 UI 中不可选。

使用 Title

模式：primary

隐藏的系统代理，生成简短的会话标题。它自动运行，且在 UI 中不可选。

使用 Summary

模式：primary

隐藏的系统代理，创建会话摘要。它自动运行，且在 UI 中不可选。

用法

  1. 对于主代理，在会话期间使用 Tab 键循环切换。您也可以使用您配置的 switch_agent 快捷键。

  2. 子代理可以通过以下方式调用

    • 主代理根据其描述自动调用以执行专门任务。

    • 通过在消息中 @ 提及子代理来手动调用。例如。

      @general help me search for this function

  3. 会话间导航：当子代理创建子会话时，使用 session_child_first（默认：<Leader>+Down）从父会话进入第一个子会话。

  4. 进入子会话后，使用

    • session_child_cycle（默认：Right）切换到下一个子会话
    • session_child_cycle_reverse（默认：Left）切换到上一个子会话
    • session_parent（默认：Up）返回到父会话

    这允许您在主对话和专用子代理工作之间切换。

配置

您可以通过配置自定义内置代理或创建自己的代理。代理可以通过两种方式进行配置

JSON

在您的 opencode.json 配置文件中配置代理

opencode.json
{
  "$schema": "https://opencode.ac.cn/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/
~/.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 选项提供代理的功能和使用时机的简要描述。

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.",
      "steps": 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 已弃用。对于新配置、更新和更精细的控制，请优先使用代理的 permission 字段。

允许您控制此代理中可用的工具。您可以通过将特定工具设置为 true 或 false 来启用或禁用它们。在代理的 tools 配置中，true 等同于 {"*": "allow"} 权限，而 false 等同于 {"*": "deny"} 权限。

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

您还可以在传统 tools 条目中使用通配符来一次控制多个工具。例如，要禁用 MCP 服务器的所有工具

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

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

权限

您可以配置权限来管理代理可以执行的操作。目前，edit、bash 和 webfetch 工具的权限可以配置为

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

您可以按代理覆盖这些权限。

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

您也可以在 Markdown 代理中设置权限。

~/.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 命令设置权限。

opencode.json
{
  "$schema": "https://opencode.ac.cn/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

这可以接受 glob 模式。

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

您还可以使用 * 通配符来管理所有命令的权限。由于最后匹配的规则优先，请将 * 通配符放在前面，然后放置特定规则。

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

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

模式

使用 mode 配置控制代理的模式。mode 选项用于确定代理如何使用。

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

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

隐藏

使用 hidden: true 将子代理从 @ 自动完成菜单中隐藏。这对于只应由其他代理通过任务工具以编程方式调用的内部子代理很有用。

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

这仅影响用户在自动完成菜单中的可见性。如果权限允许，隐藏代理仍可由模型通过任务工具调用。

任务权限

使用 permission.task 控制代理可以通过任务工具调用哪些子代理。使用 glob 模式进行灵活匹配。

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

当设置为 deny 时，子代理会从任务工具描述中完全移除，因此模型不会尝试调用它。

颜色

使用 color 选项自定义代理在 UI 中的视觉外观。这会影响代理在界面中的显示方式。

使用有效的十六进制颜色（例如，#FF5733）或主题颜色：primary、secondary、accent、success、warning、error、info。

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

Top P

使用 top_p 选项控制响应多样性。它是控制随机性的温度选项的替代方案。

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

值范围从 0.0 到 1.0。值越低越集中，值越高越多样。

附加选项

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

例如，对于 OpenAI 的推理模型，您可以控制推理工作量

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

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

创建代理

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

终端窗口
opencode agent create

这个交互式命令将

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

用例

以下是一些不同代理的常见用例。

  • Build 代理：启用所有工具的完整开发工作
  • Plan 代理：进行分析和规划，不进行更改
  • Review 代理：具有只读访问权限和文档工具的代码审查
  • Debug 代理：专注于调查，启用 bash 和读取工具
  • Docs 代理：进行文档编写，具有文件操作权限，但没有系统命令权限

示例

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

文档代理

~/.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

安全审计员

~/.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