当前位置：码云笔记 > 软件教程 > AI 编程助手 OpenCode 入门：15个工具+自定义代理+项目规则
艾米利亚艾米利亚 软件教程

AI 编程助手 OpenCode 入门：15个工具+自定义代理+项目规则

AI 概述
OpenCode 能听懂人话、精准干活，靠工具、规则、代理三大核心。工具赋予其读、写、执行命令等能力，有 15 个内置工具，支持自定义和 MCP 服务器扩展；规则通过 AGENTS.md 文件告知 AI 项目规范，分项目级和全局级，有优先级和自定义指令等；代理是 AI 小助手，分主、子代理，各有不同职责和权限，可 JSON 或 Markdown 配置，支持创建。三者配合，让 AI 融入开发流程，提升效率。
目录
文章目录隐藏
  1. 一、工具（Tools）
  2. 二、规则（Rules）
  3. 三、代理（Agents）
  4. 总结

AI 编程助手 OpenCode 入门：15 个工具+自定义代理+项目规则

用 OpenCode 这么久，你有没有好奇过它到底是怎么听懂人话、还能精准干活的？其实背后就靠三个东西：工具、规则、代理。工具让它会读会写会跑命令，规则让它懂你的项目规范，代理则是分工明确的小助手，开发、规划、审查各司其职。今天就把这三个核心概念掰开揉碎讲清楚，从配置到实战，看完你也能把 OpenCode 调教成真正的开发搭档。

一、工具（Tools）

简单说，工具就是 OpenCode 帮你干活的能力。读文件、改代码、跑命令，这些都靠工具。

1.1 工具概述

OpenCode 自带 15 个内置工具，够日常使用。还能通过自定义工具或 MCP 服务器扩展。默认全部开启，通过权限可以控制哪些需要审批。

1.2 工具配置

在 permission 字段设置：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny",
    "bash": "ask",
    "webfetch": "allow"
  }
}

通配符也能用，比如mymcp_*: ask让某个 MCP 服务器的工具都需审批。

1.3 内置工具详解

15 个工具，各有各的用处：

  • bash：跑 shell 命令。npm install、git status这些直接执行。
  • edit：精确替换文本改文件。LLM 改代码主要靠这个。edit 权限同时管着 write、patch、multiedit。
  • write：创建或覆盖文件。由 edit 权限控制。
  • read：读文件内容。大文件可以指定行范围。
  • grep：正则搜索。快速定位代码里的关键字。
  • glob：用 **/*.js 这类模式找文件。按修改时间排序返回。
  • list：列出目录内容。支持 glob 过滤。
  • lsp（实验性）：和 LSP 服务器交互，定义跳转、引用查找这些。得设置OPENCODE_EXPERIMENTAL_LSP_TOOL=true才启用。
  • patch：打补丁。diff 文件直接应用。
  • skill：加载 SKILL.md 技能文件。
  • todowrite：写待办事项。跟踪多步骤任务。子代理默认禁用，可以手动开。
  • todoread：读待办事项。看看哪些做了哪些没做。同样默认禁用。
  • webfetch：抓网页。查文档很方便。
  • websearch：联网搜索。用 Exa AI，不需要 API 钥匙。查找信息用这个，取特定 URL 内容用 webfetch。
  • question：执行中向用户提问。收集需求、澄清指令、让用户做选择。

1.4 自定义工具

自己定义函数让 LLM 调用，配置里声明就行。

1.5 MCP 服务器

MCP 是 Model Context Protocol，接入外部服务，数据库、API 都能连。

1.6 忽略模式

grep、glob、list 底层用 ripgrep，默认遵守 .gitignore。想搜被忽略的文件，建个.ignore：

!node_modules/
!dist/
!build/

二、规则（Rules）

AGENTS.md 这个文件能告诉 AI 你的项目规矩啥样。

2.1 规则概述

建个 AGENTS.md，把项目规范、代码风格、目录结构写进去。LLM 就会按这个来。跟 Cursor 的规则功能差不多。

2.2 初始化

运行/init命令，OpenCode 会扫描项目生成 AGENTS.md。有的话就在基础上补充。建议提交到 Git，团队共享。

2.3 规则文件示例

# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.

## Project Structure

- `packages/` - workspace 包
- `infra/` - 基础设施定义
- `sst.config.ts` - SST 主配置

## Code Standards

- 开启 TypeScript strict 模式
- 共享代码放 `packages/core/`
- 函数放 `packages/functions/`

## Monorepo Conventions

- 用 workspace 名字导入：`@my-app/core/example`

2.4 规则类型

项目级

根目录的 AGENTS.md，只在当前项目生效。

全局级

~/.config/opencode/AGENTS.md，所有项目都用。个人规则放这里，不提交 Git。

Claude Code 兼容

支持 CLAUDE.md 作为回退：

  • 项目：CLAUDE.md（没有 AGENTS.md 时）；
  • 全局：~/.claude/CLAUDE.md；
  • 技能：~/.claude/skills/。

禁用的话设环境变量：

export OPENCODE_DISABLE_CLAUDE_CODE=1

2.5 优先级

查找顺序：本地 → 全局 → Claude Code。同类里第一个匹配的生效。

2.6 自定义指令

opencode.json 里用 instructions 字段：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

远程 URL 也行，超时 5 秒。

2.7 引用外部文件

两种方式：

  1. opencode.json 的instructions；
  2. AGENTS.md 里手动写指令。

推荐第一种，monorepo 项目用 glob 模式很方便：packages/*/AGENTS.md

