开发

OpenCode 配置

开源 AI 编码代理工具 OpenCode 的完整配置指南，包括安装、模型、MCP 和 Skills 配置。

admin

24 Feb 2026 • 4 min read

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 格式的配置文件，支持多层级合并。

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

位置	路径	用途
远程配置	`.well-known/opencode`	组织级默认
全局配置	`~/.config/opencode/opencode.json`	用户偏好
自定义路径	`OPENCODE_CONFIG` 环境变量	自定义覆盖
项目配置	项目根目录 `opencode.json`	项目专属
内联配置	`OPENCODE_CONFIG_CONTENT` 环境变量	运行时覆盖

配置文件是合并关系，不是替换。后加载的只覆盖冲突的 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。

常用提供商

提供商	认证方式	说明
Anthropic	Claude Pro/Max 订阅或 API Key	支持浏览器 OAuth
OpenAI	ChatGPT Plus/Pro 订阅或 API Key	支持浏览器 OAuth
OpenRouter	API Key	聚合多家模型
OpenCode Zen	OpenCode 官方 API Key	官方测试验证过的模型列表
GitHub Copilot	GitHub 设备码认证	需 Copilot 订阅
Ollama	无需 Key	本地模型

自定义 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"
    }
  }
}

使用了两个核心插件：

插件	用途
oh-my-opencode	多 Agent 编排系统，提供 Oracle、Librarian、Explore 等专业代理
opencode-supermemory	持久化记忆系统，跨会话保留项目知识

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

6. TUI 常用操作

快捷键

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

操作	快捷键
退出	`ctrl+c` / `ctrl+d` / `<leader>q`
新会话	`<leader>n`
会话列表	`<leader>l`
会话时间线	`<leader>g`
打中断	`escape`
命令面板	`ctrl+p`
切换模型	`<leader>m`
切换 Agent	`tab` / `shift+tab`
切换 Build/Plan 模式	`tab`
文件搜索引用	`@` 键
撤销变更	`/undo`
分享会话	`/share`

常用命令

命令	说明
`/connect`	连接 LLM Provider
`/models`	查看和切换模型
`/init`	初始化项目（生成 AGENTS.md）
`/undo`	撤销上一次变更
`/redo`	重做变更
`/share`	分享当前会话

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)