Agents

对于 Primary 代理，请在会话期间使用 Tab 键循环浏览它们。您还可以使用配置的 switch_agent 键绑定。
可以调用子代理：
- 自动由 Primary 代理根据其描述执行专门任务。
- 通过在消息中 @提及 子代理手动进行。例如。
```
@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 选项提供代理的作用以及使用时的简要描述。

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

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

温度

使用 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。

最大步数

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

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

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

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

禁用

设置为 true 以取消代理。

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

提示

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

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

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

模型

使用 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 配置控制此代理中可用的工具。您可以通过将特定工具设置为 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
      }
    }
  }
}

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

权限

您可以配置权限来管理代理可以执行的操作。目前，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"
        }
      }
    }
  }
}

这可以采用全局模式。

{
  "$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 选项用于确定如何使用代理。

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

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

隐藏

使用 hidden: true 从 @ 自动完成菜单隐藏子代理。对于只能由其他代理通过任务工具以编程方式调用的内部子代理很有帮助。

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

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

任务权限

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

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

当设置为 deny 时，子代理社区任务工具描述中因此完全删除，模型不会尝试调用它。

颜色

在 UI 中的界面外观中使用 color 选项自定义代理。这会影响代理在界面中的显示方式。

使用有效的十六进制颜色（例如 #FF5733）或主题颜色：primary、secondary、accent、success、warning、error、info。

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

使用 top_p 选项控制响应多样性。控制随机性的温度替代方案。

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

值范围从 0.0 到 1.0。较低的值更加集中，较高的值更加多样化。

其他

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

例如，使用 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