OpenCode 安装配置

概述

OpenCode 是一个开源的 AI 编程助手，提供多种使用形态，包括命令行（CLI）、客户端、IDE 插件和云端环境。

核心优势:

免费模型支持，开箱即用
开源，灵活可扩展
四种使用形态，满足不同场景
强大的插件生态系统

OpenCode

https://github.com/anomalyco/opencode

Oh-My-OpenCode

https://github.com/code-yeongyu/oh-my-opencode

安装配置

CLI 安装

OpenCode 提供了多种安装方式，适配不同的操作系统和包管理器。

方式一: Homebrew（推荐）

# 使用官方 tap（始终最新）
brew install anomalyco/tap/opencode

# 或使用官方 formula（更新较慢）
brew install opencode

方式二: NPM

1	npm i -g opencode-ai@latest

方式三: 快速安装脚本

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

方式一: Chocolatey

1	choco install opencode

方式二: Scoop

1 2	scoop bucket add extras scoop install extras/opencode

方式三: NPM

1	npm i -g opencode-ai@latest

Arch Linux

1	paru -S opencode-bin

通用方式

# NPM/Bun/PNPM/Yarn
npm i -g opencode-ai@latest
# 或
bun add -g opencode-ai

# 快速安装脚本
curl -fsSL https://opencode.ai/install | bash

方式四: Mise（跨平台）

1	mise use -g opencode

方式五: Nix

1	nix run nixpkgs#opencode

客户端安装

macOS

1	brew install --cask opencode-desktop

下载页面

下载 OpenCode 客户端

进入OpenCode客户端

注意：客户端目前处于 Beta 测试阶段，Bug 较多，建议以命令行为主。

IDE 插件安装

VSCode

在 VSCode 插件市场搜索 OpenCode
安装 OpenCode for VSCode 插件

OpenCode_for_VScode

快捷键:

Windows: Ctrl + Shift + P
macOS: Cmd + Shift + P

vscode打开opencode命令面板

OpenCode for VSCode

https://marketplace.visualstudio.com/items?itemName=anomalyco.opencode-vscode

启动 OpenCode

安装完成后，在项目目录下运行:

opencode

这将启动 OpenCode 的交互式终端界面（TUI）。

进入OpenCode命令行界面

免费模型配置

查看可用模型

在 OpenCode 中输入以下命令查看免费模型:

/models

opencode选择模型

Antigravity 插件（Google Gemini 3 Pro，Claude Opus 4.5）

OpenCode Antigravity Auth

https://github.com/NoeFabris/opencode-antigravity-auth

Antigravity 是 Google 推出的 AI 编程 IDE，内置免费的 Gemini 3 Pro 和 Claude Opus 4.5 模型。通过该插件，可以免费使用这两个顶级的编程模型。

安装方式:

在 OpenCode 中发送以下命令，将自动安装:

Install the opencode-antigravity-auth plugin and add the Antigravity model definitions to ~/.config/opencode/opencode.json by following: https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/dev/README.md

安装opencode-antigravity-auth插件

认证步骤:

打开新的命令行窗口
执行认证命令:

1	opencode auth login

在浏览器中登录 Google 账号

Antigravity登录认证

验证成功后，重启 OpenCode
输入 /models 切换到 Google 模型

切换到Google模型

P.S. Antigravity 提供的模型需要通过 Google 账号认证，使用时注意网络环境。

接入 ChatGPT CodeX

前提条件: 需要订阅 ChatGPT Plus 或更高级别会员

配置步骤:

在 OpenCode CLI 中输入 /connect
选择 OpenAI
选择 ChatGPT Pro/Plus
在浏览器打开认证链接
登录并完成认证
在 OpenCode 中输入 /models 后，可以选择 ChatGPT 的编程模型

OpenRouter 集成

P.S. 输入 /connect 可以查到市面上几乎所有的模型供应商

配置步骤:

在 OpenCode 中输入 /connect
选择 Other 中的 openrouter
访问 OpenRouter 官网: https://openrouter.ai/
获取 API Key
填写 API Key 后，即可连接到几乎所有模型供应商

功能亮点

Session 管理

概念: 每次与 AI 开启的新对话就是一个全新的 Session，可以在后台运行，支持多个 Session 并行执行。

Session 相关命令:

命令	功能
`/session`	显示 Session 列表，查看运行状态，切换 Session
`/new`	创建全新的 Session

Session 管理功能:

后台运行多个任务
并行执行不同的 Session
查看 Session 的实时状态
在 Session 之间快速切换

SDK 文档

https://opencode.ai/docs/sdk.mdx

