自定义智能体配置

用 JSON 或 Markdown 定义角色，并设置模型、提示、权限、步数和显示属性。

This page has not been translated into English yet. The original Chinese version is shown below.

自定义智能体可以收窄任务职责，或针对不同任务选择模型和工具。首先写清用途，再配置实际权限，最后用代表任务验证它是否按预期工作。

文件与命名

在 opencode.json 的 agent 对象定义角色，或使用 Markdown 文件：

全局：~/.config/opencode/agents/。
项目：.opencode/agents/。

Markdown 文件名成为角色名称，例如 review.md 定义 review。示例：

---
description: Review code without changing files
mode: subagent
permission:
  edit: deny
  bash: deny
---

Review the selected code and explain actionable findings.

正文是角色提示。这里同时禁止文件编辑与 shell，避免仅依赖“不要修改”这句话；其他工具权限仍按实际配置确定。

核心属性

属性	用途
`description`	描述用途与使用时机，官方要求提供
`mode`	`primary`、`subagent` 或 `all`，省略默认 `all`
`prompt`	自定义系统提示，支持 `{file:...}` 引用
`model`	角色模型，格式 `provider/model-id`
`permission`	角色权限覆盖，与全局权限合并
`steps`	最大 agentic 迭代次数
`disable`	`true` 时禁用
`hidden`	对子智能体隐藏 `@` 补全，不阻止获准的 Task 调用
`color`	有效十六进制颜色或主题色名称

prompt 文件相对路径以配置文件所在目录为基准。未指定模型时，主智能体使用全局模型，子智能体使用调用方主智能体模型。

限制迭代次数

steps 限制的是代理迭代次数，不是秒数或费用。达到上限后，代理收到要求，以纯文本总结已做工作并提出剩余任务。未设置时继续迭代，直到模型结束或用户中断。

旧字段 maxSteps 已弃用，应使用 steps。例如为一个简短分析角色设置 steps: 5，其中 5 是配置选择，不是默认值。

模型选项

temperature 控制采样随机性；未指定时采用模型相关默认。Agents 页称多数模型通常为 0，Qwen 通常为 0.55，不能把“通常”写成所有版本和提供商的固定值。top_p 范围为 0.0 到 1.0，是另一种多样性控制。

额外属性会作为模型选项传递给提供商，例如某些 OpenAI 模型的 reasoningEffort、textVerbosity。支持的字段取决于模型与提供商，配置接受一个键不代表模型支持它。

权限与旧配置

角色权限优先于普通全局权限；系统托管配置仍应按托管设置核对。对 bash 等细粒度规则，最后匹配规则生效。

旧 tools 布尔配置已弃用，新配置使用 permission。官方 Config 示例仍有旧 tools，本页采用 Agents 与 Permissions 专门页的现行写法。完整工具权限和默认例外见权限与工具。

交互式创建

运行：

opencode agent create

向导会询问保存范围和角色用途，生成提示及标识符，让你选择允许的权限，然后创建 Markdown 文件。官方说明未选择的权限会被拒绝；检查生成结果后再用于真实任务。