OpenCode 配置

OpenCode 是开源 AI 编码代理工具，提供终端 TUI、桌面应用和 IDE 扩展三种使用方式。

• 官方文档：https://opencode.ai/docs/
• GitHub：https://github.com/anomalyco/opencode

1. 安装

macOS (Homebrew)

# 推荐用官方 tap，更新更快
brew install anomalyco/tap/opencode

通用安装脚本

curl -fsSL https://opencode.ai/install | bash

包管理器

# npm
npm install -g opencode-ai

# Bun
bun install -g opencode-ai

# pnpm
pnpm install -g opencode-ai

Arch Linux

sudo pacman -S opencode

安装完成后在项目目录运行 opencode 即可启动 TUI。首次使用建议运行 /init 命令，OpenCode 会分析项目结构并生成 AGENTS.md 文件（建议提交到 Git）。

2. 配置文件

OpenCode 使用 JSON / JSONC 格式的配置文件，支持多层级合并。

文件位置（优先级从低到高）

配置文件是合并关系，不是替换。后加载的只覆盖冲突的 key。

基础配置示例

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",  // 轻量任务（标题生成等）
  "autoupdate": true
}

3. Provider 连接

OpenCode 通过 AI SDK 和 Models.dev 支持 75+ LLM 提供商，包括 Anthropic、OpenAI、Google、OpenRouter、DeepSeek、Groq、Ollama 等。

连接方式

在 TUI 中运行 /connect 命令，选择提供商并输入 API Key：

/connect

API Key 存储在 ~/.local/share/opencode/auth.json。

常用提供商

自定义 Provider

可以接入任何 OpenAI 兼容 API：

{
  "provider": {
    "my-local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Local Model",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder (local)"
        }
      }
    }
  }
}

选择模型

连接 Provider 后，在 TUI 中运行 /models 查看可用模型列表：

/models

也可以在配置中直接指定默认模型：

{
  "model": "anthropic/claude-sonnet-4-5"
}

4. 插件系统

OpenCode 支持通过插件扩展功能，插件可以添加自定义工具、Hook 和外部集成。

插件加载方式

• 本地插件：放在 .opencode/plugins/ (项目级) 或 ~/.config/opencode/plugins/ (全局)
• npm 插件：在配置文件的 plugin 字段声明

本地插件依赖

如果插件需要 npm 包，在配置目录创建 package.json：

// ~/.config/opencode/package.json
{
  "dependencies": {
    "@opencode-ai/plugin": "1.2.10"
  }
}

OpenCode 启动时会用 Bun 自动安装依赖。

5. 我的配置

主配置 (~/.config/opencode/opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "oh-my-opencode@latest",
    "opencode-supermemory@latest"
  ],
  "mcp": {
    "pencil": {
      "command": [
        "/Applications/Pencil.app/Contents/Resources/app.asar.unpacked/out/mcp-server-darwin-arm64",
        "--app",
        "desktop"
      ],
      "enabled": true,
      "type": "local"
    }
  }
}

使用了两个核心插件：

同时挂载了 Pencil 的 MCP Server 用于设计协作。

Oh My OpenCode 模型搭配 (~/.config/opencode/oh-my-opencode.json)

Oh My OpenCode 是社区开发的增强插件，提供多 Agent 编排、任务系统和后台代理等高级功能。通过 oh-my-opencode.json 可以为每个 Agent 和任务类别指定不同的模型。

Agent 模型分配

不同 Agent 承担不同职责，按需匹配模型的能力和成本：

┌──────────────────────────────────────────────────────────────┐
│                    Agent 模型搭配                             │
├────────────────┬────────────────────────┬────────────────────┤
│ Agent          │ 模型                    │ 定位               │
├────────────────┼────────────────────────┼────────────────────┤
│ sisyphus       │ claude-opus-4-6 (max)  │ 主力编排、实现       │
│ hephaestus     │ gpt-5.3-codex (medium) │ 编码专家            │
│ oracle         │ gpt-5.2 (high)         │ 只读高质量顾问       │
│ librarian      │ gemini-3-flash         │ 文档检索、外部搜索    │
│ explore        │ grok-code-fast-1       │ 代码库搜索 (快速)    │
│ multimodal     │ kimi k2p5              │ 多模态分析           │
│ prometheus     │ claude-opus-4-6 (max)  │ 规划                │
│ metis          │ claude-opus-4-6 (max)  │ 预规划分析           │
│ momus          │ gpt-5.2 (medium)       │ 方案审查            │
│ atlas          │ kimi k2p5              │ 上下文映射           │
└────────────────┴────────────────────────┴────────────────────┘