功能: 将当前 Session 的对话以 URL 链接的形式分享为在线网页

使用方法:

/share

P.S. 分享链接可以直接在浏览器中查看完整的对话记录，方便团队协作和代码审查。

Timeline 时间线回退

功能: 查看当前 Session 的完整对话记录，并可以将代码和内容回退到任意一次对话之前的状态。

使用方法:

/timeline

操作步骤:

输入 /timeline 查看时间线
选择任意一次对话记录
选择 Revert 选项
代码和内容将回退到该对话之前的状态

e.g. 假设在实现功能过程中发现方向错误，可以使用 Timeline 快速回退到之前的正确状态，避免手动撤销多个步骤。

Skills 与 MCP 配置

Skills 机制

目录结构:

项目目录/
├── .claude/
│   └── skills/
│       ├── skill-name1/
│       │   └── SKILL.md
│       └── skill-name2/
│           └── SKILL.md

Claude Code 到 OpenCode 的迁移:

只需要将 .claude 目录替换为 .opencode 目录。OpenCode 兼容 Claude Code 的 Skills 格式，不修改也可以直接使用。

MCP 服务器配置

配置文件位置: ~/.config/opencode/opencode.json

配置示例:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

实际案例 - Shadcn MCP:

查看配置代码

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-antigravity-auth@latest"
  ],
  "mcp": {
    "shadcn": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "shadcn@latest",
        "mcp"
      ],
      "enabled": true
    }
  }
}

配置示例:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true,
      "headers": {
        "CONTEXT7_API_KEY": "ctx7sk-df4f046b-125d-4083-a908-764d55da99fd"
      }
    }
  }
}

Context7 说明: Context7 是一个基于 MCP 的工具，为大型语言模型和 AI 代码编辑器提供最新、版本特定的官方文档和代码示例，帮助减少过时信息和生成错误代码的问题。

验证 MCP 配置

配置完成后:

退出 OpenCode: /exit
重新启动: opencode
查看 MCP 服务器: /mcp

opencode配置mcps

OMO 插件（Oh My OpenCode）

Oh-My-OpenCode

https://github.com/code-yeongyu/oh-my-opencode

Oh My OpenCode 是 OpenCode 最热门的编程插件，本质上是预设 Tools + 预设 MCP + 预设 Agent 的捆绑包。

预设功能

预设 Tools

LSP 高级版: 通过编程语言的语法和定义，帮助 AI 快速定位理解代码
AST: 抽象语法树分析
Look At: 查看和分析文件内容
Delegate-Task: Agent 任务分配
Background-Task: Agent 后台调度

预设 MCP

Web Search: 网络搜索
Context7: 官方文档查询
Grep App: 代码搜索

预设智能体

插件内置了 7 大编程智能体，每个智能体分配了最适合的 AI 模型:

智能体名称	职责	说明
Sisyphus	主智能体	规划和调度任务
Oracle	架构师	架构设计、代码评审
Librarian	图书管理员	查找文档、代码示例
Explore	探索者	代码库分析、模式发现
Frontend UI/UX Engineer	前端工程师	UI/UX 设计和实现
Document Writer	文档编写者	技术文档编写
Multimodal Looker	多模态观察者	图片、PDF 等媒体分析

安装 OMO 插件

安装命令:

在 OpenCode 中发送:

1	Install and configure by following the instructions here https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/README.md

配置步骤:

根据提示确认是否拥有 Claude、GPT、Gemini 的订阅
等待安装完成
配置文件位置: ~/.config/opencode/oh-my-opencode.json

OMO 插件使用方法

方法一: 智能体选择

输入 @ 符号
挑选其中一个智能体进行工作

方法二: Ultra Work（ulw）

魔法词: ulw

输入 ulw 后，OMO 插件将调用一切潜能:

综合调度各个领域最强的模型
主智能体 Sisyphus 将任务分配给其他智能体
后台同时开启多个任务，并行执行
将问题做成 Todo List，实时跟踪进度

e.g. 输入 ulw 实现一个完整的用户认证系统，插件将自动:

调用 Oracle 设计架构
调用 Explore 分析现有代码
调用 Frontend Engineer 实现 UI
调用 Document Writer 编写文档
所有任务并行执行

方法三: Ralph Loop

命令:

1	/ralph-loop

拉尔夫循环模式: 强制 AI 长时间循环，对非常复杂的任务进行持续工作，直到任务完成。

P.S. 可以连续运行数小时，适合处理大型重构、复杂 bug 修复等需要长期专注的任务。

云端环境

GitHub 集成

