OpenCode AI 编程助手高级配置详解

1.3 配置生成与多层级加载机制

生成机制

1. 自动扫描 (推荐实践)：在根目录终端执行 opencode 后，立即发送 /init 指令。程序内部的文件系统扫描模块将读取根目录的构建配置文件（如 package.json / go.mod / requirements.txt / turbo.json），识别项目特征，然后通过 LLM 生成初始版本的 AGENTS.md。生成完毕后，建议开发者直接进行编辑修改，并将文件提交至 Git 版本控制系统。
2. 手动编写：直接使用系统编辑器在指定路径创建文件，并遵循上述区块结构。

文件解析与寻址路径

• 项目根目录级：系统优先扫描当前执行 opencode 进程所在的物理路径。若匹配到 AGENTS.md 文件，则将其作为最高优先级的上下文配置读取。
• 系统全局级：若全盘无项目级配置，或需设定跨项目通用的底层准则（如：始终采用纯函数编程范式），可配置全局文件：
  • Windows 系统环境：C:\Users\你的用户名\.config\opencode\AGENTS.md
  • Linux / macOS 系统环境：~/.config/opencode/AGENTS.md 此处的指令权重将被具体的项目级配置文件覆盖。

异常路径与热重载操作

若文件放置于非标准目录（如 docs/AGENTS.md 或异名为 project-agent.md），初始化检测逻辑将失效，需要采用 TUI 手动注册：

/context add ./docs/AGENTS.md # 将非标准路径的文件数据推入当前上下文数组
/context clear # 执行内存清空，卸载所有已注册的 Context 数据模块
/context reload # 读取文件系统更新状态，重新加载根目录的配置
/context list # 打印当前内存中存活的所有配置项指针及其映射内容

二、提示词 (Prompt) 深度配置指南

除了上文所述的基于文件扫描的 AGENTS.md，OpenCode 核心组件还支持对特定的 Agent（智能代理）或 Mode（执行模式）通过配置文件实现底层逻辑与提示词覆盖。这部分配置定义在 JSON 结构或特定的 Markdown 前置数据中，直接修改调用 LLM 时的基础 System Prompt。

由于 OpenCode 工具包在初始化时不会主动在磁盘生成默认的全局配置文件，用户必须根据操作系统路径规范进行手动创建。全局配置文件路径设定如下：

• Windows 路径：C:\Users\<用户名>\.config\opencode\opencode.json
• Linux/macOS 路径：~/.config/opencode/opencode.json
• 或者在具体项目的根目录创建局部的 opencode.json 覆盖全局设定。该配置支持 JSONC 解析器（即允许嵌套 C 风格的双斜杠注释）。

2.1 通过 opencode.json 配置字段注入

在 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）读取字节流并替换该字符串。

2.2 基于纯 Markdown 文件的代理配置

对于习惯文档驱动架构的开发者，系统同时提供通过 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/ 规范）的交叉兼容性。

三、工具 (Tool) 与权限管理配置机制

AI 代理在 OpenCode 环境中对宿主操作系统产生影响的能力被封装为一个'工具 (Tool)'集合。内置工具库涵盖了数据捕获操作（如 read 读取、grep 正则检索、glob 路径匹配）和数据突变操作（如 write 写入覆写、edit 增量修改、bash 系统 Shell 执行、webfetch 远程 HTTP 请求）。工具系统拥有极高的权限敏感度，核心控制流通过 opencode.json 中的 permissions（权限判定级别）和 tools（可用性注册级别）对象进行管理。

配置采用多层级继承结构，覆盖合并优先级遵循深度优先原则：代理级权限 (per-agent) > 模式级权限 (per-mode) > 项目级配置文件 > 全局级配置文件。

3.1 权限模式枚举 (Permissions Enum)

permission 对象中的值仅接受特定字符串枚举，用于干预命令执行环节的人机交互阻断逻辑：

• allow：静默授权。工具被调度时，系统不向标准输出抛出确认提示框，直接建立底层进程或文件句柄。
• ask：阻断确认。工具被调度时，系统挂起当前异步线程，在 TUI 层弹出 [Yes/No] 轮询对话框，等待控制台输入确认事件后方可放行。
• deny：强制熔断。剥夺调度权限，向 LLM 运行时返回错误异常，说明权限被拒。

3.2 可用性布尔判定 (Tools Enable/Disable)

与 permission 不同，mode.xxx.tools 树层级中的键值严格要求布尔型 (true / false)。

• 当值为 false 时，该工具在当前模式下从注册表中被彻底剔除。LLM 发起函数调用 (Tool Calling) 检测时，将无法识别该工具的存在。
• 当值为 true 时，该工具被成功注册并向 LLM 暴露。但注意：值为 true 不代表能够绕过前述的安全阻断。系统将继续向下执行 permission 字段的鉴权。若 permission 为 "ask"，则布尔值为 true 的工具执行依然需要进行 TUI 确认。

3.3 权限配置对象结构示例解析

示例 1：防御性安全基线模型（全局默认层级）

配置策略为开放数据只读收集能力，对任何可能造成状态变更或系统注入的工具实施严格拦截。

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

示例 2：模式权限割裂模型（Mode 层级）

基于业务需求制定两套隔离的沙箱环境配置，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}}
  }
}

示例 3：高精细度 AST 与路径匹配规则（生产环境级推荐配置）

使用 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 (扩展技能) 体系配置规范

