Agents - OpenCode Docs | OpenCode Tutorial

Agent 是专门的 AI 助手，可以针对特定任务和工作流程进行配置。它们允许您创建具有自定义提示、模型和工具访问权限的专注工具。

Note

💡 提示

使用 plan agent 分析代码并查看建议，而无需进行任何代码更改。

您可以在会话期间切换 agent，或者使用 @ 提及来调用它们。

##类型

OpenCode 中有两种类型的 agent；主要 agent 和子 agent。

###主要 agent

主要 agent 是您直接与之交互的主要助手。您可以使用 Tab 键或您配置的 switch_agent 快捷键在它们之间循环切换。这些 agent 处理您的主要对话。工具访问权限通过权限进行配置——例如，Build 启用了所有工具，而 Plan 则受到限制。

Note

💡 提示

您可以使用 Tab 键在会话期间切换主要 agent。

OpenCode 带有两个内置的主要 agent，Build 和 Plan。我们将在下面介绍这些。

###子 agent

子 agent 是专门的助手，主要 agent 可以调用它们来执行特定任务。您也可以通过在消息中 @ 提及 它们来手动调用它们。

OpenCode 带有两个内置的子 agent，General 和 Explore。我们将在下面介绍这些。

##内置

OpenCode 带有两个内置的主要 agent 和两个内置的子 agent。

###Build

模式: primary

Build 是默认的主要 agent，启用了所有工具。这是开发工作的标准 agent，您需要完全访问文件操作和系统命令。

###Plan

模式: primary

一个受限制的 agent，专为规划和分析而设计。我们使用权限系统来让您更好地控制并防止意外更改。默认情况下，以下所有内容都设置为 ask:

file edits: 所有写入、补丁和编辑
bash: 所有 bash 命令

当您希望 LLM 分析代码、建议更改或创建计划，而不对您的代码库进行任何实际修改时，此 agent 非常有用。

###General

模式: subagent

一个通用的 agent，用于研究复杂问题和执行多步骤任务。具有完全的工具访问权限（除了 todo），因此它可以在需要时进行文件更改。使用此 agent 并行运行多个工作单元。

###Explore

模式: subagent

一个快速的、只读的 agent，用于浏览代码库。无法修改文件。当您需要通过模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时，请使用此 agent。

##用法

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

##配置

您可以通过配置自定义内置 agent 或创建自己的 agent。可以通过两种方式配置 agent：

###JSON

在您的 opencode.json 配置文件中配置 agent：

bash

{
  "$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 文件定义 agent。将它们放置在：

全局：~/.config/opencode/agents/
每个项目：.opencode/agents/

bash

---
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 文件名将成为 agent 名称。例如，review.md 创建一个 review agent。

##选项

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

###Description

使用 description 选项来提供 agent 的简要描述，以及何时使用它。

bash

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

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

###Temperature

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

较低的值使响应更加集中和确定，而较高的值则增加创造性和可变性。

bash

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

Temperature 值通常在 0.0 到 1.0 之间：

0.0-0.2: 非常集中和确定的响应，非常适合代码分析和规划
0.3-0.5: 平衡的响应，具有一定的创造性，适用于一般的开发任务
0.6-1.0: 更具创造性和多样性的响应，可用于头脑风暴和探索

bash

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

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

###Max steps

控制 agent 在被迫仅以文本响应之前可以执行的最大 agent 迭代次数。这允许希望控制成本的用户设置 agent 操作的限制。

如果未设置此值，则 agent 将继续迭代，直到模型选择停止或用户中断会话。

bash

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

当达到限制时，agent 会收到一个特殊的系统提示，指示它响应其工作的摘要和建议的剩余任务。

###Disable

设置为 true 以禁用 agent。

bash

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

###Prompt

使用 prompt 配置为此 agent 指定自定义系统提示文件。提示文件应包含特定于 agent 目的的说明。

bash

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

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

###Model

使用 model 配置来覆盖此 agent 的模型。对于使用针对不同任务优化的不同模型非常有用。例如，用于规划的更快模型，用于实施的更强大的模型。

Note

💡 提示

如果您未指定模型，则主要 agent 使用全局配置的模型，而子 agent 将使用调用该子 agent 的主要 agent 的模型。

bash

{
  "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 配置控制此 agent 中可用的工具。您可以通过将它们设置为 true 或 false 来启用或禁用特定工具。

bash

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

Note

📝 注意

agent 特定的配置会覆盖全局配置。

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

bash

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

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

###Permissions

您可以配置权限来管理 agent 可以执行的操作。目前，可以配置 edit、bash 和 webfetch 工具的权限，以：

"ask" — 在运行工具之前提示批准
"allow" — 允许所有操作，无需批准
"deny" — 禁用该工具

bash

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

您可以为每个 agent 覆盖这些权限。

bash

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

您还可以在 Markdown agent 中设置权限。

bash

---
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 命令设置权限。

bash

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

这可以采用 glob 模式。

bash

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

您还可以使用 * 通配符来管理所有命令的权限。由于最后一个匹配的规则优先，因此首先放置 * 通配符，然后在之后放置特定规则。

bash

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

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

###Mode

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

bash

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

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

###Hidden

使用 hidden: true 从 @ 自动完成菜单中隐藏子 agent。对于仅应由其他 agent 通过 Task 工具以编程方式调用的内部子 agent 非常有用。

bash

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

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

Note

📝 注意

仅适用于 mode: subagent agent。

###Task permissions

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

bash

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

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

Note

💡 提示

规则按顺序评估，并且 最后一个匹配的规则获胜。在上面的示例中，orchestrator-planner 同时匹配 *（拒绝）和 orchestrator-*（允许），但由于 orchestrator-* 出现在 * 之后，因此结果为 allow。

Note

💡 提示

用户始终可以通过 @ 自动完成菜单直接调用任何子 agent，即使 agent 的任务权限会拒绝它。

###Additional

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

例如，对于 OpenAI 的推理模型，您可以控制推理工作量：

bash

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

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

Note

💡 提示

运行 opencode models 查看可用模型的列表。

##创建 Agent

您可以使用以下命令创建新的 Agent：

bash

opencode agent create

这个交互式命令将：

询问将 Agent 保存到何处；全局或项目特定。
描述 Agent 应该做什么。
生成适当的系统提示和标识符。
允许您选择 Agent 可以访问哪些工具。
最后，创建一个包含 Agent 配置的 markdown 文件。

##用例

以下是不同 Agent 的一些常见用例。

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

##示例

以下是一些您可能会觉得有用的示例 Agent。

Note

💡 提示

您有想要分享的 Agent 吗？提交一个 PR。

###文档 Agent

bash

---
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

###安全审计员

bash

---
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