OpenCode 支持在 GitHub 的 Issue 中通过 /opencode 命令调用 AI 进行工作。

主要功能:

在 GitHub 云端解释问题
自动修复问题
创建 Pull Request

安装步骤

1	opencode github install

创建工作流文件 .github/workflows/opencode.yml:

name: opencode

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  opencode:
    if: |
      contains(github.event.comment.body, '/oc') ||
      contains(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 1
          persist-credentials: false
      - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514

选择模型供应商（仅支持 API Key）
将 .github/workflows/opencode.yml 提交到 GitHub 公开仓库
在 GitHub 设置页面的 Actions 中添加模型供应商的 API Key

使用方法

在 GitHub Issue 或 PR 中添加评论
输入 /opencode 或 /oc 加上具体指令
e.g. /opencode 修复这个 bug: [详细描述]
Actions 开始执行，在 Actions 页面查看进度
执行完成后，可以在 Pull Requests 中看到代码变更
审查后点击 Merge pull request 合并代码

高级功能

项目初始化（/init）

功能: 让 AI 通读整个项目文件夹，将学到的知识生成到 AGENTS.md 文件中。

作用: 类似 Claude Code 的 CLAUDE.md，该文件作为整个项目的系统提示词，帮助 AI 快速了解项目结构、技术栈和业务逻辑。

使用方法:

/init

P.S. 建议在新项目加入时或项目结构发生重大变化时执行，保持 AGENTS.md 的准确性。

上下文压缩（/compact）

功能: 压缩当前对话的上下文，提炼关键信息。

使用场景:

对话过长，接近 token 限制
需要保留关键信息，丢弃无关细节

使用方法:

/compact

自定义命令

配置目录: ~/.config/opencode/commands

创建方法:

在 commands 目录中创建 markdown 文件，e.g. test.md:

---
description: Run unit tests with coverage
agent: run_test
model: anthropic/claude-haiku-4-5
---

Run the full test suite with coverage report.
Focus on the failing tests and suggest fixes.

使用方法:

在 OpenCode 中通过 /${command_name} 运行:

/test

查看配置文件方式

也可以在 ~/.config/opencode/opencode.json 中配置:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the test suite with coverage. Show failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "review": {
      "template": "Review the changes in this PR: $ARGUMENTS\nFocus on code quality, potential bugs, and adherence to project conventions.",
      "description": "Review a pull request",
      "agent": "code-reviewer"
    }
  }
}

自定义智能体

配置目录: ~/.config/opencode/agents

创建方法:

在 agents 目录中创建 markdown 文件，e.g. code_review.md:

---
description: Reviews code for best practices and potential issues
mode: subagent
model: anthropic/claude-sonnet-4-20250514
---

You are a code reviewer. Focus on:
- Security vulnerabilities
- Performance issues
- Code maintainability
- Best practices adherence
- Potential bugs

Agent 类型:

类型	说明	调用方式
primary	主智能体	通过 Tab 键切换
subagent	子智能体	由主智能体后台调用

查看配置文件方式

在 ~/.config/opencode/opencode.json 中配置:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-5",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

使用方法:

主智能体: 在 OpenCode 中按 Tab 键切换
子智能体: 由主智能体自动调度，后台运行

最佳实践

项目管理

初始化项目: 使用 /init 生成 AGENTS.md，让 AI 了解项目
使用 Todo List: 复杂任务使用 ulw 或手动创建 Todo List，跟踪进度
利用 Timeline: 实验性功能开发时使用 Timeline，方便回退
Session 管理: 不同功能使用不同 Session，保持上下文清晰

插件使用

安装 OMO 插件: 优先安装 Oh My OpenCode，获得完整功能
配置 MCP: 根据项目需求配置必要的 MCP 服务器
使用合适模型:
- 简单任务: 使用 Haiku（快速便宜）
- 复杂任务: 使用 Sonnet（平衡性能）
- 代码生成: 使用 Claude Sonnet/GPT-4
- 文档编写: 使用 GPT-4/Claude Opus

效率提升

自定义命令: 将重复性操作定义为自定义命令，e.g. /test 运行测试
智能体分工: 使用 OMO 的 7 大智能体，让每个 AI 发挥专长
并行执行: 使用 ulw 或 background_task 并行处理多个任务
上下文管理: 及时使用 /compact 压缩对话，节省 token

团队协作

Share 分享: 使用 /share 分享对话，团队成员可以查看完整过程
GitHub 集成: 配置云端环境，在 Issue 中直接调用 AI 修复 bug
统一配置: 将 .opencode 目录纳入版本控制，统一团队配置

常见问题