核心搭配思路：

• 重型决策（sisyphus / prometheus / metis）→ Claude Opus 4.6 MAX — 需要最强推理能力
• 编码实现（hephaestus）→ GPT-5.3 Codex — 代码生成专精
• 顾问审查（oracle / momus）→ GPT-5.2 — 高质量分析，成本适中
• 快速搜索（explore）→ Grok Code Fast — 速度优先
• 文档检索（librarian）→ Gemini 3 Flash — 大上下文、低成本
• 多模态（multimodal / atlas）→ Kimi K2P5 — 视觉理解能力

Fallback 策略

关键 Agent 都配置了降级模型，确保主模型不可用时自动切换：

// oracle 的 fallback 链
"oracle": {
  "model": "openai/gpt-5.2",
  "fallback_models": [
    "opencode/gemini-3-pro",      // 第一备选
    "anthropic/claude-opus-4-6"   // 第二备选
  ]
}

搜索类 Agent (librarian / explore) 的 fallback 倾向免费模型（minimax-m2.5-free、glm-5-free），因为这类任务可以容忍一定质量降级。

任务类别模型分配

Oh My OpenCode 的任务系统会根据类别自动选择合适模型：

┌──────────────────────────────────────────────────────────────┐
│                   任务类别模型搭配                             │
├──────────────────┬───────────────────────┬───────────────────┤
│ 类别              │ 模型                   │ 说明              │
├──────────────────┼───────────────────────┼───────────────────┤
│ visual-engineering│ gemini-3.1-pro (high) │ 前端 / UI / 设计   │
│ ultrabrain       │ gpt-5.3-codex (xhigh) │ 超难逻辑任务        │
│ deep             │ gpt-5.3-codex (medium)│ 深度问题解决        │
│ artistry         │ gemini-3.1-pro (high) │ 创意方案            │
│ quick            │ claude-haiku-4-5       │ 简单修改            │
│ unspecified-low  │ claude-sonnet-4-6      │ 通用低强度          │
│ unspecified-high │ claude-opus-4-6 (max)  │ 通用高强度          │
│ writing          │ claude-sonnet-4-6      │ 文档写作            │
└──────────────────┴───────────────────────┴───────────────────┘

核心搭配思路：

• 前端和创意类（visual-engineering / artistry）→ Gemini 3.1 Pro — 多模态和创意能力强
• 高难度逻辑（ultrabrain / deep）→ GPT-5.3 Codex — 推理和编码兼顾
• 快速任务（quick）→ Claude Haiku — 速度快、成本低
• 写作和通用（writing / unspecified-low）→ Claude Sonnet — 文字质量好

实验性功能

"experimental": {
  "aggressive_truncation": true,        // 激进截断，节省上下文
  "task_system": true,                  // 任务管理系统
  "dynamic_context_pruning": {
    "enabled": true,                    // 动态上下文剪枝
    "notification": "minimal"           // 最小化通知
  }
}

后台任务并发

"background_task": {
  "providerConcurrency": {
    "opencode": 10  // OpenCode Zen 提供商最多 10 个并发请求
  }
}

6. TUI 常用操作

快捷键

Leader Key 默认为 ctrl+x，大多数操作需要先按 Leader Key 再按快捷键。

常用命令

Plan 模式

按 Tab 切换到 Plan 模式，此模式下 OpenCode 不会直接修改代码，只会给出实现方案建议。确认方案后再切回 Build 模式执行。

7. MCP Server

OpenCode 原生支持 MCP (Model Context Protocol) 服务器，可以在配置中声明：

{
  "mcp": {
    "server-name": {
      "command": ["path/to/server", "--arg"],
      "enabled": true,
      "type": "local"
    }
  }
}

也支持远程 MCP Server：

{
  "mcp": {
    "remote-server": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}

8. 推荐终端

OpenCode TUI 需要现代终端模拟器才能获得最佳体验：

• Ghostty (macOS / Linux) — 当前在用
• WezTerm (跨平台)
• Alacritty (跨平台)
• Kitty (macOS / Linux)