Skills 模块属于 OpenCode 系统中处理场景化、流程化业务指令的载体机制。区别于工具底层的 IO 拦截，Skills 配置的部署不需要大量修改 opencode.json 文件对象，其技术架构建立在操作系统文件目录发现机制之上。系统将根据文件布局动态挂载业务指令和规则流。

4.1 文件系统寻址机制与结构声明

OpenCode 底层扫描进程在生命周期初始化阶段会遍历特定的目录树。路径的遍历优先级遵循下述顺序：

1. 项目级目录优先级最高：.opencode/skills/<skill-name>/SKILL.md
2. 兼容层协议（Claude Code）：.claude/skills/<skill-name>/SKILL.md
3. 系统全局级目录：~/.config/opencode/skills/<skill-name>/SKILL.md
4. 全局兼容层：~/.claude/skills/<skill-name>/SKILL.md

构建一个新的功能模块（Skill），需严格满足以下磁盘结构要求：

1. 在合法搜索路径下创建文件夹，系统要求该文件夹标识符即为技能名称。名称校验规则采用正则表达式：小写英文字母、阿拉伯数字、短横线及下划线组合，长度受限于操作系统目录名策略。
2. 文件夹根目录必须包含主控声明文件，硬编码名称为大写的 SKILL.md。

例如，开发一个关于接口路由生成的技能，使用标准 Unix 命令流建立：

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

建立后需触发重启或重载操作使发现机制重新运行。

对于企业敏感工程，可从 opencode.json 层面对挂载流程实施控制：

{"permissions":{"skill":"ask"// 限制技能库加载算法，变更为手动轮询确认，默认状态通常为 "allow"}}

4.2 主控声明文件 (SKILL.md) 语法解析

主控文件要求使用双引擎解析格式，由文件首部的 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）'。
• YAML 区块与 Markdown 区块结合界限严格控制，元数据必须放置在绝对的第 0 行至第一个结束 --- 标识内。

五、MCP 扩展配置规范

在 OpenCode 的架构中，原生能力主要封装针对本地文件系统及进程调用的基本 IO 操作。对于更庞大的分布式工程系统，当需要 AI 具备'获取企业内部数据库'、'访问外部 Git 仓库元数据'或'触发远端 CI 环境构建'的能力时，需接入 MCP (Model Context Protocol，模型上下文协议) 扩展组件。

5.1 基于 opencode.json 的拓扑挂载

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) 接管输入输出流交互。

5.2 配置注入与命令辅助

开发者在完成文件修改后，需触发 TUI 重启断开当前运行时连接，或挂起终端后发送服务端热重载信令（如通过 opencode serve 守护进程模式重启）方可激活扩展层。

OpenCode 亦提供了交互式 CLI 命令以屏蔽底层的 JSON 结构组织工作：

opencode mcp add # 依据终端问询分步构建上述 JSON 对象，并处理 Token 键的安全录入
opencode mcp list # 查询当前内存堆中所有活跃建立的长连接与挂起状态

工程集成警戒建议：

1. Context 开销风险：如 Context7 或 GitHub 等复杂检索协议接入，极易返回大量无组织的数据块塞入上下文队列导致 LLM 超载，可以强制在主控制流提示词内收缩权限声明（如：'只有在遭遇库依赖冲突时，才允许初始化并调度 GitHub 搜索模块'）。
2. Credential 暴露风险：针对局部配置文件包含 HTTP Bearer Token 等认证签名的行为，必须将包含该 opencode.json 实体添加至项目根 .gitignore 的排除清单内，防止泄露。
3. 执行风险：由于 local 模式底层直接转译为系统原生命令，当加载不可溯源的 npm 包配置时存在被注入后门指令及挖矿脚本的提权危险。

六、记忆系统 (Memory) 层次架构与配置

为解决生成式 AI 固有的无状态协议（Stateless）所造成的短时遗忘问题。OpenCode 将记忆系统划分为运行在 RAM 级别的'会话级记忆（Session Memory）'和落盘在存储设备上的'跨会话持久记忆（Persistent Memory）'。工具架构层没有封装高度冗余的重型向量数据库（如 Qdrant 或 Milvus），而是依托纯文本与轻量插件体系处理持久化逻辑。

6.1 原生机制：利用 AGENTS.md 降维模拟持久库

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 版本快照完全追踪。技术局限在于受限于窗口令牌阈值限制，数据无法无限扩张。

6.2 插件驱动层：利用社区扩展引入结构化存储

对于依赖深层工程上下文解析、超长周期任务协作的企业级重度使用环境，标准文本内存池将产生性能瓶颈。需通过安装第三方插件以集成具有 add (推送) / search (召回) / forget (擦除) 工具抽象接口的高维存储介质。

1. supermemory 插件：利用 Supermemory 开放 API 获取远端服务或将数据下沉存储至本地轻量数据库层。该模块封装了完整的向量检索接口，解决数据块体积庞大的瓶颈。
2. opencode-agent-memory 插件：借鉴 Letta 架构建立内存分段块技术。将记忆分割为具有不同生命周期的局部域内存（Scoped memory blocks），区隔化处理针对独立开发人员的偏好信息与系统共用的项目全局架构信息，避免上下文数据污染。
3. simple-memory 等微缩型插件：为降低网络开销及组件复杂度，直接使用本地 SQLite 或键值对映射进行索引建立与磁盘 I/O。

七、结语

OpenCode CLI 及其工具生态提供了一套面向深度技术开发的配置控制平面，无论是轻量化的脚本调整还是整合 MCP 及 Memory 组件的系统级集成，均依靠基于文本的配置声明和细颗粒的系统权限管辖机制得以实现。