OpenCode + Oh-My-OpenCode 学习笔记

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 对话来完成编码、调试、重构等开发任务。

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

二、Windows 上安装 OpenCode

方式一：WSL 推荐

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

# 1. 确保已安装 WSL（PowerShell 管理员模式）wsl--install# 2. 进入 WSL 终端wsl# 3. 一键安装 OpenCodecurl-fsSLhttps://opencode.ai/install|bash

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

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

方式二：npm 直接安装

npminstall-gopencode-ai

方式三：包管理器

# Chocolateychoco install opencode# Scoopscoop install opencode

方式四：其他包管理

# Bunbuninstall-gopencode-ai# pnpmpnpminstall-gopencode-ai# Yarnyarnglobaladdopencode-ai

验证安装

opencode--version

三、快速上手

1. 配置 API Key

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

# Anthropic ClaudeexportANTHROPIC_API_KEY=your-key-here# OpenAIexportOPENAI_API_KEY=your-key-here# Google GeminiexportGEMINI_API_KEY=your-key-here

Windows PowerShell：

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

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

2. 启动 OpenCode

# 进入你的项目目录cdD:\my-project# 启动opencode

3. 开始对话

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

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

4. 切换模式

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

四、核心功能一览

内置工具

常用 Slash 命令

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

五、支持的模型提供商

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

主流提供商

云服务提供商

本地/自建模型

网关/代理

自定义提供商

任何兼容 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--modelanthropic/claude-sonnet-4-5# 或简写opencode-mopenai/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"}}

常用配置项

八、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？

十、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-opencodeinstall# 或非交互式安装bunx oh-my-opencodeinstall--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

编排 Agent

Category 任务类别

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

十二、Skills 与 Commands

内置 Skills（技能）

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

内置 Commands（斜杠命令）

内置 MCP 集成

十三、实战：用 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创建上下文摘要，在新会话中继续工作。

附录：常用环境变量

附录：键盘快捷键

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