Open Agent 使用教程

OpenCode 代理（Agent）是一套可定制化专用 AI 助手体系，支持独立配置系统提示词、大语言模型、工具权限与运行规则。开发者可根据代码编写、代码审查、依赖调研、文档编写等不同任务，创建专属代理，实现任务分工、权限隔离与流程标准化。OpenCode 内置多款开箱即用的代理，同时支持自定义代理，兼顾通用开发场景与个性化业务需求。本文将系统讲解代理分类、内置代理功能、调用方式、全量配置语法、交互式创建流程以及实战案例与最佳实践，帮助开发者全面掌握 OpenCode 代理的使用与定制。

一、代理基础分类

OpenCode 将代理划分为主代理、子代理和隐藏系统代理三大类型，不同类型的调用方式、权限范围和使用场景存在明确区分，也是后续配置与使用的基础。

1.1 主代理（primary）

主代理是用户直接交互的核心助手，也是会话的默认运行载体。在 TUI 界面中可通过快捷键快速切换，拥有完整的会话上下文，主要承接用户直接发起的各类开发任务。主代理支持全量工具配置，可自由开启或限制文件编辑、终端命令、网络访问等能力。

1.2 子代理（subagent）

子代理是主代理调用的专项辅助助手，聚焦单一细分任务。用户可手动调用，也可由主代理根据任务需求自动触发。子代理通常会被限制部分高危权限，多用于代码检索、外部依赖调研、专项分析等场景，不会直接作为主会话载体。

1.3 隐藏系统代理

此类代理无手动调用入口，由 OpenCode 后台自动触发运行，用于完成上下文压缩、会话标题生成、会话摘要等系统级任务，用户无法在 UI 中选择或配置。

二、内置代理全解

OpenCode 预置 7 款代理，包含 2 个主代理、3 个子代理以及 3 个隐藏系统代理，覆盖绝大多数常规开发场景，开箱即可使用。

2.1 内置主代理

2.1.1 Build 代理

• 运行模式：primary

• 核心特性：OpenCode 默认主代理，默认启用全部工具权限，拥有文件读写、补丁应用、终端命令执行、网络访问等完整能力。

• 适用场景：日常代码开发、功能迭代、项目构建、依赖安装等需要修改代码库、执行系统命令的全流程开发工作。

2.1.2 Plan 代理

• 运行模式：primary

• 核心特性：受限型分析代理，默认将文件编辑、补丁、写入、Bash 命令等高危操作的权限设置为 ask（执行前需人工审批），可有效避免代码被意外修改。

• 适用场景：代码分析、方案规划、需求梳理、代码评审、问题诊断等只查看不改动的场景。官方推荐优先使用该代理分析代码，再切换至 Build 代理执行修改。

2.2 内置子代理

2.2.1 General 代理

• 运行模式：subagent

• 核心特性：通用型子代理，拥有完整工具权限（todo 工具除外），支持多步骤复杂任务，可并行处理多个工作单元，允许修改文件。

• 适用场景：拆解复杂开发任务、多模块协同处理、综合性问题研究。

2.2.2 Explore 代理

• 运行模式：subagent

• 核心特性：纯只读代理，无任何文件修改权限，擅长基于匹配规则检索文件、关键字全局搜索。

• 适用场景：快速梳理代码结构、查找指定函数 / 接口、批量检索项目关键字、解答代码库相关问题。

2.2.3 Scout 代理

• 运行模式：subagent

• 核心特性：只读外部调研代理，专注于第三方依赖、外部仓库研究，可将外部仓库克隆至托管缓存进行分析，不会修改本地工作区。

• 适用场景：查阅第三方库源码、对比上游框架实现、调研外部依赖功能与兼容性。

2.3 隐藏系统代理

1. Compaction：自动压缩超长会话上下文，减少 Token 消耗，后台静默运行。

2. Title：自动为会话生成简短标题，用于会话列表展示。

3. Summary：自动创建会话摘要，用于历史会话回溯。

以上三款代理均无法手动选择、调用或配置，全部由系统按需触发。

三、代理调用与会话导航

不同类型代理的调用方式存在差异，同时 OpenCode 提供专属快捷键实现父子会话快速切换，提升多代理协同效率。

3.1 主代理切换

在 TUI 会话中，可通过两种方式循环切换已配置的主代理：

1. 快捷键（推荐）：按下 Tab 键快速切换；

2. 自定义快捷键：使用提前配置的 switch_agent 快捷键切换。

切换后会话上下文会同步保留，可无缝衔接分析、规划、开发等连续操作。

3.2 子代理调用

子代理支持自动调用和手动调用两种方式：

1. 自动调用：主代理根据任务描述，自主判断并调用匹配的子代理完成专项任务，全程无需用户干预。

2. 手动调用：在对话消息中使用 @代理名 的格式直接唤起子代理，语法示例：

@general 帮我梳理项目中所有 Redis 相关的业务代码
@explore 查找项目中所有接口路由文件

