Agent 配置指南

当你掌握了 Agent 的配置和使用，你就能从"对话式编程"升级到"调度式开发"。本文将详细介绍 Opencode 的 Agent 系统。

什么是 Agent？

在 Opencode 中，Agent（智能体） 是具有特定角色和能力的 AI 单元。不同的 Agent 擅长不同的任务：

有的擅长架构设计
有的擅长快速搜索
有的擅长文档编写
有的擅长前端开发

通过合理配置和调度 Agent，你可以让 AI 团队像真实团队一样协作。

内置 Agent 介绍

Opencode 内置了多个专业 Agent：

Agent 名称	角色定位	擅长任务	推荐模型
plan	规划者	任务拆解、方案设计	Claude Opus
build	执行者	代码实现、文件修改	Claude Sonnet
architect	架构师	系统设计、技术选型	GPT-5.2
explorer	探索者	代码搜索、结构分析	Gemini Flash
documenter	文档专家	文档编写、注释生成	Claude Sonnet
reviewer	审查员	代码审查、安全检查	Claude Opus

如何使用 Agent？

方法一：直接 @ 提及

在对话中直接 @ Agent 名称：

让 @architect 设计一个用户认证系统的架构

让 @explorer 找出所有 API 调用的代码

让 @reviewer 审查这个 PR 的安全性

方法二：切换默认 Agent

运行 /agents 命令，选择想要使用的 Agent。之后的对话都会使用该 Agent。

方法三：在配置中指定

在 opencode.json 中设置默认 Agent：

{
  "default_agent": "plan"
}

Agent 协作示例

场景：开发新功能

假设你要开发一个支付功能，可以这样调度 Agent：

1. @architect 设计支付系统的架构，包括：
   - 支持的支付方式（微信、支付宝、Stripe）
   - 数据库表结构
   - API 接口设计

2. @explorer 搜索项目中现有的支付相关代码

3. @plan 根据架构方案制定实施计划

4. @build 按计划实现代码

5. @reviewer 审查代码的安全性和性能

Opencode 会自动协调这些 Agent 完成任务。

场景：Bug 修复

@explorer 找出所有与用户登录相关的代码

@architect 分析登录失败的可能原因

@build 修复 Bug 并添加错误处理

@reviewer 确认修复没有引入新问题

自定义 Agent

你可以创建自己的 Agent。在 opencode.json 中添加：

{
  "agent": {
    // 创建一个前端专家 Agent
    "frontend-expert": {
      "description": "前端开发专家，精通 React 和 Vue",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一位资深前端工程师，精通 React、Vue、TypeScript 和现代 CSS。你的代码注重性能、可访问性和用户体验。",
      "tools": {
        "read": true,
        "write": true,
        "edit": true,
        "bash": "ask"
      }
    },
    
    // 创建一个只读的代码审查 Agent
    "security-auditor": {
      "description": "安全审计专家",
      "model": "anthropic/claude-opus-4-5",
      "prompt": "你是安全审计专家，专注于发现代码中的安全漏洞、性能问题和潜在 Bug。你不会修改代码，只会提供详细的审查报告。",
      "tools": {
        "read": true,
        "write": false,   // 禁止写入
        "edit": false,    // 禁止编辑
        "bash": "deny"    // 禁止执行命令
      }
    },
    
    // 创建一个数据库专家 Agent
    "database-expert": {
      "description": "数据库设计与优化专家",
      "model": "openai/gpt-5.2",
      "prompt": "你是数据库专家，精通 PostgreSQL、MySQL 和 MongoDB。你擅长设计高效的数据库架构、编写优化的 SQL 查询，并能识别性能瓶颈。",
      "temperature": 0.3,  // 降低随机性，提高准确性
      "tools": {
        "read": true,
        "write": true,
        "bash": {
          "*": "ask",
          "psql": "allow",
          "mysql": "allow"
        }
      }
    }
  }
}

Agent 配置项说明

配置项	类型	说明
`description`	string	Agent 的描述，帮助你记住它的用途
`model`	string	使用的 AI 模型
`prompt`	string	系统提示词，定义 Agent 的角色和行为
`temperature`	number	0-1，控制输出的随机性（0=确定性，1=创造性）
`tools`	object	工具权限配置

工具权限配置

