Agent 与权限系统

OpenCode 的 Agent 不仅是「不同提示词」，而是带 mode、model、permission 的完整执行配置。

内置 Agent 详解

Build（Primary）

默认主 Agent，全工具可用
适合：实现功能、跑测试、改多文件

Plan（Primary）

受限 Agent：默认对 edit、bash 等敏感操作 ask 或禁止
适合：方案设计、代码审查建议、重构计划
不会产生意外 diff，是 OpenCode 的「安全设计模式」

Explore（Subagent）

只读，快速 glob/grep/读文件
适合：「这个模块在哪？」「有哪些 API 路由？」

Scout（Subagent）

只读，偏外部依赖与上游源码
适合：查第三方库实现、clone 依赖到缓存对照

General（Subagent）

全工具（除 todo 相关限制），可改文件
适合：可并行的独立子任务

切换与调用

方式	示例
Tab 切换 Primary	Build ↔ Plan
@ 提及 Subagent	`@explore 找出所有 REST 路由`
task 工具	Primary 自动委派

隐藏 Agent：配置 hidden: true 的 Subagent 不出现在 @ 菜单，但仍可被 task 调用。

JSON 配置 Agent

opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-6"
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-5",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "code-reviewer": {
      "description": "审查代码质量与安全",
      "mode": "subagent",
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "deny",
          "git diff*": "allow",
          "git log*": "allow"
        }
      }
    }
  }
}

Markdown 配置 Agent

路径：

全局：~/.config/opencode/agents/review.md
项目：.opencode/agents/review.md

---
description: 安全审计，只读
mode: subagent
model: anthropic/claude-sonnet-4-6
temperature: 0.1
permission:
  edit: deny
  bash:
    "*": "ask"
    "grep *": allow
---

你是安全审计员，关注注入、鉴权、依赖漏洞。只输出报告，不改文件。

文件名 review.md → Agent 名 review。

交互式创建

opencode agent create

向导会询问：保存位置、描述、权限勾选，并生成 Markdown Agent 文件。

opencode agent list

Permission 进阶

全局默认 + Agent 覆盖

{
  "permission": {
    "edit": "ask"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "allow"
      }
    }
  }
}

task 权限（谁能调哪个 Subagent）

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

deny 时该 Subagent 从 task 工具描述中移除，模型不会自动委派；用户仍可用 @ 手动调用。

steps 限制（控制成本）

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

达到步数上限后，Agent 被强制输出总结而非继续调工具。

典型 Agent 组合

场景	Primary	Subagent
新功能	Plan → Build	Explore 查现有模式
Code Review	Plan	code-reviewer
修 bug	Build	Explore 定位调用链
依赖升级	Plan	Scout 查 upstream breaking changes

#Agent 与权限系统

#内置 Agent 详解

#Build（Primary）

#Plan（Primary）

#Explore（Subagent）

#Scout（Subagent）

#General（Subagent）

#切换与调用

#JSON 配置 Agent

#Markdown 配置 Agent

#交互式创建

#Permission 进阶

#全局默认 + Agent 覆盖

#task 权限（谁能调哪个 Subagent）

#steps 限制（控制成本）

#典型 Agent 组合

#下一步