customizing-opencode

用途

Customizing OpenCode 用于配置与扩展 OpenCode 的行为。资料指出，可以通过配置文件、智能体（agents）、命令（commands）与扩展对 OpenCode 进行定制，包括主题、模型、自动更新、智能体、斜杠命令、MCP 外部工具、自定义工具函数、插件与钩子、工具访问权限、键盘快捷键以及颜色与外观。

配置位置与优先级

配置文件分为三类：

• 全局：~/.config/opencode/opencode.json，用于用户级偏好。
• 项目：./opencode.json，用于项目专属设置。
• 自定义：通过 $OPENCODE_CONFIG 环境变量覆盖路径。

优先级规则（后写覆盖先写）：远程 .well-known/opencode < 全局 < 自定义 < 项目。

快速参考对应关系

资料给出任务与配置位置的对应：

• 设置主题、模型、自动更新 → opencode.json，参考 config-schema.md。
• 定义专门智能体 → .opencode/agents/*.md 或配置，参考 agents.md。
• 创建斜杠命令 → .opencode/commands/*.md 或配置，参考 commands.md。
• 通过 MCP 添加外部工具 → opencode.json 的 mcp 段，参考 mcp-servers.md。
• 编写自定义工具函数 → .opencode/tools/*.ts，参考 custom-tools.md。
• 用插件/钩子扩展 → .opencode/plugins/*.ts 或 npm，参考 plugins.md。
• 控制工具访问 → opencode.json 的 permission 段，参考 permissions.md。
• 自定义键盘快捷键 → opencode.json 的 keybinds 段，参考 keybinds.md。
• 更改颜色/外观 → opencode.json 的 theme 或自定义 JSON，参考 themes.md。

目录结构

全局配置位于 ~/.config/opencode/，包含 opencode.json、AGENTS.md（全局规则）、agents/（全局智能体）、commands/（全局命令）、plugins/（全局插件）、skills/（全局技能）、tools/（全局自定义工具）、themes/（全局自定义主题）。

项目配置位于 .opencode/，具有相同结构：agents/、commands/、plugins/、skills/、tools/、themes/。

选择使用方式

资料列出需求与方案对应：

• 为所有项目更改模型/主题 → 全局 opencode.json。
• 项目专属智能体行为 → 项目 .opencode/agents/。
• 可复用提示模板 → 命令（.opencode/commands/）。
• 外部服务集成 → MCP 服务器。
• LLM 可调用的自定义逻辑 → 自定义工具。
• 响应 OpenCode 事件 → 插件。
• 限制危险操作 → 权限。

变量替换

可在任意配置值中使用：

{
  "model": "{env:OPENCODE_MODEL}",           // 环境变量
  "instructions": ["{file:./rules.md}"]      // 文件内容
}

规则（AGENTS.md）

项目指令会加载到 LLM 上下文中：

• ./AGENTS.md：项目（向上遍历到 git 根目录）。
• ~/.config/opencode/AGENTS.md：全局。
• 配置中的 instructions 数组：额外文件/通配符。

示例：

{
  "instructions": ["CONTRIBUTING.md", "docs/*.md"]
}

限制

资料未提供关于收费、价格、平台支持或具体效果的信息，暂未提供。