{
  "tools": {
    "read": true,        // 是否允许读取文件
    "write": true,       // 是否允许创建文件
    "edit": true,        // 是否允许修改文件
    "bash": "ask",       // 命令执行权限：true/false/"ask"
    "webfetch": false    // 是否允许访问网络
  }
}

Agent 分工策略

策略一：按任务类型分工

{
  "agent": {
    "quick-fix": {
      "description": "快速修复小问题",
      "model": "deepseek/deepseek-coder",  // 使用快速模型
      "prompt": "你专注于快速修复简单的 Bug 和小问题。"
    },
    "complex-task": {
      "description": "处理复杂任务",
      "model": "anthropic/claude-opus-4-5",  // 使用强大模型
      "prompt": "你负责处理复杂的架构设计和重构任务。"
    }
  }
}

策略二：按技术栈分工

{
  "agent": {
    "backend-dev": {
      "description": "后端开发",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是后端工程师，精通 Node.js、Python 和数据库设计。"
    },
    "frontend-dev": {
      "description": "前端开发",
      "model": "openai/gpt-5.2",
      "prompt": "你是前端工程师，精通 React、Vue 和现代 CSS。"
    },
    "devops": {
      "description": "DevOps 工程师",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是 DevOps 工程师，精通 Docker、Kubernetes 和 CI/CD。"
    }
  }
}

策略三：按开发阶段分工

{
  "agent": {
    "designer": {
      "description": "设计阶段",
      "model": "anthropic/claude-opus-4-5",
      "prompt": "你负责系统设计和架构规划。",
      "tools": {
        "write": false,  // 设计阶段不写代码
        "edit": false
      }
    },
    "implementer": {
      "description": "实现阶段",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你负责按照设计方案实现代码。"
    },
    "tester": {
      "description": "测试阶段",
      "model": "openai/gpt-5.2",
      "prompt": "你负责编写测试用例和发现 Bug。"
    }
  }
}

高级技巧

1. Agent 链式调用

在 prompt 中指导 Agent 调用其他 Agent：

{
  "agent": {
    "orchestrator": {
      "description": "任务编排者",
      "model": "anthropic/claude-opus-4-5",
      "prompt": "你是任务编排者。当收到复杂任务时，你需要：\n1. 分析任务需求\n2. 调用 @architect 设计方案\n3. 调用 @explorer 搜索相关代码\n4. 调用 @implementer 实现功能\n5. 调用 @reviewer 审查代码"
    }
  }
}

2. 上下文注入

为 Agent 注入项目特定的知识：

{
  "agent": {
    "project-expert": {
      "description": "项目专家",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是本项目的专家。\n\n项目信息：\n- 技术栈：React + TypeScript + Node.js\n- 数据库：PostgreSQL\n- 部署：AWS\n- 编码规范：使用 ESLint + Prettier\n\n请始终遵循项目规范。"
    }
  }
}

3. 动态 Agent 选择

根据文件类型自动选择 Agent：

{
  "agent_rules": [
    {
      "pattern": "*.tsx",
      "agent": "frontend-dev"
    },
    {
      "pattern": "*.py",
      "agent": "backend-dev"
    },
    {
      "pattern": "Dockerfile",
      "agent": "devops"
    }
  ]
}

实战工作流

完整的功能开发流程

1. 需求分析
   @architect 分析需求并设计方案

2. 代码搜索
   @explorer 搜索相关代码和依赖

3. 任务拆解
   @plan 制定详细的实施计划

4. 代码实现
   @build 按计划实现功能

5. 代码审查
   @reviewer 审查代码质量和安全性

6. 文档编写
   @documenter 编写 API 文档和使用说明

Bug 修复流程

1. 问题定位
   @explorer 搜索相关代码

2. 根因分析
   @architect 分析 Bug 产生的原因

3. 修复实施
   @build 修复 Bug

4. 回归测试
   @reviewer 确认修复没有引入新问题

常见问题

Q: 如何查看所有可用的 Agent？

运行 /agents 命令。

Q: 可以同时使用多个 Agent 吗？

可以。在对话中 @ 多个 Agent，它们会协作完成任务。

Q: Agent 之间会共享上下文吗？

会。同一个会话中的所有 Agent 共享对话历史。

Q: 如何为 Agent 设置不同的模型？

在 Agent 配置中指定 model 字段即可。

下一步

本文由 OpenCodex 社区整理，欢迎分享你的 Agent 配置经验。