OpenCode + Oh-My-OpenCode 学习笔记

xjtuer2162026-04-28 11:48

OpenCode + Oh-My-OpenCode 学习笔记

一份从零开始的完整教程：安装、配置、入门使用，以及 Oh-My-OpenCode 插件的多 Agent 编排能力。

目录

  • [一、OpenCode 是什么](#一、OpenCode 是什么 "#%E4%B8%80opencode-%E6%98%AF%E4%BB%80%E4%B9%88")
  • [二、Windows 上安装 OpenCode](#二、Windows 上安装 OpenCode "#%E4%BA%8Cwindows-%E4%B8%8A%E5%AE%89%E8%A3%85-opencode")
  • 三、快速上手
  • 四、核心功能一览
  • 五、支持的模型提供商
  • 六、切换模型提供商与套餐
  • 七、配置文件详解
  • [八、AGENTS.md 项目规则文件](#八、AGENTS.md 项目规则文件 "#%E5%85%ABagentsmd-%E9%A1%B9%E7%9B%AE%E8%A7%84%E5%88%99%E6%96%87%E4%BB%B6")
  • [九、Oh-My-OpenCode 插件](#九、Oh-My-OpenCode 插件 "#%E4%B9%9DOh-My-OpenCode-%E6%8F%92%E4%BB%B6")
  • [十、Oh-My-OpenCode 安装](#十、Oh-My-OpenCode 安装 "#%E5%8D%81Oh-My-OpenCode-%E5%AE%89%E8%A3%85")
  • [十一、Agent 系统详解](#十一、Agent 系统详解 "#%E5%8D%81%E4%B8%80agent-%E7%B3%BB%E7%BB%9F%E8%AF%A6%E8%A7%A3")
  • [十二、Skills 与 Commands](#十二、Skills 与 Commands "#%E5%8D%81%E4%BA%8Cskills-%E4%B8%8E-commands")
  • [十三、实战：用 ultrawork 完成一个任务](#十三、实战：用 ultrawork 完成一个任务 "#%E5%8D%81%E4%B8%89%E5%AE%9E%E6%88%98%E7%94%A8-ultrawork-%E5%AE%8C%E6%88%90%E4%B8%80%E4%B8%AA%E4%BB%BB%E5%8A%A1")
  • [十四、常见问题 FAQ](#十四、常见问题 FAQ "#%E5%8D%81%E5%9B%9B%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98-faq")

一、OpenCode 是什么

OpenCode 是一个开源的终端 AI 编程助手，直接在终端里与 AI 对话来完成编码、调试、重构等开发任务。

特性 说明
开源 代码完全公开，GitHub: anomalyco/opencode
终端 TUI 基于 Bubble Tea 构建的流畅终端界面
多模型支持 支持 75+ LLM 提供商（OpenAI、Anthropic、Google、GitHub Copilot 等）
内置工具 文件读写、命令执行、代码搜索、LSP 诊断、网页搜索等
多会话 支持保存和管理多个对话会话
MCP 扩展 支持 Model Context Protocol，可扩展外部工具
类 Vim 编辑 内置 Vim 模式的文本编辑能力

官方文档 : opencode.ai/docs

二、Windows 上安装 OpenCode

方式一：WSL 推荐

Windows 上最稳定的使用方式是通过 WSL（Windows Subsystem for Linux） 。

bash 复制代码 
# 1. 确保已安装 WSL（PowerShell 管理员模式）
wsl --install
​
# 2. 进入 WSL 终端
wsl
​
# 3. 一键安装 OpenCode
curl -fsSL https://opencode.ai/install | bash

安装完成后，在 WSL 中访问 Windows 文件：

bash 复制代码 
cd /mnt/c/Users/你的用户名/项目路径
opencode

方式二：npm 直接安装

复制代码 
npm install -g opencode-ai

方式三：包管理器

bash 复制代码 
# Chocolatey
choco install opencode
​
# Scoop
scoop install opencode

方式四：其他包管理

csharp 复制代码 
# Bun
bun install -g opencode-ai
​
# pnpm
pnpm install -g opencode-ai
​
# Yarn
yarn global add opencode-ai

验证安装

css 复制代码 
opencode --version

三、快速上手

1. 配置 API Key

OpenCode 支持多种 AI 提供商，最简单的方式是设置环境变量：

ini 复制代码 
# Anthropic Claude
export ANTHROPIC_API_KEY=your-key-here
​
# OpenAI
export OPENAI_API_KEY=your-key-here
​
# Google Gemini
export GEMINI_API_KEY=your-key-here

Windows PowerShell：

ini 复制代码 
$env:ANTHROPIC_API_KEY = "your-key-here"

也可以在 OpenCode TUI 中使用 /connect 命令交互式配置。

2. 启动 OpenCode

bash 复制代码 
# 进入你的项目目录
cd D:\my-project

# 启动
opencode

3. 开始对话

启动后你会看到 TUI 界面，直接输入问题即可：

shell 复制代码 
> 帮我看看这个项目的结构
> 给 src/utils.ts 添加一个防抖函数
> 修复 index.ts 第 42 行的类型错误

4. 切换模式

按 Tab 键在两种模式间切换：

模式 说明
Build 完整工具访问权限，可以编辑文件、执行命令
Plan 仅分析和规划，不做任何修改

四、核心功能一览

内置工具

工具 功能
glob 按文件名模式搜索
grep 按内容搜索
read 读取文件内容
write 写入文件
edit 精确替换编辑文件
bash 执行终端命令
webfetch 抓取网页内容
websearch 网络搜索（Exa 集成）
lsp_diagnostics 语言服务器诊断
lsp_goto_definition 跳转到定义
lsp_find_references 查找引用
task 启动子 Agent 执行任务

常用 Slash 命令

命令 功能
/connect 配置 AI 提供商
/init 初始化项目，生成 AGENTS.md
/help 查看帮助

注意 ：OpenCode 中没有 /clear 命令。如需清空当前对话，可以开启新会话或使用 Ctrl+C 中断后重新输入。

五、支持的模型提供商

OpenCode 通过 AI SDK 和 Models.dev 支持 75+ LLM 提供商，以下是主要分类：

主流提供商

提供商 说明
Anthropic Claude 系列（Sonnet、Opus、Haiku）
OpenAI GPT 系列（GPT-5、GPT-4o、o3 等）
Google Gemini 系列
GitHub Copilot 使用 Copilot 订阅（部分模型需 Pro+）
GitLab Duo Claude 为基础的模型（Haiku、Sonnet、Opus）
DeepSeek DeepSeek Reasoner 等
xAI Grok 系列
Mistral AI Mistral 系列模型
MiniMax M2 系列
Moonshot AI Kimi K2
Groq 高速推理模型
Cerebras 超高速推理（Qwen 3 Coder 480B 等）
OpenRouter 多模型聚合网关
Together AI 开源模型聚合
Fireworks AI 开源模型
Hugging Face 开放模型，支持 17+ 推理提供商
Z.AI GLM 系列（智谱）
302.AI 国内聚合 API

云服务提供商

提供商 说明
Amazon Bedrock AWS 托管模型
Azure OpenAI 微软 Azure 托管 OpenAI
Azure Cognitive Services 微软认知服务
Google Vertex AI Google Cloud 模型
Cloudflare AI Gateway Cloudflare 统一网关
Cloudflare Workers AI 边缘推理
Scaleway 欧洲云提供商
OVHcloud AI Endpoints 法国云提供商
Nebius Token Factory 云推理

本地/自建模型

提供商 说明
Ollama 本地运行开源模型
Ollama Cloud 云端 Ollama
LM Studio 本地模型 GUI + API
llama.cpp llama-server 本地推理

网关/代理

提供商 说明
OpenCode Zen OpenCode 官方推荐模型集合
OpenCode Go OpenCode 低成本订阅计划
Helicone LLM 可观测性 + 网关
Vercel AI Gateway Vercel 网关
Cloudflare AI Gateway Cloudflare 网关
ZenMux 多模型路由
Baseten 模型部署平台
Firmware 模型推理平台
Cortecs 模型推理
IO.NET 去中心化推理网络
Deep Infra 开源模型推理
LLM Gateway 通用网关
SAP AI Core SAP AI 平台
STACKIT 德国云 AI

自定义提供商

任何兼容 OpenAI API 格式的提供商都可以通过自定义配置接入。

六、切换模型提供商与套餐

方式一：TUI 内切换（推荐）

  1. 在 OpenCode TUI 中输入 /models 查看所有可用模型
  2. 输入 /model <provider>/<model> 切换到指定模型
bash 复制代码 
/models          # 查看可用模型列表
/model anthropic/claude-sonnet-4-5    # 切换到 Claude Sonnet
/model openai/gpt-5                   # 切换到 GPT-5

方式二：配置文件切换

在 opencode.json 中设置默认模型：

bash 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}
  • model：默认使用的主模型
  • small_model：用于轻量任务（如生成会话标题），节省成本

方式三：命令行启动时指定

bash 复制代码 
opencode --model anthropic/claude-sonnet-4-5
# 或简写
opencode -m openai/gpt-5

切换提供商套餐

一些提供商支持多种认证方式或套餐：

  • Anthropic ：支持 API Key 或 Claude Pro/Max 订阅认证（通过 /connect 选择认证方式）
  • GitHub Copilot：免费订阅可用，部分模型需 Pro+ 订阅
  • OpenCode Zen ：官方推荐，通过 /connect → OpenCode Zen 注册并获取 API Key
  • OpenCode Go：低成本订阅计划，适合预算有限的用户

禁用/启用特定提供商

bash 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"],
  "enabled_providers": ["anthropic", "github-copilot"]
}

七、配置文件详解

OpenCode 的配置文件为 opencode.json，按以下优先级加载：

  1. 远程配置（.well-known/opencode）
  2. 全局配置：~/.config/opencode/opencode.json
  3. 项目配置：项目根目录下的 opencode.json
  4. .opencode 目录下的 agents、commands、plugins

基础配置示例

bash 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxx"
    }
  },
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

常用配置项

配置项 说明
model 默认使用的模型
providers 各 AI 提供商的 API Key 和配置
permission 编辑和命令执行的权限策略（ask/allow/deny）
mcpServers MCP 服务器配置
lsp 语言服务器配置
agents 自定义 Agent 配置

八、AGENTS.md 项目规则文件

AGENTS.md 是项目级别的 AI 行为指令文件，类似于 Cursor 的 Rules。

创建方式

在 OpenCode TUI 中输入：

bash 复制代码 
/init

会自动扫描项目并生成 AGENTS.md。

手动编写示例

markdown 复制代码 
# 项目规则

## 技术栈
- TypeScript + React + Vite
- Tailwind CSS 样式
- Vitest 测试框架

## 代码规范
- 使用函数式组件
- 所有组件必须有 TypeScript 类型定义
- 遵循 ESLint 规则

## 构建命令
- `npm run dev` - 开发服务器
- `npm run build` - 生产构建
- `npm test` - 运行测试

最佳实践

  • 提交到 Git：让团队成员共享规则
  • 保持简洁：只写关键规则
  • 包含内容：构建命令、架构说明、编码规范

九、Oh-My-OpenCode 插件

什么是 Oh-My-OpenCode？

Oh-My-OpenCode（OMO） 是一个为 OpenCode 打造的 全功能多 Agent 编排插件。它把 OpenCode 从"单个 AI 聊天机器人"变成"一个 AI 开发团队"。

核心能力：

  • 自动将任务拆分并分配给多个专业 Agent
  • 并行执行多个子任务
  • 内置 11 个专业 Agent，覆盖规划、编码、审查、搜索等场景
  • 兼容 Claude Code 的 hooks、commands、skills、MCPs
  • 开箱即用，安装后无需额外配置

GitHub : github.com/code-yeongy...

为什么需要 Oh-My-OpenCode？

场景 原生 OpenCode + Oh-My-OpenCode
简单问答 直接回答 直接回答
单文件修改 手动编辑 自动委派 Agent
多模块重构 需要手动分步 自动拆分、并行执行
查找外部文档 需要手动搜索 自动调用 Librarian Agent
代码审查 需要手动要求 自动启动 5 个并行审查 Agent

十、Oh-My-OpenCode 安装

前置条件

确保已安装 OpenCode 和 Bun（或 npm）：

bash 复制代码 
# 安装 Bun（如果还没有）
powershell -c "irm bun.sh/install.ps1|iex"

安装步骤

方式一：使用 LLM Agent 自动安装（官方推荐）

Oh-My-OpenCode 官方推荐使用一个 LLM Agent 来帮你完成安装和配置。复制以下提示词粘贴到你的 LLM Agent（Claude Code、Cursor 等）会话中：

perl 复制代码 
Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

Agent 会自动读取安装指南并完成所有配置，包括模型选择、API Key 设置等。这是最省心的方式。

方式二：手动交互式安装

ini 复制代码 
# 交互式安装（推荐）
bunx oh-my-opencode install

# 或非交互式安装
bunx oh-my-opencode install --no-tui --claude=yes --openai=no --gemini=no

安装过程中会提示你选择拥有的 AI 订阅/服务（Claude Pro/Max、OpenAI/ChatGPT、Gemini 等），根据你实际拥有的订阅进行选择。

验证安装

perl 复制代码 
bunx oh-my-opencode doctor

初始化 Agent 模型配置

安装完成后，必须初始化各个 Agent 的模型配置，否则 Agent 系统无法正常工作。

方式一：使用 /init-deep 命令（推荐）

在 OpenCode TUI 中直接运行：

bash 复制代码 
/init-deep

这会自动生成分层 AGENTS.md 文件，并初始化 Agent 配置。

方式二：手动编辑配置文件

Oh-My-OpenCode 的配置文件位置（按优先级）：

  1. 项目配置：.opencode/oh-my-opencode.json

  2. 用户配置：

    • Windows: %APPDATA%\opencode\oh-my-opencode.json
    • macOS/Linux: ~/.config/opencode/oh-my-opencode.json

配置文件使用 JSONC 格式（支持注释和尾逗号）：

kotlin 复制代码 
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",

  // 自定义 Agent 模型
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-7"
    },
    "oracle": {
      "model": "openai/gpt-5.4",
      "variant": "high"
    },
    "librarian": {
      "model": "google/gemini-3-flash"
    }
  },

  // 自定义任务类别模型
  "categories": {
    "visual-engineering": {
      "model": "google/gemini-3.1-pro",
      "variant": "high"
    },
    "quick": {
      "model": "openai/gpt-5-nano"
    }
  }
}

注意：如果没有 Claude 订阅，Sisyphus Agent 可能无法正常工作。官方强烈建议至少拥有 Claude Pro/Max 订阅。如果只有 OpenAI/ChatGPT 订阅，需要在配置中手动指定 Sisyphus 使用 OpenAI 模型。

十一、Agent 系统详解

Oh-My-OpenCode 提供了 11 个专业 Agent，每个都针对特定场景优化。

核心 Agent

Agent 用途 触发场景
Sisyphus 主编排者，负责任务分解和委派 复杂多步任务
Hephaestus 深度执行 Worker，端到端执行任务 需要完整实现的场景
Oracle 架构决策、代码审查、调试 复杂架构、2+ 次修复失败后
Librarian 外部资源搜索（文档、GitHub、Web） 不熟悉的库/API
Explore 代码库内搜索（上下文感知的 grep） 查找现有代码模式

规划 Agent

Agent 用途
Prometheus 战略规划，创建详细工作计划
Metis 计划顾问，识别隐藏意图和歧义
Momus 计划审查，验证计划的清晰度和完整性

编排 Agent

Agent 用途
Atlas Todo 列表编排，系统化执行计划任务
Sisyphus-Junior 类别执行器，不能再次委派
Multimodal-Looker 视觉内容专家，分析 PDF、图片、图表

Category 任务类别

通过 task(category="...") 调用，每个类别使用不同的优化模型：

类别 默认模型 适用场景
visual-engineering gemini-3.1-pro 前端、UI/UX、设计、动画
ultrabrain gpt-5.4 (xhigh) 深度逻辑推理
deep gpt-5.4 (medium) 自主问题解决
quick gpt-5.4-mini 简单修改、拼写错误
unspecified-high claude-opus-4-7 复杂通用任务
writing gemini-3-flash 文档、技术写作

十二、Skills 与 Commands

内置 Skills（技能）

Skills 是领域专业知识包，通过 skill(name="...") 加载：

Skill 触发条件 说明
git-master commit、rebase、squash Git 专家，原子提交、变基策略
playwright 浏览器任务 Playwright MCP 浏览器自动化
dev-browser 状态化浏览 持久化页面的浏览器自动化
frontend-ui-ux UI/UX 任务 设计师兼开发者角色
review-work "review work"、"QA" 5 个并行子 Agent 的代码审查
ai-slop-remover "remove AI slop" 清除 AI 生成的代码异味

内置 Commands（斜杠命令）

命令 说明
/init-deep 初始化分层 AGENTS.md 知识库
/ralph-loop 自引用开发循环直到完成
/ulw-loop Ultrawork 循环，持续执行直到完成
/cancel-ralph 取消活跃的 Ralph Loop
/refactor 智能重构（LSP + AST-grep + TDD）
/start-work 从 Prometheus 计划启动工作会话
/stop-continuation 停止所有续传机制
/handoff 创建上下文摘要以便新会话继续

内置 MCP 集成

MCP 功能
websearch Exa AI 网络搜索
context7 库文档查询
grep_app GitHub 代码搜索

十三、实战：用 ultrawork 完成一个任务

什么是 ultrawork？

ultrawork（简称 ulw）是 Oh-My-OpenCode 的 魔法关键词。当你的提示中包含这个词时：

  • 所有 Agent 自动激活
  • 后台任务并行启动
  • 深度探索自动执行
  • 系统不会停止，直到任务 100% 完成

实战示例

场景：为一个 Express.js 项目添加 JWT 认证

markdown 复制代码 
ultrawork 帮我为这个 Express 项目添加 JWT 认证，
包括登录、注册、token 刷新中间件。
要求：
1. 使用 httpOnly cookie 存储 token
2. 实现 refresh token 轮换
3. 遵循项目现有的错误处理模式
4. 添加单元测试

Oh-My-OpenCode 会自动：

  1. Sisyphus 分析任务，拆分为 4 个子任务
  2. Explore 并行搜索现有的认证实现和错误处理模式
  3. Librarian 搜索 JWT 安全最佳实践
  4. Sisyphus-Junior 们并行实现各个模块
  5. Oracle 审查最终实现
  6. 全部完成后交付结果

日常使用技巧

bash 复制代码 
# 简单任务 - 直接说
帮我修复 auth.ts 的类型错误

# 复杂任务 - 加 ultrawork
ultrawork 重构整个用户模块，拆分为 service/controller/model 三层

# 需要外部知识
ultrawork 查找 Stripe API 最新的订阅管理方式并实现

# 代码审查
/review-work

十四、常见问题 FAQ

Q: Windows 上必须用 WSL 吗？

A : 不是必须，但 强烈推荐。WSL 提供更好的文件系统性能和完整的终端支持。直接用 npm 安装也能运行，但某些高级功能（如 LSP）在 WSL 下更稳定。

Q: 需要哪些 API Key？

A: 至少需要一个 AI 提供商的 API Key。推荐 Anthropic Claude（Sisyphus 默认使用），也可以用 OpenAI GPT 系列。Oh-My-OpenCode 的某些 Agent 可以使用不同模型，按需配置。

Q: 如何切换模型？

A : 在 opencode.json 中修改 model 字段，或在 TUI 中使用 /model 命令。

Q: Oh-My-OpenCode 收费吗？

A: Oh-My-OpenCode 本身是开源免费的。但使用的 AI 模型（如 Claude、GPT）需要各自的 API Key，按模型提供商的定价计费。

Q: 可以同时使用多个模型吗？

A : 可以。Oh-My-OpenCode 的不同 Agent 可以配置不同的模型。例如 Sisyphus 用 Claude Opus，Librarian 用 Gemini Flash，Oracle 用 GPT-5。在 oh-my-opencode.json 的 agents 配置中分别指定即可。

Q: 如何自定义 Agent 行为？

A : 通过 .opencode/oh-my-opencode.json 配置文件，可以覆盖每个 Agent 的模型、权限、提示词等。也可以编写自定义 Skills 来扩展能力。

Q: 任务执行到一半失败了怎么办？

A : Oh-My-OpenCode 支持会话恢复。使用 session_id 可以继续之前的 Agent 会话，保留所有上下文。也可以用 /handoff 创建上下文摘要，在新会话中继续工作。

附录：常用环境变量

变量名 说明
ANTHROPIC_API_KEY Anthropic API Key
OPENAI_API_KEY OpenAI API Key
GEMINI_API_KEY Google Gemini API Key
GITHUB_TOKEN GitHub Copilot Token
LOCAL_ENDPOINT 自托管模型端点
OPENCODE_CONFIG 自定义配置文件路径
OPENCODE_SERVER_PASSWORD 服务器访问密码

附录：键盘快捷键

快捷键 功能
Tab 切换 Build/Plan 模式
Ctrl+C 中断当前操作
Ctrl+K 清空输入
Esc 取消/返回

提示 ：本教程基于 OpenCode 和 Oh-My-OpenCode 的最新版本编写。具体功能可能随版本更新有所变化，建议参考 官方文档 获取最新信息。

相关推荐
AI 编程助手GPT4 小时前
【深度】GPT-5.5 重新定义编程、Copilot 转向 Token 计费、大模型进入“雅尔塔时刻“——2026 年 4 月 28 日 AI 编程三大变局
人工智能·gpt·ai·chatgpt·copilot·ai编程·#程序员效率
DanCheOo5 小时前
我开源了一个工具，把 Cursor 37 个对话提取成 519 条结构化记忆——再也不用给 AI 重复解释背景了
aigc·ai编程·cursor
Sailing5 小时前
🚀🚀CLI 为什么在 2025 年突然复兴？看懂 Agent、Skill、MCP、CLI 四层架构
前端·agent·ai编程
Cyning5 小时前
2026-04-27 : Tech Graph — 自动渲染 + 跨仓契约 + CI 门禁
ai编程·cursor
C澒5 小时前
AI 生码 - API2CODE：接口智能匹配与 API 自动化生码实践
前端·低代码·ai编程
qq_454245036 小时前
视野的枷锁：为什么文件碎片化是AI编程的隐形天花板
人工智能·ai编程
向量引擎6 小时前
向量引擎×GPT Image 2×deepseek v4实战全解析：API调用、Key管理和高并发的新潮玩法！
gpt·aigc·api·ai编程·ai写作·key
好运的阿财6 小时前
OpenClaw工具拆解之browser+agents_list
前端·人工智能·机器学习·开源软件·ai编程·openclaw·openclaw工具
一念杂记6 小时前
零基础训练出懂你的AI助手——工作流、Skill、MCP服务
人工智能·ai编程
热门推荐
01GitHub 镜像站点02近期有什么ai的新消息，新动态？ 2026.4月032026年4月AI大事件深度解读：大模型竞争进入“深水区“042026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot05Codex 接入 DeepSeek API 完整配置文档062026年AI前瞻：量子AI、具身智能与科学发现的新纪元07在Windows 11上安装Docker的踩坑记录08零基础教你claude code 接入 deepseek V409DeepSeek V4 全面解析：测评、对比、案例及实操指南10codex app每次打开重连5次Reconnecting问题解决