OpenCode 操作指导书（五）：进阶使用
适用版本：OpenCode v1.18.3
本篇目标：掌握内置 Agent、自定义 Agent、MCP 接入、多会话与子 Agent 并行、会话分享等进阶能力。
1. 内置 Agent 体系
OpenCode 的 Agent 分三类：
1.1 Primary Agents（主要 Agent）
| Agent | 模式 | 说明 |
|---|---|---|
| build | primary | 默认，所有工具可用，标准开发 |
| plan | primary | 受限 Agent，file edits/bash默认ask，只规划不改动 |
切换：Tab循环 /Shift+Tab反向 /Leader → a打开 Agent 列表。
1.2 Subagents（子 Agent）
由主 Agent 自动调用，或你在消息中@提及手动调用：
- general：通用，有完整工具权限（除 todo），可并行多任务。
- explore：快速只读，探索代码库，不修改文件。
- scout：只读，用于外部文档与依赖研究（可克隆依赖库到缓存）。
示例：
@general help me search for this function across the repo2. 自定义 Agent
2.1 交互式创建
opencode agent create向导会：询问保存位置（全局/项目级）→ 描述功能 → 生成系统提示与标识符 → 选择权限 → 创建配置文件。
2.2 配置文件方式
- JSON：写入
opencode.json的agent字段。 - Markdown：放在
~/.config/opencode/agents/（全局）或.opencode/agents/（项目），文件名即 Agent 名（如review.md→review）。
2.3 Agent 配置字段
| 字段 | 说明 |
|---|---|
description | 必填，用途简述 |
model | 覆盖模型，provider/model-id |
mode | primary/subagent/all |
permission | 细粒度权限：ask/allow/deny，支持通配符 |
prompt | 系统提示，支持{file:./path} |
temperature/top_p | 随机性控制 |
steps | 最大迭代次数（达限后仅文本总结） |
hidden | 仅 subagent 有效，隐藏@菜单 |
color | UI 颜色 |
常用权限键：readeditglobgreplistbashtaskexternal_directorytodowritewebfetchwebsearchlspskillquestion。
2.4 示例：JSON 配置
{"$schema":"https://opencode.ai/config.json","agent":{"build":{"mode":"primary","model":"anthropic/claude-sonnet-4-5","prompt":"{file:./prompts/build.txt}","permission":{"edit":"allow","bash":"allow"}},"plan":{"mode":"primary","model":"anthropic/claude-haiku-4-5","permission":{"edit":"deny","bash":"deny"}},"code-reviewer":{"description":"Reviews code for best practices and potential issues","mode":"subagent","model":"anthropic/claude-sonnet-4-5","prompt":"You are a code reviewer. Focus on security, performance, and maintainability.","permission":{"edit":"deny"}}}}2.5 示例：Markdown 配置（~/.config/opencode/agents/review.md）
--- description: Reviews code for quality and best practices mode: subagent model: anthropic/claude-sonnet-4-5 temperature: 0.1 permission: edit: deny bash: deny --- 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.2.6 权限通配符示例
{"agent":{"build":{"permission":{"bash":{"*":"ask","git status *":"allow"}}}}}3. MCP（Model Context Protocol）
MCP 让 OpenCode 接入外部工具/数据源（数据库、API、文件系统等）。
opencode mcpadd# 引导添加本地或远程 MCP 服务opencode mcp list# 或 mcp ls，列出已配置及连接状态opencode mcp auth<name># 对支持 OAuth 的服务器认证opencode mcplogout<name>opencode mcp debug<name># 调试 OAuth 连接4. 多会话与子 Agent 会话
- 多会话并行：同一项目可开多个会话，互不影响（Leader→n 新建，Leader→l 列表）。
- 子 Agent 会话导航：
| 快捷键 | 功能 |
|---|---|
↓ | 进入首个子会话 |
→/← | 下一个 / 上一个子会话 |
↑ | 返回父会话 |
5. 会话分享
将当前会话生成一条可分享链接，便于他人查看或调试：
/share # 或 Leader → x 导出，Leader 相关分享键- 默认对公开仓库自动分享；可用配置
OPENCODE_AUTO_SHARE或share: true/false控制。 - 反向导入：
opencode import <file-or-url>（见第 06 篇）。
6. LSP 与语义能力
OpenCode 会自动为项目加载对应语言的 LSP，使模型获得：
- 符号定义/引用跳转
- 类型与诊断信息
- 更准确的补全建议
无需手动配置；如需禁用自动下载：OPENCODE_DISABLE_LSP_DOWNLOAD=true。
进阶能力已就位。下一步阅读06-CLI 命令参考.md掌握命令行全部能力，再用07-实战案例.md练手。
本篇为 OpenCode 操作指导书系列之一，版本 v1.18.3。