3.3 父子会话导航

当子代理创建独立子会话后，可通过快捷键在父会话与多个子会话之间循环切换，快捷键基于默认前导键 <Leader>（默认 ctrl+x）：

1. 向前循环（父会话 → 子会话 1 → 子会话 2 → 父会话）：<Leader>+Right（对应配置项 session_child_cycle）；

2. 向后循环（父会话 ← 子会话 1 ← 子会话 2）：<Leader>+Left（对应配置项 session_child_cycle_reverse）。

四、代理配置方式

OpenCode 支持 JSON 配置 和 Markdown 文件配置 两种方式自定义代理，同时区分全局代理和项目级代理，前者对本机所有会话生效，后者仅作用于当前项目。

4.1 配置文件存放路径

1. 全局代理（本机所有项目生效）：~/.config/opencode/agents/

2. 项目级代理（仅当前项目生效）：.opencode/agents/

补充规则：使用 Markdown 定义代理时，文件名即为代理名称，配置会自动加载生效。

4.2 方式一：JSON 配置（opencode.json）

在项目根目录或全局配置目录的 opencode.json 文件中，通过 agent 节点统一管理多个代理，适合批量配置、集中维护。

完整示例

{
  "$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
      }
    }
  }
}

4.3 方式二：Markdown 配置（推荐）

单个代理独立使用 Markdown 文件配置，结构清晰、可读性强，是官方推荐的单代理配置方案。文件分为头部配置区（Frontmatter）和正文提示词区。

完整示例（全局代码审查代理）

文件路径：~/.config/opencode/agents/review.md

---
description: 代码审查，检查编码规范、漏洞与性能问题
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
你是专业代码审查工程师，工作要求如下：
1. 检查代码是否符合项目编码规范；
2. 识别潜在 Bug、安全漏洞与性能隐患；
3. 给出可落地的优化建议，禁止直接修改代码。

五、全配置参数详解

本节详解代理支持的所有配置参数，包含基础属性、模型参数、工具权限、会话控制、样式配置等，所有参数同时兼容 JSON 与 Markdown 两种配置方式。

5.1 基础通用参数

1. description（必填）
   代理功能描述，会在命令面板、代理列表中展示，用于标识代理用途。
   示例：description: 项目文档编写代理

2. mode
   定义代理运行模式，取值包含 primary / subagent / all，默认值为 all。

   • primary：仅作为主代理，支持 Tab 切换；

   • subagent：仅作为子代理，只能被调用；

   • all：同时支持主、子代理两种模式。

3. disable
   布尔值，设为 true 可临时禁用该代理，禁用后代理不再加载。
   示例：disable: true

4. hidden
   仅适用于子代理，设为 true 可将代理从 @ 自动补全菜单中隐藏，仅允许其他代理通过 Task 工具调用，适合内部专用代理。

5.2 模型与生成参数

1. model
   指定代理使用的大模型，格式统一为 提供商/模型名。若不配置，主代理继承全局模型，子代理继承调用它的主代理模型。
   示例：model: opencode/gpt-5.1-codex

2. temperature
   控制 LLM 响应的随机性与创造力，取值范围 0.0 ~ 1.0：

   • 0.0 - 0.2：输出严谨、确定性强，适合代码分析、规划；

   • 0.3 - 0.5：平衡模式，适用于常规开发；

   • 0.6 - 1.0：创造力强，适用于头脑风暴、方案构思。
     未配置时使用模型默认参数。

3. top_p
   temperature 的替代参数，同样用于控制响应多样性，取值 0.0 ~ 1.0，值越高多样性越强。

4. steps
   限制代理最大迭代步数，达到上限后会输出工作摘要与剩余任务。旧字段 maxSteps 已弃用，统一使用 steps。
   示例：steps: 5

5. prompt
   配置代理的系统提示词，支持直接填写文本，或通过 {file:文件路径} 引用外部提示词文件（路径相对配置文件）。
   示例：prompt: "{file:./prompts/audit.txt}"

5.3 工具与权限配置（核心）

代理的工具权限优先级高于全局配置，可精细化管控每一个工具、每一条终端命令。

5.3.1 tools 基础开关

通过布尔值 true/false 全局启用 / 禁用指定工具，支持 * 通配符批量管理工具组。

"tools": {
  "write": false,
  "edit": false,
  "mymcp_*": false
}

5.3.2 permission 细粒度权限

支持 allow（允许）、ask（审批后执行）、deny（禁止）三种权限，可作用于全局工具、单一命令，支持 Glob 通配符。匹配规则：后配置的规则优先级高于先配置的规则。

1. 全局工具权限：

"permission": {
  "edit": "deny",
  "bash": "ask"
}

1. Bash 命令精细化权限（区分不同命令）：

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

5.3.3 permission.task 子代理调用权限

控制当前代理可通过 Task 工具调用哪些子代理，支持通配符，deny 状态下子代理会从工具列表中隐藏。

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

