OpenCode 代理（Agent）

在 OpenCode 中，代理（Agent）是核心能力之一。

< strong>代理（Agent）允许你把 AI 拆分成多个有分工的助手，从而更高效地完成开发任务。

OpenCode 的核心不是一个 AI，而是一组可以协作的 AI 代理。

掌握 Agent，相当于解锁 OpenCode 的核心能力。

代理 = 模型 + 提示词 + 工具 + 权限

什么是代理？

代理可以理解为一个带能力的 AI 角色，包含：

  • 模型：使用哪个 LLM
  • 提示词：行为规则
  • 工具：能做什么（读写文件 / 执行命令）
  • 权限：是否允许执行

通过组合这些能力，你可以创建不同角色：

  • 代码生成代理
  • 代码审查代理
  • 安全分析代理
  • 只读分析代理

代理类型

主代理（Primary）

你直接交互的 AI，负责主要对话。

<TAB>  // 切换主代理
  • Build：写代码
  • Plan：做规划

子代理（Sub Agent）

由主代理调用的专业助手。

@general 帮我分析这个函数

适用于：

  • 复杂任务拆分
  • 并行执行
  • 不同能力分工

内置代理

Build（默认）

  • 拥有全部权限
  • 可读写文件
  • 可执行命令
Build = 真正干活的工程师

Plan

  • 默认只读
  • 不能修改代码
  • 用于规划
Plan = 只出方案，不动代码

General

  • 通用子代理
  • 支持复杂任务

Explore

  • 只读
  • 专注搜索和分析

使用方式

1、切换代理

<TAB>

推荐流程：

  • 先 Plan（设计）
  • 再 Build（执行）

2、调用子代理

@explore 查找 auth 相关代码

代理配置

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4",
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

核心配置项

model（模型）

"model": "openai/gpt-5"

prompt（行为）

"prompt": "{file:./prompts/review.txt}"

tools（工具）

"tools": {
  "write": false,
  "bash": false
}

permission（权限）

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

temperature（创造力）

"temperature": 0.2

Markdown 定义代理（推荐）

~/.config/opencode/agents/review.md

---
description: Code review agent
mode: subagent
tools:
  write: false
---

You are a code reviewer.

高级能力

任务权限

"permission": {
  "task": {
    "*": "deny",
    "review-*": "allow"
  }
}

隐藏代理

"hidden": true

UI 颜色

"color": "#ff6b6b"

常见使用场景

  • Build：开发代码
  • Plan：设计方案
  • Review：代码审查
  • Debug：排查问题
  • Docs：写文档