agent-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Configuration

Agent 配置

Configure and customize OpenCode agents for specialized tasks and workflows.

为特定任务和工作流配置及自定义OpenCode Agent。

Overview

概述

OpenCode agents are specialized AI assistants that can be configured for specific tasks. The agent system supports two types:

Primary agents - Main assistants you interact with directly (switchable via Tab key)
Subagents - Specialized assistants invoked by primary agents or via @ mention

Agents can be customized with specific prompts, models, tool access, and permissions to create focused workflows optimized for different development scenarios.

OpenCode Agent是可针对特定任务进行配置的专业AI助手。Agent系统支持两种类型：

Primary Agent - 你直接交互的主要助手（可通过Tab键切换）
Subagent - 由Primary Agent调用或通过@提及唤起的专业助手

可以为Agent配置特定的提示词、模型、工具访问权限和操作权限，以创建针对不同开发场景优化的专属工作流。

Core Concepts

核心概念

Agent Types

Agent类型

Primary Agents

Main conversation partners
Switch between them using Tab key or configured keybind
Examples: Build (full access), Plan (restricted for analysis)

Subagents

Invoked automatically by primary agents for specialized tasks
Can be manually invoked with @ mention (e.g.,
```
@general help me search
```
)
Examples: General (multi-step tasks), Explore (codebase exploration)

Primary Agent

主要对话伙伴
可通过Tab键或配置的快捷键在它们之间切换
示例：Build（全权限访问）、Plan（仅用于分析的受限权限）

Subagent

由Primary Agent自动调用以完成专业任务
可通过@提及手动唤起（例如：
```
@general help me search
```
）
示例：General（多步骤任务）、Explore（代码库探索）

Built-in Agents

内置Agent

OpenCode includes four primary built-in agents:

Build (Primary)

Default agent with all tools enabled
Full file operations and system commands
Standard development work

Plan (Primary)

Restricted agent for planning and analysis
File edits and bash commands set to
```
ask
```
by default
Analyzes and suggests without modifying code

General (Subagent)

General-purpose for complex questions and multi-step tasks
Full tool access except todo
Execute multiple units of work in parallel

Explore (Subagent)

Fast, read-only codebase exploration
Cannot modify files
Find patterns, search keywords, answer codebase questions

OpenCode包含四个内置Primary Agent：

Build（Primary）

默认Agent，启用所有工具
支持完整的文件操作和系统命令
适用于标准开发工作

Plan（Primary）

用于规划和分析的受限Agent
文件编辑和bash命令默认设置为
```
ask
```
权限
仅分析并提出建议，不修改代码

General（Subagent）

适用于复杂问题和多步骤任务的通用型Agent
除todo外拥有完整工具访问权限
可并行执行多个工作单元

Explore（Subagent）

快速、只读的代码库探索Agent
无法修改文件
查找模式、搜索关键词、解答代码库相关问题

Switching and Invoking Agents

切换与唤起Agent

Switch primary agents:

Press Tab key during a session
Cycles through available primary agents

Invoke subagents:

Automatically by primary agents based on descriptions
Manually via @ mention:
```
@explore find the authentication logic
```

Navigate between sessions:

Leader+Right: Cycle forward (parent → child1 → child2 → parent)
Leader+Left: Cycle backward

切换Primary Agent：

在会话中按Tab键
在可用的Primary Agent间循环切换

唤起Subagent：

Primary Agent根据任务描述自动唤起
通过@提及手动唤起：
```
@explore find the authentication logic
```

在会话间导航：

Leader+Right：向前循环（父会话→子会话1→子会话2→父会话）
Leader+Left：向后循环

Configuration Methods

配置方式

JSON Configuration

JSON配置

Configure agents in

opencode.json

json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "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
      }
    }
  }
}

在

opencode.json

中配置Agent：

json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "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 Configuration

Markdown配置

Create agent files in:

Global:
```
~/.config/opencode/agents/
```
Project:
```
.opencode/agents/
```

Example

~/.config/opencode/agents/review.md

markdown

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

在以下目录创建Agent文件：

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

示例

~/.config/opencode/agents/review.md

：

markdown

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

Essential Configuration Options

核心配置选项

Description (Required)

Description（必填）

Brief description of what the agent does and when to use it.

