OpenCode 配置分享：默认 Agent、插件与 Provider

目录

1. 1. 当前配置
2. 2. 配置加载优先级
3. 3. 顶层字段速览
4. 4. default_agent = cx-local 的来源
5. 5. 插件体系（重点）
   1. 5.1 插件清单（npm 名称）
   2. 5.2 opencode-planpilot
   3. 5.3 opencode-workbench
   4. 5.4 opencode-web-preview
   5. 5.5 opencode-cx-agents
   6. 5.6 使用建议
6. 6. Provider 与模型路由

1. 当前配置

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false,
  "compaction": {
    "auto": true,
    "prune": true
  },
  "default_agent": "cx-local",
  "model": "openai/gpt-5.3-codex",
  "small_model": "openai/gpt-5.1-codex-mini",
  "plugin": [
    "opencode-planpilot",
    "opencode-workbench",
    "opencode-web-preview",
    "opencode-cx-agents"
  ],
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:CLAUDE_API_KEY}",
        "baseURL": "https://gateway.example.com/v1"
      }
    },
    "google": {
      "options": {
        "apiKey": "{env:GEMINI_API_KEY}",
        "baseURL": "https://gateway.example.com/v1beta"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}",
        "baseURL": "https://gateway.example.com/v1",
        "setCacheKey": true
      }
    }
  }
}

2. 配置加载优先级

OpenCode 配置优先级（低 -> 高）：

1. Remote .well-known/opencode
2. 全局 ~/.config/opencode/opencode.json
3. OPENCODE_CONFIG
4. 项目 opencode.json
5. .opencode 目录（agents/commands/plugins 等）
6. OPENCODE_CONFIG_CONTENT

全局层适合放长期默认值：default_agent、model、small_model、通用 provider 与通用插件。

3. 顶层字段速览

4. default_agent = cx-local 的来源

cx-local 由 opencode-cx-agents 插件注册，不在该配置中手写 agent 定义。

该插件当前提供的 canonical agents 为：cx-explore、cx-local、cx-global。

影响：

1. 全局配置更精简，agent 生命周期由插件统一维护。
2. 插件加载失败时，对应默认 agent 不会注册。

5. 插件体系（重点）

5.1 插件清单（npm 名称）

"plugin": [
  "opencode-planpilot",
  "opencode-workbench",
  "opencode-web-preview",
  "opencode-cx-agents"
]

对应 GitHub 仓库：

• opencode-planpilot
• opencode-workbench
• opencode-web-preview
• opencode-cx-agents

5.2 opencode-planpilot

定位：结构化推进复杂任务。
核心能力：

• 统一任务模型：plan -> step -> goal
• 支持 ai / human 执行者分离
• 下一步执行者为 ai 时可自动续跑

适用场景：长任务拆解、跨阶段改造、需要状态持续追踪的流程。

5.3 opencode-workbench

定位：多分支 / 多 worktree 并行编排。
核心能力：

• 会话与 worktree 显式绑定，降低任务串线风险
• 按 worktree 路由任务，支持并行推进
• 记录分支与任务上下文，便于回溯

适用场景：同仓库并行处理多个任务、多人协作分支并发。

5.4 opencode-web-preview

定位：前端预览会话与本地预览链路管理。
核心能力：

• 发现可用预览会话
• 启停本地预览 host
• 查询预览状态，便于回归验证

适用场景：需要快速验证 UI 或本地前端改动时。

5.5 opencode-cx-agents

定位：提供可复用的预设 agent 组合与权限基线。
核心能力：

• 提供 canonical agents：cx-explore、cx-local、cx-global
• 区分写入权限档位：
  • cx-local：工作区优先，external_directory: ask
  • cx-global：跨目录写入，external_directory: allow
• 与 opencode-planpilot、opencode-workbench、opencode-web-preview 协同使用，保持工具可见性

适用场景：

• 多仓库统一 agent 行为基线
• 需要按风险偏好选择默认写入权限

5.6 使用建议

1. 默认推荐 default_agent = cx-local，把高权限写入留给明确场景。
2. 需要跨目录自动写入时，再切换到 cx-global。
3. 启动后确认 agent 列表中可见 cx-explore / cx-local / cx-global。

6. Provider 与模型路由

当前 provider 设计为“单网关域名 + 多路由入口”：