OpenCode Agents 文档（简体中文）

概述

Agents 是可配置用于特定任务和工作流程的专用 AI 助手，支持通过自定义提示词、模型和工具访问权限，创建针对性工具。

提示：使用 Plan 代理可分析代码并查看建议，且不会对代码做出任何修改。会话期间可切换代理，或通过 @ 提及方式调用代理。

代理类型

OpenCode 中的代理分为两类：主代理（Primary agents）和子代理（Subagents）。

主代理（Primary agents）

可直接交互的主要助手，支持通过 Tab 键或配置的 switch_agent 快捷键切换。
负责处理主要对话，可访问所有已配置工具。
内置主代理：
- Build：默认主代理，所有工具均启用，适用于需要完整文件操作和系统命令访问权限的标准开发工作。
- Plan：受限代理，专为规划和分析设计，通过权限系统避免意外修改。默认情况下，文件编辑（所有写入、补丁和编辑操作）和 bash（所有 bash 命令）的权限均设为 ask（需用户确认）。

子代理（Subagents）

主代理可调用的专用助手，也可通过在消息中 @ 提及手动调用。
内置子代理：
- General：通用代理，适用于研究复杂问题、搜索代码和执行多步骤任务，适合不确定能否快速找到匹配结果的关键词或文件搜索场景。
- Explore：快速代理，专注于代码库探索，适用于通过模式快速查找文件、搜索代码中的关键词或解答代码库相关问题。

使用方法

主代理

会话期间通过 Tab 键循环切换，或使用配置的 switch_agent 快捷键。

子代理

自动调用：主代理根据子代理描述，针对特定任务自动调用。
手动调用：在消息中 @ 提及子代理名称，示例：@general help me search for this function（@general 帮我搜索这个函数）。

会话导航（子代理子会话）

当子代理创建独立子会话时，可通过以下方式在父会话与所有子会话间导航：

Leader+Right（或配置的 session_child_cycle 快捷键）：正向循环切换（父会话 → 子会话1 → 子会话2 → … → 父会话）。
Leader+Left（或配置的 session_child_cycle_reverse 快捷键）：反向循环切换（父会话 ← 子会话1 ← 子会话2 ← … → 父会话）。

支持在主对话与专用子代理工作流间无缝切换。

配置方式

可通过两种方式自定义内置代理或创建新代理：JSON 配置文件、Markdown 文件。

1. 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
      }
    }
  }
}

2. Markdown 配置文件

将 Markdown 配置文件放置在指定目录，文件名即为代理名称：

全局配置：~/.config/opencode/agent/
项目级配置：.opencode/agent/

示例（review.md）：

---
description: 审查代码质量和最佳实践
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
你处于代码审查模式，重点关注：
- 代码质量和最佳实践
- 潜在漏洞和边界情况
- 性能影响
- 安全考量

提供建设性反馈，不直接修改代码。

配置选项详情

1. 描述 (Description)

必填项，简要说明代理功能及适用场景，示例：

{
  "agent": {
    "review": {
      "description": "审查代码的最佳实践和潜在问题"
    }
  }
}

2. 温度 (Temperature)

控制 LLM 响应的随机性和创造性，取值范围 0.0-1.0：

0.0-0.2：高度聚焦、确定性强，适用于代码分析和规划。
0.3-0.5：平衡型，兼具一定创造性，适用于通用开发任务。
0.6-1.0：高创造性、多样性强，适用于头脑风暴和探索。

说明：未指定时使用模型默认值（多数模型为 0，Qwen 模型为 0.55）。

示例：

{
  "agent": {
    "plan": { "temperature": 0.1 },
    "creative": { "temperature": 0.8 }
  }
}

3. 最大步骤 (Max steps)

限制代理迭代次数，超出后仅返回文本总结及剩余任务建议，适用于成本控制，示例：

{
  "agent": {
    "quick-thinker": {
      "description": "有限迭代次数的快速推理",
      "prompt": "你是快速思考者，用最少步骤解决问题。",
      "maxSteps": 5
    }
  }
}

4. 禁用 (Disable)

设置为 true 可禁用代理，示例：

{
  "agent": {
    "review": { "disable": true }
  }
}

5. 提示词 (Prompt)

指定自定义系统提示词文件，路径相对于配置文件所在目录，示例：

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

6. 模型 (Model)

指定代理使用的模型，格式为 提供商/模型ID，示例：

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

说明：未指定时，主代理使用全局配置模型，子代理使用调用它的主代理模型。

7. 工具 (Tools)

控制代理可访问的工具，支持 true（启用）/false（禁用），或通配符批量控制，示例：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false, // 禁用所有 mymcp 相关工具
        "write": false,
        "edit": false
      }
    }
  }
}

说明：代理级配置会覆盖全局工具配置。

8. 权限 (Permissions)

配置工具操作权限，支持 ask（需批准）、allow（直接允许）、deny（禁用），可针对特定命令（如 bash）细化配置，示例：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask", // 所有 bash 命令需批准
          "git status": "allow" // 单独允许 git status 命令
        }
      }
    }
  }
}

Markdown 配置示例：

---
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
---

9. 模式 (Mode)

指定代理类型，可选值：

primary：主代理
subagent：子代理
all：默认值（支持两种模式）

示例：

{
  "agent": {
    "review": { "mode": "subagent" }
  }
}

10. 隐藏 (Hidden)

仅适用于子代理，设置为 true 可隐藏其在 @ 自动补全菜单中，仅允许通过 Task 工具编程调用，示例：

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

11. 任务权限 (Task permissions)

控制代理可通过 Task 工具调用的子代理，支持通配符，示例：

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny", // 默认拒绝所有
          "orchestrator-*": "allow", // 允许 orchestrator- 前缀子代理
          "code-reviewer": "ask" // 调用 code-reviewer 需批准
        }
      }
    }
  }
}

说明：用户仍可通过 @ 手动调用被拒绝的子代理。

12. 额外参数 (Additional)

支持传递模型/提供商特定的参数，示例：

{
  "agent": {
    "deep-thinker": {
      "model": "openai/gpt-5",
      "reasoningEffort": "high", // OpenAI 模型特定参数
      "textVerbosity": "low"
    }
  }
}

提示：运行 opencode models 可查看可用模型列表。

创建代理

通过以下命令交互式创建新代理：

opencode agent create

命令流程：

选择保存位置（全局/项目级）
输入代理功能描述
生成系统提示词和标识符
选择工具访问权限
创建 Markdown 配置文件

常见用例

| 代理类型 | 用途 | |----------|------| | Build 代理 | 启用所有工具的完整开发工作 | | Plan 代理 | 不修改代码的分析和规划 | | Review 代理 | 只读权限的代码审查（含文档工具） | | Debug 代理 | 启用 bash 和只读工具的问题排查 | | Docs 代理 | 文档编写（支持文件操作，禁用系统命令） |

示例代理

1. 文档编写代理

---
description: 编写和维护项目文档
mode: subagent
tools:
  bash: false
---
你是技术文档撰写者，创建清晰、全面的文档，重点关注：
- 解释清晰
- 结构合理
- 代码示例
- 用户友好的语言

2. 安全审计代理

---
description: 执行安全审计并识别漏洞
mode: subagent
tools:
  write: false
  edit: false
---
你是安全专家，重点识别潜在安全问题，包括：
- 输入验证漏洞
- 认证和授权缺陷
- 数据泄露风险
- 依赖项漏洞
- 配置安全问题

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)