json

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

简要描述Agent的功能及适用场景。

json

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

Mode

Controls how the agent can be used.

```
primary
```
- Main agent, switchable via Tab
```
subagent
```
- Invoked by other agents or @ mention
```
all
```
- Both (default if not specified)

控制Agent的使用方式。

```
primary
```
- 主要Agent，可通过Tab键切换
```
subagent
```
- 由其他Agent唤起或通过@提及调用
```
all
```
- 同时支持以上两种模式（未指定时默认）

Model

Override the model for specific agents.

json

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

Model format:

provider/model-id

为特定Agent覆盖默认模型。

json

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

模型格式：

provider/model-id

Temperature

Control response randomness and creativity (0.0-1.0).

0.0-0.2: Focused, deterministic (code analysis)
0.3-0.5: Balanced (general development)
0.6-1.0: Creative (brainstorming)

控制响应的随机性和创造性（取值范围0.0-1.0）。

0.0-0.2：专注、确定性强（适用于代码分析）
0.3-0.5：平衡型（适用于通用开发）
0.6-1.0：创造性强（适用于头脑风暴）

Tools

Enable or disable specific tools.

json

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false,
        "mymcp_*": false  // Wildcard to disable MCP server tools
      }
    }
  }
}

启用或禁用特定工具。

json

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false,
        "mymcp_*": false  // Wildcard to disable MCP server tools
      }
    }
  }
}

Permissions

Control what actions an agent can take.

Permission levels:

```
allow
```
- Execute without approval
```
ask
```
- Prompt for approval
```
deny
```
- Disable the tool

json

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git push": "ask"
        },
        "webfetch": "deny"
      }
    }
  }
}

控制Agent可执行的操作。

权限级别：

```
allow
```
- 无需批准即可执行
```
ask
```
- 执行前需提示用户批准
```
deny
```
- 禁用该工具

json

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git push": "ask"
        },
        "webfetch": "deny"
      }
    }
  }
}

Prompt

Custom system prompt file for the agent.

json

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

Path is relative to config file location.

为Agent配置自定义系统提示词文件。

json

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

路径相对于配置文件所在位置。

Max Steps

Maximum agentic iterations before text-only response.

json

{
  "agent": {
    "quick-thinker": {
      "steps": 5
    }
  }
}

Agent在转为纯文本响应前可执行的最大迭代次数。

json

{
  "agent": {
    "quick-thinker": {
      "steps": 5
    }
  }
}

Additional Options

其他选项

hidden - Hide subagent from @ autocomplete menu

json

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

color - Customize UI appearance (hex color or theme color)

json

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    }
  }
}

top_p - Alternative to temperature for controlling diversity (0.0-1.0)

hidden - 在@自动补全菜单中隐藏Subagent

json

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

color - 自定义UI外观（十六进制颜色或主题颜色）

json

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    }
  }
}

top_p - 替代temperature的多样性控制参数（取值范围0.0-1.0）

MUST FOLLOW

必须遵守

Always define
color
,
model
, and
temperature
for every agent in
opencode.json
— never in the markdown agent file. These fields belong in

opencode.json

as the single source of truth for runtime configuration.

json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "your-agent-name": {
      "model": "github-copilot/claude-sonnet-4.6",
      "temperature": 0.3,
      "color": "#ff6b6b"
    }
  }
}

Do not include

model

temperature

, or

color

in the agent's

.opencode/agents/<name>.md

frontmatter. The markdown file should only contain

description

mode

tools

permission

steps

hidden

, and the system prompt body.

务必在
opencode.json
中为每个Agent定义
color
、
model
和
temperature
— 绝不要在Markdown Agent文件中配置这些字段。这些字段属于运行时配置，应统一放在

opencode.json

中作为唯一可信来源。

json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "your-agent-name": {
      "model": "github-copilot/claude-sonnet-4.6",
      "temperature": 0.3,
      "color": "#ff6b6b"
    }
  }
}

请勿在Agent的

.opencode/agents/<name>.md

前置元数据中包含

model

、

temperature

或

color

。Markdown文件应仅包含

description

、

mode

、

tools

、

permission

、

steps

、

hidden

以及系统提示词主体内容。

Creating Custom Agents

创建自定义Agent

Interactive Creation

