OpenCode AI 编程助手的高级配置方法。涵盖 AGENTS.md 上下文注入机制、opencode.json 全局及项目级配置、工具权限管理（allow/ask/deny）、Skills 扩展技能体系部署、MCP 协议接入规范以及记忆系统（Session/Persistent）架构。通过示例展示了如何定义 Agent 角色、约束代码规范、设置安全白名单及集成外部数据源，旨在帮助开发者优化 AI 辅助编程体验并保障系统安全。
OpenCode 的核心上下文注入机制依赖于 AGENTS.md 配置文件。该文件解决的核心技术问题是弥补单次对话中 AI 对工程全局缺乏感知的问题。系统在每次发起大模型 API 请求时，会将 AGENTS.md 的文本内容序列化并前置拼接在 System Prompt 区域。
一个符合 OpenCode 解析器的标准 AGENTS.md 文件应包含以下层级结构（文件格式采用标准 Markdown 解析引擎，无需编写 YAML 前置元数据）：
# Project AI Agent Configuration
## 1. Agent Role
- Role: Vue3 + TypeScript 前端开发工程师
- Expertise: 精通 Element Plus 组件库体系、Pinia 状态管理库架构、Vue Router 路由控制逻辑，熟悉基于 rem/vw 的移动端物理像素适配方案。
## 2. Project Context
- Tech Stack: Vue3, TypeScript, Vite, Element Plus
- Core Files: src/main.ts, src/App.vue, src/router/index.ts
- Dependencies: 依赖解析表映射至 package.json (关键核心模块：vue@3.4.0, typescript@5.2.2)
- Project Structure:
├── src/
│ ├── components/ (通用 UI 组件树)
│ ├── views/ (业务路由视图组件)
│ ├── router/ (路由定义与鉴权拦截器)
│ └── store/ (全局状态树与持久化逻辑)
## 3. Coding Standards
- Naming 规范：严格执行组件名 PascalCase 命名法（如 UserForm），变量名与函数执行 camelCase 命名法（如 userName）。
- Comment 规范：暴露级别的函数定义必须包含完整 JSDoc 标准注释，高复杂度算法区域要求提供单行注释说明业务意图。
- Format 规范：严格依附工程 Prettier 配置文件（单引号字符串、强制语句末尾分号、2 空格严格缩进）。
## 4. Action Rules
- 目录白名单：仅允许对 src/views/ 和 src/components/ 目录树下节点执行 write/edit 工具。
- 目录黑名单：锁定 src/main.ts 及 package.json，禁止 AI 实例进行无确认的直接修改。
- 输出声明：所有生成代码流的末尾需附带文本格式的 diff 说明，标出被修改的行号区间。
## 5. Skills Binding
- 已加载插件树：ESLint 静态代码分析检查、Prettier 格式化调用、Vue 单文件组件 AST 生成模块。
- 推荐未加载树：Vitest 单元测试桩点生成模块、Swagger 接口定义序列化模块。
opencode 后，立即发送 /init 指令。程序内部的文件系统扫描模块将读取根目录的构建配置文件（如 package.json / go.mod / requirements.txt / turbo.json），识别项目特征，然后通过 LLM 生成初始版本的 AGENTS.md。生成完毕后，建议开发者直接进行编辑修改，并将文件提交至 Git 版本控制系统。opencode 进程所在的物理路径。若匹配到 AGENTS.md 文件，则将其作为最高优先级的上下文配置读取。C:\Users\你的用户名\.config\opencode\AGENTS.md~/.config/opencode/AGENTS.md
此处的指令权重将被具体的项目级配置文件覆盖。若文件放置于非标准目录（如 docs/AGENTS.md 或异名为 project-agent.md），初始化检测逻辑将失效，需要采用 TUI 手动注册：
/context add ./docs/AGENTS.md # 将非标准路径的文件数据推入当前上下文数组
/context clear # 执行内存清空，卸载所有已注册的 Context 数据模块
/context reload # 读取文件系统更新状态，重新加载根目录的配置
/context list # 打印当前内存中存活的所有配置项指针及其映射内容
除了上文所述的基于文件扫描的 AGENTS.md，OpenCode 核心组件还支持对特定的 Agent（智能代理）或 Mode（执行模式）通过配置文件实现底层逻辑与提示词覆盖。这部分配置定义在 JSON 结构或特定的 Markdown 前置数据中，直接修改调用 LLM 时的基础 System Prompt。
由于 OpenCode 工具包在初始化时不会主动在磁盘生成默认的全局配置文件，用户必须根据操作系统路径规范进行手动创建。全局配置文件路径设定如下：
C:\Users\<用户名>\.config\opencode\opencode.json~/.config/opencode/opencode.jsonopencode.json 覆盖全局设定。该配置支持 JSONC 解析器（即允许嵌套 C 风格的双斜杠注释）。在 JSON 对象中，通过建立 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 键用于绑定 JSON Schema 验证文件，在 VS Code 等编辑器内可激活自动完成与校验。model 字段支持对不同 Agent 绑定特定模型，覆盖默认设定。prompt 字段接受标准的字符串输入。若文本过长导致 JSON 结构维护成本升高，OpenCode 提供了基于特定语法的外部文件解析宏：{file:相对路径}。运行时加载器会截获此语法，从磁盘对应路径（如 ./prompts/code-review.txt）读取字节流并替换该字符串。对于习惯文档驱动架构的开发者，系统同时提供通过 Markdown 文件管理 Agent 参数的解析器支持。相关文件需部署在系统全局路径 ~/.config/opencode/agents/ 或工程局部路径 .opencode/agents/ 中。
配置格式强制采用在文件顶部插入两段 --- 分隔符组成的 YAML Frontmatter 区域声明系统变量，文件主体区域声明 Prompt 参数：
示例文件结构（位于 agents/code-reviewer.md）：
---
name: code-reviewer
description: 专用于提供 Pull Request 级别代码审核工作的静态审查代理实例
model: anthropic/claude-sonnet-4-5
---
你被设定为严苛的代码质量审查算法实体。运算逻辑重点关注 XSS/SQLi 等安全防范、时间/空间复杂度性能损耗，以及模块的高内聚低耦合维护性分析。
输出流规范：首先输出缺陷统计摘要，然后按优先级倒序列举具体的优化或重构建议方案。
所有通讯均需序列化为标准的 Markdown 文本格式，禁止直接输出未包裹的代码块。
此种基于文件映射系统的配置，不仅利于长文本字符串阅读，亦提供了与其他生态（如 Cursor 的 .agents/ 目录规范或 Claude Code 的 .claude/ 规范）的交叉兼容性。
AI 代理在 OpenCode 环境中对宿主操作系统产生影响的能力被封装为一个'工具 (Tool)'集合。内置工具库涵盖了数据捕获操作（如 read 读取、grep 正则检索、glob 路径匹配）和数据突变操作（如 write 写入覆写、edit 增量修改、bash 系统 Shell 执行、webfetch 远程 HTTP 请求）。工具系统拥有极高的权限敏感度，核心控制流通过 opencode.json 中的 permissions（权限判定级别）和 tools（可用性注册级别）对象进行管理。
配置采用多层级继承结构，覆盖合并优先级遵循深度优先原则：代理级权限 (per-agent) > 模式级权限 (per-mode) > 项目级配置文件 > 全局级配置文件。
permission 对象中的值仅接受特定字符串枚举，用于干预命令执行环节的人机交互阻断逻辑：
allow：静默授权。工具被调度时，系统不向标准输出抛出确认提示框，直接建立底层进程或文件句柄。ask：阻断确认。工具被调度时，系统挂起当前异步线程，在 TUI 层弹出 [Yes/No] 轮询对话框，等待控制台输入确认事件后方可放行。deny：强制熔断。剥夺调度权限，向 LLM 运行时返回错误异常，说明权限被拒。与 permission 不同，mode.xxx.tools 树层级中的键值严格要求布尔型 (true / false)。
false 时，该工具在当前模式下从注册表中被彻底剔除。LLM 发起函数调用 (Tool Calling) 检测时，将无法识别该工具的存在。true 时，该工具被成功注册并向 LLM 暴露。但注意：值为 true 不代表能够绕过前述的安全阻断。系统将继续向下执行 permission 字段的鉴权。若 permission 为 "ask"，则布尔值为 true 的工具执行依然需要进行 TUI 确认。配置策略为开放数据只读收集能力，对任何可能造成状态变更或系统注入的工具实施严格拦截。
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"*": "ask",
"read": "allow",
"grep": "allow",
"glob": "allow",
"edit": "ask",
"write": "ask",
"bash": "ask"
}
}
基于业务需求制定两套隔离的沙箱环境配置，Build 模式作为高权态释放全量读写控制，Plan 模式作为低权态锁定为只读审计。
{
"$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}}
}
}
使用 Glob 通配符语法，对底层指令字符串和文件系统路径树进行深度的粒度切分，实现零信任架构下的精确白名单管理。
{
"$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"
}
}
在该技术模型下，例如若 AI 试图调用 bash rm -rf node_modules 命令，将匹配到 "rm *": "deny" 规则被系统硬性阻断。若试图发起对 packages/web/src/App.tsx 的 AST 修改，由于匹配到白名单路径规则，系统将静默放行该 IO 操作。任何更改需通过进程重启（退出 TUI 重进或执行 opencode serve）触发配置文件热重载。
Skills 模块属于 OpenCode 系统中处理场景化、流程化业务指令的载体机制。区别于工具底层的 IO 拦截，Skills 配置的部署不需要大量修改 opencode.json 文件对象，其技术架构建立在操作系统文件目录发现机制之上。系统将根据文件布局动态挂载业务指令和规则流。
OpenCode 底层扫描进程在生命周期初始化阶段会遍历特定的目录树。路径的遍历优先级遵循下述顺序：
.opencode/skills/<skill-name>/SKILL.md.claude/skills/<skill-name>/SKILL.md~/.config/opencode/skills/<skill-name>/SKILL.md~/.claude/skills/<skill-name>/SKILL.md构建一个新的功能模块（Skill），需严格满足以下磁盘结构要求：
SKILL.md。例如，开发一个关于接口路由生成的技能，使用标准 Unix 命令流建立：
mkdir -p .opencode/skills/api-endpoint
touch .opencode/skills/api-endpoint/SKILL.md
建立后需触发重启或重载操作使发现机制重新运行。
对于企业敏感工程，可从 opencode.json 层面对挂载流程实施控制：
{"permissions":{"skill":"ask"// 限制技能库加载算法，变更为手动轮询确认，默认状态通常为 "allow"}}
主控文件要求使用双引擎解析格式，由文件首部的 YAML 序列化参数区和尾部的 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 属性值（必须字段）：作为注册标识符。若值为 api-endpoint，对应物理文件夹也必须定名为 api-endpoint，禁止存在大写及空格或特殊标点符。description 属性值（必须字段）：此参数在 LLM 的向量检索阶段作为召回评分的唯一依赖基准。若描述泛化空洞（例如'自动编写代码'），将引发极高的误加载率并形成对请求上下文的阻塞效应。正确的工程写法应包含'功能定义 + 触发词集（when to trigger）'。--- 标识内。在 OpenCode 的架构中，原生能力主要封装针对本地文件系统及进程调用的基本 IO 操作。对于更庞大的分布式工程系统，当需要 AI 具备'获取企业内部数据库'、'访问外部 Git 仓库元数据'或'触发远端 CI 环境构建'的能力时，需接入 MCP (Model Context Protocol，模型上下文协议) 扩展组件。
MCP 数据接入层同样受控于 opencode.json (或 .jsonc) 文件。按照全局复用机制或独立解耦机制决定其存放位置。对于数据库直连插件，出于安全合规考虑，强烈建议单独编写至局部项目的配置文件内。
以下为结构体接入配置的技术示例，包含对远程 RPC 及本地微进程挂载的双范式支持：
{
"$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"]
}
}
}
数据结构解析：
mcp 顶级键值映射一个哈希对象。子级键（如 enterprise-github-connector）作为运行时在进程中维持的长连接句柄唯一标识名。type 枚举：声明通讯信道建立模式。若为 "remote" 模式，则强制检验 url 属性。系统将调用底层基于 HTTP/SSE 协议发起长连接协商，配置中的 headers 内容将被无损注入网络层。若为 "local" 模式，则强制检验 command 数组属性，由操作系统建立子进程 (Child Process) 接管输入输出流交互。开发者在完成文件修改后，需触发 TUI 重启断开当前运行时连接，或挂起终端后发送服务端热重载信令（如通过 opencode serve 守护进程模式重启）方可激活扩展层。
OpenCode 亦提供了交互式 CLI 命令以屏蔽底层的 JSON 结构组织工作：
opencode mcp add # 依据终端问询分步构建上述 JSON 对象，并处理 Token 键的安全录入
opencode mcp list # 查询当前内存堆中所有活跃建立的长连接与挂起状态
工程集成警戒建议：
opencode.json 实体添加至项目根 .gitignore 的排除清单内，防止泄露。local 模式底层直接转译为系统原生命令，当加载不可溯源的 npm 包配置时存在被注入后门指令及挖矿脚本的提权危险。为解决生成式 AI 固有的无状态协议（Stateless）所造成的短时遗忘问题。OpenCode 将记忆系统划分为运行在 RAM 级别的'会话级记忆（Session Memory）'和落盘在存储设备上的'跨会话持久记忆（Persistent Memory）'。工具架构层没有封装高度冗余的重型向量数据库（如 Qdrant 或 Milvus），而是依托纯文本与轻量插件体系处理持久化逻辑。
OpenCode 处理低复杂度状态延续的最有效技术手段是将记忆体硬编码写入 AGENTS.md。因系统底层在任何实例化状态下都会将其推入系统调用头部，构成了'伪永久存储区'。
操作范式： 编辑配置文件，分配固定的 Memory 写入块区域。
## 持久记忆与状态保留层 (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，所有生成代码按新方案解耦。
当开启 write 和 edit 权限处于 allow 或被用户确认通过状态时，该配置文件具有自更新迭代能力。优点为实现成本近似为零且被 Git 版本快照完全追踪。技术局限在于受限于窗口令牌阈值限制，数据无法无限扩张。
对于依赖深层工程上下文解析、超长周期任务协作的企业级重度使用环境，标准文本内存池将产生性能瓶颈。需通过安装第三方插件以集成具有 add (推送) / search (召回) / forget (擦除) 工具抽象接口的高维存储介质。
supermemory 插件：利用 Supermemory 开放 API 获取远端服务或将数据下沉存储至本地轻量数据库层。该模块封装了完整的向量检索接口，解决数据块体积庞大的瓶颈。opencode-agent-memory 插件：借鉴 Letta 架构建立内存分段块技术。将记忆分割为具有不同生命周期的局部域内存（Scoped memory blocks），区隔化处理针对独立开发人员的偏好信息与系统共用的项目全局架构信息，避免上下文数据污染。simple-memory 等微缩型插件：为降低网络开销及组件复杂度，直接使用本地 SQLite 或键值对映射进行索引建立与磁盘 I/O。OpenCode CLI 及其工具生态提供了一套面向深度技术开发的配置控制平面，无论是轻量化的脚本调整还是整合 MCP 及 Memory 组件的系统级集成，均依靠基于文本的配置声明和细颗粒的系统权限管辖机制得以实现。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online