OpenCode 操作指导书五进阶使用适用版本OpenCode v1.18.3本篇目标掌握内置 Agent、自定义 Agent、MCP 接入、多会话与子 Agent 并行、会话分享等进阶能力。1. 内置 Agent 体系OpenCode 的 Agent 分三类Primary Agents直接交互build 默认plan 受限规划Subagents被调用/手动 general 通用explore 只读探索scout 外部研究Hidden 系统compactiontitlesummary1.1 Primary Agents主要 AgentAgent模式说明buildprimary默认所有工具可用标准开发planprimary受限 Agentfile edits/bash默认ask只规划不改动切换Tab循环 /ShiftTab反向 /Leader → a打开 Agent 列表。1.2 Subagents子 Agent由主 Agent 自动调用或你在消息中提及手动调用general通用有完整工具权限除 todo可并行多任务。explore快速只读探索代码库不修改文件。scout只读用于外部文档与依赖研究可克隆依赖库到缓存。示例general help me search for this function across the repo2. 自定义 Agent2.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-idmodeprimary/subagent/allpermission细粒度权限ask/allow/deny支持通配符prompt系统提示支持{file:./path}temperature/top_p随机性控制steps最大迭代次数达限后仅文本总结hidden仅 subagent 有效隐藏菜单colorUI 颜色常用权限键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. MCPModel Context ProtocolMCP 让 OpenCode 接入外部工具/数据源数据库、API、文件系统等。opencode mcpadd# 引导添加本地或远程 MCP 服务opencode mcp list# 或 mcp ls列出已配置及连接状态opencode mcp authname# 对支持 OAuth 的服务器认证opencode mcplogoutnameopencode mcp debugname# 调试 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_DOWNLOADtrue。进阶能力已就位。下一步阅读06-CLI 命令参考.md掌握命令行全部能力再用07-实战案例.md练手。本篇为 OpenCode 操作指导书系列之一版本 v1.18.3。