三、代理（Agents）

代理是专门的 AI 小助手，不同任务换不同代理。

3.1 代理概述

Plan 代理只分析不改代码，Build 代理干重活。切换着用，或者 @ 提及调用。

3.2 代理类型

主代理

直接对话的主力。用 Tab 键切换。内置 Build 和 Plan。

子代理

主代理调用的专业助手。也能 @ 提及调用。内置 General 和 Explore。

3.3 内置代理

  • Build（主代理）：默认代理，所有工具都开。开发工作全靠它。
  • Plan（主代理）：只读代理，分析和规划用。edit 和 bash 默认要审批，防止手滑改代码。
  • General（子代理）：通用研究代理，多步骤任务它来。能改文件，但不能用 todo。
  • Explore（子代理）：只读探索代理。快速搜代码、找文件，不修改任何东西。
  • Compaction、Title、Summary（隐藏代理）：系统自动调用，不能手动选。分别是压缩上下文、生成标题、做摘要。

3.4 代理用法

主代理用 Tab 切换。子代理可以自动调用，也能@general这样手动叫。会话间导航用Leader+Right/Left。

3.5 代理配置

JSON 配置

opencode.json 里配置：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Markdown 配置

放~/.config/opencode/agents/或项目级.opencode/agents/：

---
description: 代码审查代理
mode: subagent
tools:
  write: false
  edit: false
---

你是代码审查员，关注安全和性能。

文件名就是代理名。

3.6 代理配置选项

  • description：必填，说清楚代理干啥的。
  • temperature：0.0-1.0，越高越有创意。分析用低值，头脑风暴用高值。
  • steps：最大迭代次数。控制成本。
  • disable：禁用代理。
  • prompt：自定义提示词文件。
  • model：指定模型。provider/model-id格式。
  • tools：控制可用工具。代理级覆盖全局级。
  • permission：权限控制。edit、bash、webfetch 可以设ask/allow/deny。还能针对具体命令设：bash: { "git *": "ask" }
  • mode：primary/subagent/all。
  • hidden：设为 true 从 @ 补全里隐藏。
  • permission.task：控制能调用哪些子代理。
  • color：UI 颜色。十六进制或主题色。
  • top_p：和temperature二选一控制随机性。

其他选项直接传给模型提供商。

3.7 创建代理

opencode agent create

交互式创建，问保存位置、功能描述、工具权限，最后生成 Markdown 文件。

3.8 使用场景

  • Build：完整开发；
  • Plan：只分析不改；
  • Review：代码审查；
  • Debug：问题排查；
  • Docs：写文档。

3.9 示例代理

文档代理：

---
description: 写文档
mode: subagent
tools:
  bash: false
---

技术文档风格：清晰、结构、有例子。

安全审计代理：

---
description: 安全审计
mode: subagent
tools:
  write: false
  edit: false
---

关注：输入验证、认证授权、数据泄露、依赖漏洞。

总结

工具、规则、代理，构成了 OpenCode 的三大支柱：工具赋予 AI 执行能力，让读文件、改代码、跑命令不再依赖手动；规则将项目规范注入 AI 的思维，确保代码风格、目录结构始终如一；代理则实现专业分工，不同任务由不同助手负责，从开发到审计各司其职。三者相互配合，让 AI 从“能干活”进化到“会干活”，真正融入开发流程。用好这三大核心，你会发现复杂项目也能被拆解得井井有条，效率自然翻倍。现在就去配置你的工具、写下项目规则、创建专属代理，让 OpenCode 成为你开发路上的最强搭档。

以上关于AI 编程助手 OpenCode 入门：15个工具+自定义代理+项目规则的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。

「点点赞赏，手留余香」

赞 1 赏

给作者打赏，鼓励TA抓紧创作！

微信微信 支付宝支付宝

还没有人赞赏，快来当第一个赞赏的人吧！

声明：本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权/违法违规/事实不符，请将相关资料发送至 admin@mybj123.com 进行投诉反馈，一经查实，立即处理！
重要：如软件存在付费、会员、充值等，均属软件开发者或所属公司行为，与本站无关，网友需自行判断
码云笔记 » AI 编程助手 OpenCode 入门：15个工具+自定义代理+项目规则

艾米利亚 普通

分享到：

相关推荐

发表回复