Q1: OpenCode 与 Claude Code 有什么区别?

特性	OpenCode	Claude Code
开源性	完全开源	闭源
模型支持	不限模型	仅支持 Claude
插件系统	丰富插件	有限
免费模型	支持 Gemini、Antigravity 等	仅 Claude
跨平台	完整支持 macOS/Windows/Linux	限制较多

Q2: 如何选择合适的模型?

简单任务（代码解释、小修改）:

Claude Haiku 4.5（快速、便宜）

常规开发（功能实现、代码重构）:

Claude Sonnet 4（平衡性能）

复杂任务（架构设计、文档编写）:

Claude Opus 4.5 / GPT-4（最强性能）

特定领域:

前端开发: GPT-4o
后端开发: Claude Sonnet 4
安全审计: Claude Opus 4.5

Q3: MCP 配置后无法使用?

检查步骤:

配置文件格式是否正确
enabled 字段是否为 true
Local MCP 的命令是否可执行
Remote MCP 的 URL 是否正确
API Key 是否有效
退出并重启 OpenCode: /exit → opencode
查看 MCP 列表: /mcp

Q4: OMO 插件安装失败?

解决方案:

检查网络连接（需要访问 GitHub）
确认有足够权限修改配置文件
手动下载配置文件: https://github.com/code-yeongyu/oh-my-opencode
检查 ~/.config/opencode/oh-my-opencode.json 是否生成

Q5: 如何减少 API 成本?

方法:

使用免费模型: Antigravity（Gemini 3 Pro，Claude Opus 4.5）
简单任务使用 Haiku 模型
及时压缩上下文: /compact
使用自定义命令减少重复对话
开启缓存，避免重复请求

Q6: GitHub Actions 执行失败?

常见原因:

API Key 未配置或已过期
Workflow 文件路径错误（应为 .github/workflows/opencode.yml）
模型名称错误（使用 /models 查看）
权限不足（需要 id-token: write）

调试步骤:

查看 GitHub Actions 日志
确认 Secrets 中的 API Key
测试模型连接: 在本地使用相同配置
检查 Workflow 语法: 使用 GitHub Actions linter

Q7: Session 切换后上下文丢失?

说明: 每个 Session 是独立的，切换 Session 不会共享上下文。

解决方案:

使用 /share 分享重要对话
将关键信息写入文件或注释
使用 Todo List 记录跨 Session 的任务
将项目知识写入 AGENTS.md

参考资料

官方文档

OpenCode 官网

https://opencode.ai/

GitHub 仓库

https://github.com/anomalyco/opencode

CLI 文档

https://opencode.ai/docs/cli

TUI 文档

https://opencode.ai/docs/tui

MCP 文档

https://opencode.ai/docs/mcp-servers

GitHub 集成

https://opencode.ai/docs/github

SDK 文档

https://opencode.ai/docs/sdk

插件与工具

Oh-My-OpenCode

https://github.com/code-yeongyu/oh-my-opencode

OpenCode Antigravity Auth

https://github.com/NoeFabris/opencode-antigravity-auth

Context7 OpenRouter

社区资源

Discord 社区 Twitter

OpenCode for VSCode

https://marketplace.visualstudio.com/items?itemName=sst-dev.opencode

概述

安装配置

CLI 安装

客户端安装

macOS

下载页面

IDE 插件安装

VSCode

启动 OpenCode

免费模型配置

查看可用模型

Antigravity 插件（Google Gemini 3 Pro，Claude Opus 4.5）

接入 ChatGPT CodeX

OpenRouter 集成

功能亮点

Session 管理

Share 分享

Timeline 时间线回退

Skills 与 MCP 配置

Skills 机制

MCP 服务器配置

验证 MCP 配置

OMO 插件（Oh My OpenCode）

预设功能

预设 Tools

预设 MCP

预设智能体

安装 OMO 插件

OMO 插件使用方法

方法一: 智能体选择

方法二: Ultra Work（ulw）

方法三: Ralph Loop

云端环境

GitHub 集成

安装步骤

使用方法

高级功能

项目初始化（/init）

上下文压缩（/compact）

自定义命令

自定义智能体

最佳实践

项目管理

插件使用

效率提升

团队协作

常见问题

Q1: OpenCode 与 Claude Code 有什么区别?

Q2: 如何选择合适的模型?

Q3: MCP 配置后无法使用?

Q4: OMO 插件安装失败?

Q5: 如何减少 API 成本?

Q6: GitHub Actions 执行失败?

Q7: Session 切换后上下文丢失?

参考资料

官方文档

插件与工具

社区资源

相关工具