交互式创建

Use the built-in command:

bash

opencode agent create

This interactive process:

Asks where to save (global or project)
Requests agent description
Generates system prompt and identifier
Lets you select tool access
Creates markdown file with configuration

使用内置命令：

bash

opencode agent create

该交互式流程：

询问保存位置（全局或项目）
请求Agent描述
生成系统提示词和标识符
允许你选择工具访问权限
创建包含配置的Markdown文件

Manual Creation Steps

手动创建步骤

Identify the use case - What specific task or workflow?
Choose configuration method - JSON in
```
opencode.json
```
or markdown file
Set required fields:
- ```
description
```
  - When to use this agent
- ```
mode
```
  - Primary or subagent
Configure tools and permissions - What can the agent access?
Add custom prompt (optional) - Specialized instructions
Test the agent - Try it on real tasks and iterate

明确使用场景 - 该Agent用于完成什么特定任务或工作流？
选择配置方式 - 在
```
opencode.json
```
中使用JSON配置，或创建Markdown文件
设置必填字段：
- ```
description
```
  - 该Agent的适用场景
- ```
mode
```
  - Primary或Subagent
配置工具和权限 - Agent可访问哪些资源？
添加自定义提示词（可选） - 专属指令
测试Agent - 在实际任务中试用并迭代优化

Common Patterns

常见配置模式

Read-Only Analysis Agent

只读分析Agent

json

{
  "agent": {
    "analyzer": {
      "description": "Analyzes code without making changes",
      "mode": "subagent",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

json

{
  "agent": {
    "analyzer": {
      "description": "Analyzes code without making changes",
      "mode": "subagent",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Documentation Writer

文档撰写Agent

markdown

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

markdown

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

Security Auditor

安全审计Agent

markdown

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

markdown

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

Faster Model for Planning

快速规划模型

json

{
  "agent": {
    "quick-plan": {
      "description": "Fast planning with cheaper model",
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

json

{
  "agent": {
    "quick-plan": {
      "description": "Fast planning with cheaper model",
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Quick Reference

快速参考

Switch Agents

切换Agent

Tab key - Cycle through primary agents
@ mention - Invoke subagent (e.g.,
```
@explore find auth code
```
)

Tab键 - 在Primary Agent间循环切换
@提及 - 唤起Subagent（例如：
```
@explore find auth code
```
）

Navigate Sessions

会话导航

Leader+Right - Next child session
Leader+Left - Previous child session

Leader+Right - 切换到下一个子会话
Leader+Left - 切换到上一个子会话

Configuration Locations

配置文件位置

Global JSON:
```
~/.config/opencode/opencode.json
```
Project JSON:
```
.opencode/opencode.json
```
Global agents:
```
~/.config/opencode/agents/
```
Project agents:
```
.opencode/agents/
```

全局JSON：
```
~/.config/opencode/opencode.json
```
项目JSON：
```
.opencode/opencode.json
```
全局Agent：
```
~/.config/opencode/agents/
```
项目Agent：
```
.opencode/agents/
```

Permission Levels

权限级别

```
allow
```
- No approval needed
```
ask
```
- Prompt user
```
deny
```
- Disabled

```
allow
```
- 无需批准
```
ask
```
- 需提示用户确认
```
deny
```
- 禁用

Temperature Ranges

Temperature取值范围

0.0-0.2: Focused (analysis, planning)
0.3-0.5: Balanced (general dev)
0.6-1.0: Creative (brainstorming)

0.0-0.2：专注型（分析、规划）
0.3-0.5：平衡型（通用开发）
0.6-1.0：创意型（头脑风暴）

Additional Resources

额外资源

Reference Files

参考文档

For detailed information:

references/primary-agents.md
- In-depth primary agent configuration
references/subagents.md
- Subagent setup and invocation strategies
references/permissions.md
- Complete permission system details

如需详细信息，请查阅：

references/primary-agents.md
- Primary Agent深度配置指南
references/subagents.md
- Subagent设置与调用策略
references/permissions.md
- 完整权限系统详情

Example Files

示例文件

Working examples in

examples/

custom-agents.md
- Real-world custom agent configurations

examples/

目录下的可用示例：

custom-agents.md
- 真实场景下的自定义Agent配置示例