自学教程

OpenCode AGENTS.md 配置

OpenCode 教程

AGENTS.md 是 OpenCode v2 的项目级配置文件，放在项目根目录。用来定义多个智能体（Agent）角色、模型、文件权限、项目规则，AI 在本项目会话里会读取这份文件，约束行为、理解项目规范。

提示：执行 /init 命令会自动生成基础版 AGENTS.md。你可以手动编辑这个文件来自定义规则。

一、AGENTS.md 作用

  1. 定义多个 Agent 角色，比如：代码评审、开发、测试
  2. 控制权限：只读、可写、是否允许执行 Shell 命令
  3. 设置项目默认模型，覆盖全局 API 配置
  4. 编写项目专属规则、编码规范、目录约定
  5. 提交 Git 仓库，团队共享统一的 OpenCode 项目规则

重点：AGENTS.md 只保存配置规则，不要写入 API Key。密钥保存在 OpenCode 全局配置中，不要提交到代码仓库。

二、基础模板（自动生成版本）

执行 /init 后得到的默认模板示例：

# AGENTS.md
# OpenCode v2 项目智能体配置# 项目默认模型
model: opencode/zen
agents:
  - name: reviewer
    description: 代码评审智能体，仅阅读代码，不修改文件
    model: opencode/zen
    permissions: [read]

  - name: developer
    description: 开发智能体，可以读取和修改代码文件
    model: opencode/go
    permissions: [read, write]

三、配置项详解

1. 全局 model（项目默认模型）

model: opencode/zen
  • 作用：不单独指定 agent 模型时，默认使用这个模型
  • 支持官方模型 opencode/zen、opencode/go，也支持 openai/gpt-4o 等
  • 优先级：AGENTS.md 项目模型 > 全局 /connect 设置的模型

2. agents 数组：定义多个智能体角色

配置项说明
nameAgent 名称，Tab 快捷键切换时显示
description角色描述，告诉AI这个Agent的职责
model该Agent使用的模型，可选，不填则继承全局model
permissions权限列表，控制Agent能力

权限说明（permissions）

  • read：只读权限，可以读取项目所有文件，不能修改
  • write：允许新增、修改、删除本地代码文件
  • shell：允许执行终端命令（安装依赖、运行脚本等，谨慎开启）

示例：开启 shell 权限的开发Agent

  - name: dev-full
    description: 完整开发智能体，可以读写文件并执行shell命令
    model: opencode/go
    permissions: [read, write, shell]

安全建议：日常开发尽量不要默认开启 shell，仅在需要执行命令时单独使用该Agent。

四、项目规则（rules）

可以在文件末尾增加 rules，用来告诉AI本项目编码规范、目录约定，AI会严格遵守。

rules:
  - 使用 TypeScript，严格开启严格模式
  - 新增接口统一放在 src/routes 目录
  - 修改代码前先阅读同目录下的现有代码风格
  - 新增功能需要添加简单注释，不删除原有注释
  - 不改动第三方依赖目录 node_modules

五、完整示例（推荐生产项目）

# AGENTS.md
# OpenCode v2 Project Agent Configmodel: opencode/zen
agents:
  - name: reviewer
    description: 代码评审，阅读并分析代码，只输出方案，不修改任何文件
    model: opencode/zen
    permissions: [read]

  - name: coder
    description: 开发Agent，读写代码，不允许执行shell命令
    model: opencode/go
    permissions: [read, write]

  - name: builder
    description: 构建Agent，读写文件+执行shell，用于安装依赖、运行构建
    model: opencode/go
    permissions: [read, write, shell]

rules:
  - 项目使用 Vue3 + Typescript
  - 组件统一放在 src/components
  - 新增函数必须写JSDoc注释
  - 不要修改 package.json 之外的配置文件
  - 改动完成后，简单说明改动点

六、如何切换 Agent

  1. 进入 OpenCode TUI 界面
  2. 按 Tab 键循环切换定义好的 Agent（reviewer / coder / builder）
  3. 右下角状态栏会显示当前选中的Agent名称和权限

建议工作流：先用 reviewer 做方案评审，确认方案后切换 coder 执行代码修改。

七、生效规则

  1. 修改保存 AGENTS.md 后，新开OpenCode会话才会加载新配置，已经打开的会话不会自动刷新。
  2. AGENTS.md 放在项目根目录，OpenCode启动时自动读取。
  3. 可以提交到Git，团队所有成员打开项目都会加载同一套Agent配置。

八、常见踩坑

  1. ❌ 不要在 AGENTS.md 写入 API Key，密钥是全局隐私配置
  2. ❌ 权限不要过度放开，多人项目尽量区分只读/可写Agent
  3. ❌ 修改 AGENTS.md 后，当前正在运行的 OpenCode 会话不会自动更新，需要退出重进
  4. ❌ 模型名称写错会导致Agent无法加载，核对 /models 输出的模型名称

九、常用场景建议

  • 方案构思、阅读代码：使用 reviewer（仅read），避免误改代码
  • 写新功能、重构代码：使用 coder（read+write）
  • 执行npm install、运行构建脚本：临时切换 builder（带shell权限）

0 条笔记