5.4 样式与扩展参数

1. color
   自定义代理在 UI 中的显示颜色，支持十六进制色值或内置主题色（primary、success、error 等）。
   示例：color: #FF5733

2. 模型专属参数
   配置的额外字段会直接透传给模型提供商，可使用模型独有能力，例如 OpenAI 模型的推理力度：

"reasoningEffort": "high",
"textVerbosity": "low"

六、交互式命令创建代理

除手动编写配置文件外，OpenCode 提供交互式命令，引导用户一键生成代理配置文件，降低上手门槛。

6.1 执行命令

opencode agent create

6.2 分步创建流程

1. 选择代理保存位置：全局（本机所有项目）或项目级（仅当前项目）；

2. 填写代理功能描述，程序自动生成基础系统提示词；

3. 勾选代理可使用的工具，配置工具开关；

4. 确认配置后，程序自动在对应目录生成 Markdown 格式的代理文件。

创建完成后，代理立即生效，可直接在 TUI 中调用。

七、实战自定义代理案例

本节提供多个可直接复用的代理配置案例，覆盖文档编写、安全审计、代码调试等高频场景，均采用 Markdown 格式。

7.1 文档编写代理（子代理）

文件路径：~/.config/opencode/agents/docs-writer.md

---
description: 编写与维护项目技术文档
mode: subagent
tools:
  bash: false
---
你是专业技术文档工程师，编写文档需结构清晰、示例完整、语言通俗易懂。
专注于接口文档、使用手册、开发指南的撰写与优化，不执行系统命令。

7.2 安全审计代理（子代理）

文件路径：.opencode/agents/security-auditor.md

---
description: 代码安全审计，排查漏洞与风险
mode: subagent
tools:
  write: false
  edit: false
---
你是安全审计专家，重点排查以下风险：
1. 输入验证漏洞、身份认证缺陷；
2. 数据泄露、权限越权问题；
3. 第三方依赖安全漏洞。
仅输出审计报告与修复建议，禁止修改代码。

7.3 代码调试代理（主代理）

文件路径：.opencode/agents/debug.md

---
description: 代码问题排查与调试
mode: primary
temperature: 0.2
permission:
  bash: allow
  edit: ask
---
专注代码 Bug 排查、异常分析、日志解读，可执行调试命令。
修改代码前必须给出问题原因与修复思路，确认后再执行修改。

八、使用场景与最佳实践

8.1 场景化代理选型

1. 日常功能开发：使用默认 Build 代理，完整工具权限满足编码、构建、依赖安装需求；

2. 代码评审 / 陌生代码研读：优先切换至 Plan 代理，利用审批权限防止误改代码；

3. 代码全局检索：调用 @explore 子代理，只读模式快速定位文件与关键字；

4. 第三方依赖调研：调用 @scout 子代理，分析外部库源码与实现；

5. 复杂多步骤任务：调用 @general 子代理，拆分任务并行处理。

8.2 权限管控最佳实践

1. 生产环境项目：将 bash、edit 等高危工具统一设为 ask，避免误执行高危命令、篡改线上代码；

2. 只读类代理：彻底禁用 write、edit 工具，从根源杜绝代码修改；

3. Bash 命令细分：允许 git status、ls 等查询命令，禁止 rm、git push 等高风险命令。

8.3 代理配置规范

1. 通用代理（文档、安全审计）放置在全局目录，所有项目共享；

2. 项目专属代理（业务调试、专项审查）放置在项目级目录，随项目纳入 Git 管理；

3. 多代理项目优先使用 Markdown 单文件配置，便于团队成员单独维护。

8.4 参数调优建议

1. 代码分析、审计类代理：temperature 设置为 0.1 - 0.2，保证输出严谨；

2. 方案设计、头脑风暴类代理：temperature 设置为 0.6+，激发创意；

3. 长会话任务：合理配置 steps 参数，限制迭代步数，控制 Token 消耗与使用成本。

九、总结

OpenCode 代理体系通过分类设计、精细化权限、灵活配置，实现了 AI 助手的专业化分工，是提升开发效率、保障项目安全的核心功能。核心要点总结如下：

1. 代理分为主代理、子代理、隐藏系统代理三大类，内置 7 款代理可覆盖绝大多数常规场景；

2. 主代理使用 Tab 键切换，子代理通过 @代理名 手动调用，父子会话依靠专属快捷键导航；

3. 支持 JSON、Markdown 两种配置方式，区分全局与项目级代理，Markdown 更适合单代理独立维护；

4. 权限系统支持全局工具、单条 Bash 命令、子代理调用多层管控，搭配通配符可实现批量规则配置；

5. 交互式命令 opencode agent create 可快速生成代理，降低自定义门槛。

在实际开发中，结合业务场景搭配不同代理，并合理管控工具权限，既能发挥 AI 辅助编码的效率优势，又能规避误操作风险。团队可根据技术栈与工作流程，沉淀专属代理模板，统一团队 AI 使用规范。