智能体

对于主智能体，使用 Tab 键在会话期间循环切换。你也可以使用配置的 switch_agent 快捷键。
子智能体可以通过以下方式调用：
- 由主智能体根据描述自动调用以执行专门任务。
- 在你的消息中手动通过 @ 提及 子智能体。例如：
```
@general help me search for this function
```
会话间导航：当子智能体创建自己的子会话时，你可以使用以下方式在父会话和所有子会话之间导航：
- <Leader>+Right（或你配置的 session_child_cycle 快捷键）向前循环：父级 → 子级1 → 子级2 → … → 父级
- <Leader>+Left（或你配置的 session_child_cycle_reverse 快捷键）向后循环：父级 ← 子级1 ← 子级2 ← … ← 父级
这允许你在主对话和专门的子智能体工作之间无缝切换。

配置

你可以自定义内置智能体，或通过配置创建自己的智能体。智能体可以通过两种方式配置：

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": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

你也可以使用 markdown 文件定义智能体。将它们放在：

全局: ~/.config/opencode/agents/
项目级: .opencode/agents/

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

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.

markdown 文件名即为智能体名称。例如，review.md 创建一个 review 智能体。

选项

让我们详细看看这些配置选项。

描述 Description

使用 description 选项提供关于智能体做什么以及何时使用它的简要描述。

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

这是一个必填的配置选项。

温度 Temperature

使用 temperature 配置控制 LLM 回复的随机性和创造性。

较低的值使回复更加专注和确定，而较高的值增加创造性和变化。

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

温度值通常范围在 0.0 到 1.0 之间：

0.0-0.2: 非常专注和确定性的回复，适合代码分析和规划
0.3-0.5: 平衡的回复，具有一定的创造性，适合一般开发任务
0.6-1.0: 更具创造性和多样化的回复，适合头脑风暴和探索

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

如果未指定温度，OpenCode 使用模型特定的默认值；大多数模型通常为 0，Qwen 模型为 0.55。

最大步骤 Max steps

使用 maxSteps 配置控制智能体在被迫仅用文本回复之前可以执行的最大智能体迭代次数。这允许希望控制成本的用户对智能体行为设置限制。

如果未设置，智能体将继续迭代，直到模型选择停止或用户中断会话。

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "maxSteps": 5
    }
  }
}

当达到限制时，智能体将收到一个特殊的系统提示，指示它用工作总结和剩余任务建议进行回复。

禁用 Disable

设置为 true 以禁用智能体。

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

提示词 Prompt

使用 prompt 配置为此智能体指定自定义系统提示词文件。提示词文件应包含特定于智能体用途的指令。

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

此路径是相对于配置文件所在位置的。因此，这对全局 OpenCode 配置和项目特定配置都有效。

模型 Model

使用 model 配置覆盖此智能体的模型。对于针对不同任务优化的不同模型非常有用。例如，规划使用更快的模型，实现使用能力更强的模型。

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

OpenCode 配置中的模型 ID 使用 provider/model-id 格式。例如，如果你使用 OpenCode Zen，你会使用 opencode/gpt-5.1-codex 来使用 GPT 5.1 Codex。

工具 Tools

使用 tools 配置控制此智能体可用的工具。你可以通过设置为 true 或 false 来启用或禁用特定工具。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

你还可以使用通配符同时控制多个工具。例如，禁用来自 MCP 服务器的所有工具：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

了解更多关于工具的信息。

权限 Permissions

你可以配置权限来管理智能体可以采取的操作。目前，edit、bash 和 webfetch 工具的权限可以配置为：

"ask" — 运行工具前询问批准
"allow" — 允许所有操作无需批准
"deny" — 禁用工具

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

你可以为每个智能体覆盖这些权限。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

你也可以在 Markdown 智能体中设置权限。

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.

你可以为特定的 bash 命令设置权限。

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

这可以使用 glob 模式。

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

你也可以使用 * 通配符来管理所有命令的权限。由于最后匹配的规则优先，请将 * 通配符放在前面，具体规则放在后面。

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

了解更多关于权限的信息。

模式 Mode

使用 mode 配置控制智能体的模式。mode 选项用于确定如何使用智能体。

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

mode 选项可以设置为 primary、subagent 或 all。如果未指定 mode，默认为 all。

隐藏 Hidden

使用 hidden: true 在 @ 自动完成菜单中隐藏子智能体。这对于只能通过 Task 工具由其他智能体以编程方式调用的内部子智能体很有用。

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

这仅影响自动完成菜单中的用户可见性。如果权限允许，模型仍可以通过 Task 工具调用隐藏的智能体。

任务权限 Task permissions

使用 permission.task 控制智能体可以通过 Task 工具调用哪些子智能体。使用 glob 模式进行灵活匹配。

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

当设置为 deny 时，子智能体完全从 Task 工具描述中移除，因此模型不会尝试调用它。

其他 Additional

你在智能体配置中指定的任何其他选项都将 直接传递 给提供商作为模型选项。这允许你使用特定于提供商的功能和参数。

例如，使用 OpenAI 的推理模型，你可以控制推理工作量：

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

这些附加选项是特定于模型和提供商的。请查看你的提供商文档以获取可用参数。

创建智能体

你可以使用以下命令创建新智能体：

opencode agent create

此交互式命令将：

询问保存智能体的位置；全局或项目特定。
描述智能体应该做什么。
生成适当的系统提示词和标识符。
让你选择智能体可以访问的工具。
最后，创建一个带有智能体配置的 markdown 文件。

用例

以下是不同智能体的常见用例。

Build agent: 启用所有工具的完整开发工作
Plan agent: 分析和规划而不进行更改
Review agent: 只有只读访问权限加上文档工具的代码审查
Debug agent: 专注于启用了 bash 和读取工具的调查
Docs agent: 有文件操作权限但没有系统命令的文档编写

示例

以下是你可能会觉得有用的一些示例智能体。

文档智能体

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

安全审计员

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues