OpenCode 配置体系实战：AGENTS、权限、技能、MCP、记忆

/context add ./docs/AGENTS.md
/context clear
/context reload
/context list

全局级配置也可以放在固定位置：

• Windows：C:\Users\你的用户名\.config\opencode\AGENTS.md
• Linux / macOS：~/.config/opencode/AGENTS.md

这类全局文件适合放那些跨项目都成立的底层规则，但项目级文件通常会覆盖它。

二、opencode.json：提示词、Agent、Mode 都能管

除了 AGENTS.md，OpenCode 还会从 opencode.json 或 opencode.jsonc 读取更细的配置。它能直接改模型调用时的基础 Prompt，也能给不同 Agent、Mode 分配不同工具和权限。

一个常见写法是这样：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "专用于提供 Pull Request 级别代码审核工作的静态审查代理实例",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你被设定为严苛的代码质量审查算法实体。运算逻辑重点关注 XSS/SQLi 等安全防范、时间/空间复杂度性能损耗，以及模块的高内聚低耦合维护性分析。输出流规范：首先输出 200 字以内的缺陷统计摘要，然后按优先级倒序列举具体的 AST 优化或重构建议方案。",
      "tools": {"write": false, "edit": false, "bash": false}
    }
  },
  "mode": {
    "review": {"prompt": "{file:./prompts/code-review.txt}"}
  }
}

这里有两个地方比较实用：

• $schema 便于编辑器补全和校验；
• prompt 过长时，可以用 {file:...} 这种外部文件引用，维护成本低很多。

如果你更习惯文档式配置，也可以把 Agent 写成独立的 Markdown 文件，放在 ~/.config/opencode/agents/ 或 .opencode/agents/：

---
name: code-reviewer
description: 专用于提供 Pull Request 级别代码审核工作的静态审查代理实例
model: anthropic/claude-sonnet-4-5
---
你被设定为严苛的代码质量审查算法实体。运算逻辑重点关注 XSS/SQLi 等安全防范、时间/空间复杂度性能损耗，以及模块的高内聚低耦合维护性分析。
输出流规范：首先输出缺陷统计摘要，然后按优先级倒序列举具体的优化或重构建议方案。
所有通讯均需序列化为标准的 Markdown 文本格式，禁止直接输出未包裹的代码块。

这套方式的优点是读起来直观，和一些其他生态的目录约定也更接近。缺点是文件一多，命名和触发词就得管得更细，否则很容易乱。

三、工具与权限：别让模型拿到太多默认权限

OpenCode 里的工具大致分两类：读数据的，比如 read、grep、glob；改数据的，比如 write、edit、bash、webfetch。真正要紧的不是'有没有这些工具'，而是它们在什么范围内可用。

权限是分层继承的，优先级大致是：代理级 > 模式级 > 项目级 > 全局级。这个顺序很重要，很多配置问题其实都出在'以为某层生效了，实际被更高层覆盖了'。

3.1 权限枚举

permission 的取值通常有三种：

• allow：直接放行，不弹确认；
• ask：需要用户确认；
• deny：直接拒绝。

3.2 工具开关

tools 里的值是布尔型：

• true 表示这个工具在当前模式里可注册；
• false 表示直接不暴露给模型。

但别把这两层混为一谈。工具能不能被看到，和能不能真的执行，是两回事。比如工具开了 true，如果权限还是 ask，那照样会卡确认。

3.3 三种常见配置

先看一个偏保守的全局默认配置：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "write": "ask",
    "bash": "ask"
  }
}

这种配置适合先把读能力放开，写和执行都留给人确认。上线前或者接手陌生项目时，我会更愿意用这类保守配置。

再看模式隔离的写法：

{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "build": {"tools": {"write": true, "edit": true, "bash": true}},
    "plan": {"tools": {"write": false, "edit": false, "bash": false, "read": true, "grep": true, "glob": true}}
  }
}

这比一套权限打到底更顺手。规划阶段就别给写权限，真的要改代码，再切到 build 模式。

最后是更细粒度的规则：

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": {
    "bash": {"*": "ask", "git *": "allow", "npm *": "allow", "pnpm *": "allow", "rm *": "deny", "touch test*": "allow"},
    "edit": {"*": "deny", "**/*.md": "ask", "packages/web/src/**/*.tsx": "allow"},
    "webfetch": "deny"
  }
}

这类规则适合生产环境。像 rm * 直接禁掉，就少很多误操作风险；对特定路径放行 edit，也比一刀切更稳。

四、Skills：把流程型任务做成可发现目录

Skills 这部分更像'任务模板库'。它不是在运行时临时拼一大段提示词，而是通过文件系统发现机制自动加载约定好的能力块。

搜索路径一般是这些：

1. .opencode/skills/<skill-name>/SKILL.md
2. .claude/skills/<skill-name>/SKILL.md
3. ~/.config/opencode/skills/<skill-name>/SKILL.md
4. ~/.claude/skills/<skill-name>/SKILL.md

新建一个 Skill，目录名就是技能名，目录里必须有 SKILL.md。比如：

mkdir -p .opencode/skills/api-endpoint
touch .opencode/skills/api-endpoint/SKILL.md

如果改了文件，通常要重启或者 reload 一次，让发现机制重新扫目录。

