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 对话来完成编码、调试、重构等开发任务。特性说明开源代码完全公开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 上最稳定的使用方式是通过WSLWindows Subsystem for Linux。# 1. 确保已安装 WSLPowerShell 管理员模式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 KeyOpenCode 支持多种 AI 提供商最简单的方式是设置环境变量# Anthropic ClaudeexportANTHROPIC_API_KEYyour-key-here# OpenAIexportOPENAI_API_KEYyour-key-here# Google GeminiexportGEMINI_API_KEYyour-key-hereWindows PowerShell$env:ANTHROPIC_API_KEY your-key-here也可以在 OpenCode TUI 中使用/connect命令交互式配置。2. 启动 OpenCode# 进入你的项目目录cdD:\my-project# 启动opencode3. 开始对话启动后你会看到 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命令。如需清空当前对话可以开启新会话或使用CtrlC中断后重新输入。五、支持的模型提供商OpenCode 通过 AI SDK 和 Models.dev 支持75 LLM 提供商以下是主要分类主流提供商提供商说明AnthropicClaude 系列Sonnet、Opus、HaikuOpenAIGPT 系列GPT-5、GPT-4o、o3 等GoogleGemini 系列GitHub Copilot使用 Copilot 订阅部分模型需 ProGitLab DuoClaude 为基础的模型Haiku、Sonnet、OpusDeepSeekDeepSeek Reasoner 等xAIGrok 系列Mistral AIMistral 系列模型MiniMaxM2 系列Moonshot AIKimi K2Groq高速推理模型Cerebras超高速推理Qwen 3 Coder 480B 等OpenRouter多模型聚合网关Together AI开源模型聚合Fireworks AI开源模型Hugging Face开放模型支持 17 推理提供商Z.AIGLM 系列智谱302.AI国内聚合 API云服务提供商提供商说明Amazon BedrockAWS 托管模型Azure OpenAI微软 Azure 托管 OpenAIAzure Cognitive Services微软认知服务Google Vertex AIGoogle Cloud 模型Cloudflare AI GatewayCloudflare 统一网关Cloudflare Workers AI边缘推理Scaleway欧洲云提供商OVHcloud AI Endpoints法国云提供商Nebius Token Factory云推理本地/自建模型提供商说明Ollama本地运行开源模型Ollama Cloud云端 OllamaLM Studio本地模型 GUI APIllama.cppllama-server 本地推理网关/代理提供商说明OpenCode ZenOpenCode 官方推荐模型集合OpenCode GoOpenCode 低成本订阅计划HeliconeLLM 可观测性 网关Vercel AI GatewayVercel 网关Cloudflare AI GatewayCloudflare 网关ZenMux多模型路由Baseten模型部署平台Firmware模型推理平台Cortecs模型推理IO.NET去中心化推理网络Deep Infra开源模型推理LLM Gateway通用网关SAP AI CoreSAP AI 平台STACKIT德国云 AI自定义提供商任何兼容 OpenAI API 格式的提供商都可以通过自定义配置接入。六、切换模型提供商与套餐方式一TUI 内切换推荐在 OpenCode TUI 中输入/models查看所有可用模型输入/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 KeyOpenCode Go低成本订阅计划适合预算有限的用户禁用/启用特定提供商{$schema:https://opencode.ai/config.json,disabled_providers:[openai,gemini],enabled_providers:[anthropic,github-copilot]}七、配置文件详解OpenCode 的配置文件为opencode.json按以下优先级加载远程配置.well-known/opencode全局配置~/.config/opencode/opencode.json项目配置项目根目录下的opencode.json.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/denymcpServersMCP 服务器配置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-OpenCodeOh-My-OpenCodeOMO是一个为 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-cirm bun.sh/install.ps1|iex安装步骤方式一使用 LLM Agent 自动安装官方推荐Oh-My-OpenCode 官方推荐使用一个 LLM Agent 来帮你完成安装和配置。复制以下提示词粘贴到你的 LLM AgentClaude 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.mdAgent 会自动读取安装指南并完成所有配置包括模型选择、API Key 设置等。这是最省心的方式。方式二手动交互式安装# 交互式安装推荐bunx oh-my-opencodeinstall# 或非交互式安装bunx oh-my-opencodeinstall--no-tui--claudeyes--openaino--geminino安装过程中会提示你选择拥有的 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 的配置文件位置按优先级项目配置.opencode/oh-my-opencode.json用户配置Windows:%APPDATA%\opencode\oh-my-opencode.jsonmacOS/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每个都针对特定场景优化。核心 AgentAgent用途触发场景Sisyphus主编排者负责任务分解和委派复杂多步任务Hephaestus深度执行 Worker端到端执行任务需要完整实现的场景Oracle架构决策、代码审查、调试复杂架构、2 次修复失败后Librarian外部资源搜索文档、GitHub、Web不熟悉的库/APIExplore代码库内搜索上下文感知的 grep查找现有代码模式规划 AgentAgent用途Prometheus战略规划创建详细工作计划Metis计划顾问识别隐藏意图和歧义Momus计划审查验证计划的清晰度和完整性编排 AgentAgent用途AtlasTodo 列表编排系统化执行计划任务Sisyphus-Junior类别执行器不能再次委派Multimodal-Looker视觉内容专家分析 PDF、图片、图表Category 任务类别通过task(category...)调用每个类别使用不同的优化模型类别默认模型适用场景visual-engineeringgemini-3.1-pro前端、UI/UX、设计、动画ultrabraingpt-5.4 (xhigh)深度逻辑推理deepgpt-5.4 (medium)自主问题解决quickgpt-5.4-mini简单修改、拼写错误unspecified-highclaude-opus-4-7复杂通用任务writinggemini-3-flash文档、技术写作十二、Skills 与 Commands内置 Skills技能Skills 是领域专业知识包通过skill(name...)加载Skill触发条件说明git-mastercommit、rebase、squashGit 专家原子提交、变基策略playwright浏览器任务Playwright MCP 浏览器自动化dev-browser状态化浏览持久化页面的浏览器自动化frontend-ui-uxUI/UX 任务设计师兼开发者角色review-work“review work”、“QA”5 个并行子 Agent 的代码审查ai-slop-remover“remove AI slop”清除 AI 生成的代码异味内置 Commands斜杠命令命令说明/init-deep初始化分层 AGENTS.md 知识库/ralph-loop自引用开发循环直到完成/ulw-loopUltrawork 循环持续执行直到完成/cancel-ralph取消活跃的 Ralph Loop/refactor智能重构LSP AST-grep TDD/start-work从 Prometheus 计划启动工作会话/stop-continuation停止所有续传机制/handoff创建上下文摘要以便新会话继续内置 MCP 集成MCP功能websearchExa AI 网络搜索context7库文档查询grep_appGitHub 代码搜索十三、实战用 ultrawork 完成一个任务什么是 ultraworkultrawork简称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 会自动Sisyphus分析任务拆分为 4 个子任务Explore并行搜索现有的认证实现和错误处理模式Librarian搜索 JWT 安全最佳实践Sisyphus-Junior们并行实现各个模块Oracle审查最终实现全部完成后交付结果日常使用技巧# 简单任务 - 直接说 帮我修复 auth.ts 的类型错误 # 复杂任务 - 加 ultrawork ultrawork 重构整个用户模块拆分为 service/controller/model 三层 # 需要外部知识 ultrawork 查找 Stripe API 最新的订阅管理方式并实现 # 代码审查 /review-work十四、常见问题 FAQQ: Windows 上必须用 WSL 吗A: 不是必须但强烈推荐。WSL 提供更好的文件系统性能和完整的终端支持。直接用 npm 安装也能运行但某些高级功能如 LSP在 WSL 下更稳定。Q: 需要哪些 API KeyA: 至少需要一个 AI 提供商的 API Key。推荐 Anthropic ClaudeSisyphus 默认使用也可以用 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 OpusLibrarian 用 Gemini FlashOracle 用 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_KEYAnthropic API KeyOPENAI_API_KEYOpenAI API KeyGEMINI_API_KEYGoogle Gemini API KeyGITHUB_TOKENGitHub Copilot TokenLOCAL_ENDPOINT自托管模型端点OPENCODE_CONFIG自定义配置文件路径OPENCODE_SERVER_PASSWORD服务器访问密码附录键盘快捷键快捷键功能Tab切换 Build/Plan 模式CtrlC中断当前操作CtrlK清空输入Esc取消/返回提示本教程基于 OpenCode 和 Oh-My-OpenCode 的最新版本编写。具体功能可能随版本更新有所变化建议参考 官方文档 获取最新信息。