OpenCode + Oh-My-OpenCode 学习笔记

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

---

目录

• 一、OpenCode 是什么
• 二、Windows 上安装 OpenCode
• 三、快速上手
• 四、核心功能一览
• 五、支持的模型提供商
• 六、切换模型提供商与套餐
• 七、配置文件详解
• 八、AGENTS.md 项目规则文件
• 九、Oh-My-OpenCode 插件
• 十、Oh-My-OpenCode 安装
• 十一、Agent 系统详解
• 十二、Skills 与 Commands
• 十三、实战：用 ultrawork 完成一个任务
• 十四、常见问题 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 模式的文本编辑能力

官方文档: https://opencode.ai/docs

---

二、Windows 上安装 OpenCode

方式一：WSL 推荐

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

# 1. 确保已安装 WSL（PowerShell 管理员模式）
wsl --install

# 2. 进入 WSL 终端
wsl

# 3. 一键安装 OpenCode
curl -fsSL https://opencode.ai/install | bash

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

cd /mnt/c/Users/你的用户名/项目路径
opencode

方式二：npm 直接安装

npm install -g opencode-ai

方式三：包管理器

# Chocolatey
choco install opencode

# Scoop
scoop install opencode

方式四：其他包管理

# Bun
bun install -g opencode-ai

# pnpm
pnpm install -g opencode-ai

# Yarn
yarn global add opencode-ai

验证安装

opencode --version

---

三、快速上手

1. 配置 API Key

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

# 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：

$env:ANTHROPIC_API_KEY = "your-key-here"

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

2. 启动 OpenCode

# 进入你的项目目录
cd D:\my-project

# 启动
opencode

3. 开始对话

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

> 帮我看看这个项目的结构
> 给 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> 切换到指定模型

/models          # 查看可用模型列表
/model anthropic/claude-sonnet-4-5    # 切换到 Claude Sonnet
/model openai/gpt-5                   # 切换到 GPT-5

方式二：配置文件切换

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

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

• model：默认使用的主模型
• small_model：用于轻量任务（如生成会话标题），节省成本

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

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：低成本订阅计划，适合预算有限的用户

禁用/启用特定提供商

{
  "$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

基础配置示例

{
  "$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 中输入：

/init

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

手动编写示例

# 项目规则

## 技术栈
- 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: https://github.com/code-yeongyu/oh-my-openagent

为什么需要 Oh-My-OpenCode？

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

---

十、Oh-My-OpenCode 安装

前置条件

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

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

安装步骤

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

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

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 设置等。这是最省心的方式。

方式二：手动交互式安装

# 交互式安装（推荐）
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 等），根据你实际拥有的订阅进行选择。

验证安装

bunx oh-my-opencode doctor

初始化 Agent 模型配置

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

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

在 OpenCode TUI 中直接运行：

/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 格式（支持注释和尾逗号）：

{
  "$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 认证

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. 全部完成后交付结果

日常使用技巧

# 简单任务 - 直接说
帮我修复 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 的最新版本编写。具体功能可能随版本更新有所变化，建议参考 官方文档 获取最新信息。