SKILL.md 本身一般是 YAML frontmatter + Markdown 正文：

---
name: api-endpoint
description: >
  核心路由与服务层控制器自动生成模块。包含依赖注入配置方案、RESTful 风格动作映射及基础数据层桩点代码。该模块具备自动触发条件：当语义分析中包含 endpoint、api、controller、route 等词汇向量时自动压入请求栈。
license: MIT
compatibility: opencode
metadata:
  audience: backend-developers
  workflow: nestjs-api-generation
---
## 运行时指令注入集
- 执行边界：严禁偏离 RESTful API 设计范式。所有响应体必须被包裹在统一的数据结构 JSON 协议内。
- 上下文联动：必须检索目标工程的 src/common/exceptions 结构并使用自定义异常捕获类。
- 格式化约束：DTO 校验参数需直接使用 class-validator 装饰器绑定。
## 执行序列定义
1. 第一阶段：对参数 DTO 对象进行属性拆解。
2. 第二阶段：生成对应的 Controller 映射文件。
3. 第三阶段：建立 Service 层逻辑壳层并执行 IoC 注入。
## 断言与行为演示
输入特征捕获：User: 请求新增一个管理员鉴权登入逻辑。
Output 模型预设：
- HTTP 协议动词：POST 映射。
- 注入 JWT 令牌签名逻辑及加密算法库引入。
- 抛出 401 异常占位符代码块。

这里最关键的是 name 和目录名要一致，description 也别写得太虚。否则模型触发时很容易误判。

五、MCP：把外部数据和服务接进来

OpenCode 原生更偏本地 IO。要让它碰企业内部数据库、外部 Git 元数据，或者远端 CI，就得上 MCP（Model Context Protocol）。

MCP 也可以写进 opencode.json，比如这样：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "enterprise-github-connector": {
      "type": "remote",
      "url": "https://api.internal-mcp.domain.com/v1",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer token_xxxxx_yyyyy",
        "X-Custom-Context": "backend-repo"
      }
    },
    "local-postgres-analyzer": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "@opencode/mcp-postgresql-plugin", "--host", "127.0.0.1"]
    }
  }
}

这里的取舍也挺明显：

• remote 适合接远端服务，配置简单，但要注意地址和鉴权信息；
• local 直接起子进程，集成更贴近本地环境，但第三方包的可信度要盯紧。

改完配置后，通常要重启 TUI 或重新拉起服务，MCP 才会真正生效。CLI 里也有辅助命令：

opencode mcp add
opencode mcp list

实际用的时候，我更建议先把接入范围收小一点。像 GitHub 检索这类能力，如果一上来就全开，最常见的问题不是'不能用'，而是返回的数据太多，模型根本消化不完。

还有一件事别省：带 Token 的局部配置记得放进 .gitignore，不然迟早会踩坑。

六、Memory：用文本和插件做记忆

OpenCode 里的记忆分两层：会话级记忆和跨会话持久记忆。它不是靠重型向量库硬顶，默认更偏文本和轻量插件。这种设计没那么'平台化'，但够实用，尤其在配置和代码生成这类场景里。

6.1 直接写进 AGENTS.md

最省事的办法，就是把长期偏好写进 AGENTS.md。因为这个文件会被持续注入上下文，所以它很像一个轻量的伪持久存储。

## 持久记忆与状态保留层 (Persistent Memory & Style Tracking)
- 核心强制要求：所有 TypeScript 运行环境必须强制通过 strict mode 审查，禁用隐式 any 类型。
- 语法屏蔽方案：项目级强制抹除 var 关键字定义，执行引擎替换为 const 和 let 块作用域生命周期。
- 反馈更新管道控制：如果指令输入流内出现'记录该偏好'、'覆盖现有设定'等行为动词词法，必须由 AI 调用文件系统 edit 工具，精准覆写本文件的'User Preferences'数组节点。
- User Preferences Data (由系统守护进程维护)：
  - [2026-03-04]: 引入代码提交规则引擎限制，限制执行 conventional commits 语义化标准。
  - [2026-03-01]: 状态切片管理算法方案从 Redux 迁移至 Zustand，所有生成代码按新方案解耦。

这种方式优点是简单、可追踪，Git 也能直接管住。缺点是容量有限，东西多了以后，还是得往外拆。

6.2 用插件做结构化存储

如果项目上下文更重，或者任务周期更长，纯文本内存池就会吃紧。这个时候可以接插件，给它 add、search、forget 这类接口。

常见方向有三个：

• supermemory：适合做远端或本地轻量存储；
• opencode-agent-memory：更偏分段记忆，适合区分个人偏好和项目全局信息；
• simple-memory 之类的小插件：直接落到 SQLite 或键值存储，成本低。

插件方案的核心不是'更高级'，而是'更适合长周期任务'。如果只是一个中小型前端项目，很多时候 AGENTS.md 加少量模式配置就够了，没必要把系统弄得过重。

结尾

OpenCode 的这一套配置，表面上看是几份文件，实际是在搭一个可控的 AI 工作台：上下文怎么给、权限怎么收、哪些任务能自动发现、外部系统怎么接、长期偏好怎么保留，都能落到文件里。它不算轻，但一旦规则定下来，AI 才更像在工程里干活，而不是只会聊天。