大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



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

---

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

---

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

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

---

方式一：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 键在两种模式间切换：

---

内置工具

常用 Slash 命令

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

---

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

主流提供商

云服务提供商

本地/自建模型

网关/代理

自定义提供商

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

---

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

1. 在 OpenCode TUI 中输入 /models 查看所有可用模型
2. 输入 /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" 

} }

常用配置项

---

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（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 和 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%opencodeoh-my-opencode.json
   • macOS/Linux: ~/.config/opencode/oh-my-opencode.json

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

,

"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 模型。

---

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

核心 Agent

规划 Agent

编排 Agent

Category 任务类别

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

---

内置 Skills（技能）

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

内置 Commands（斜杠命令）

内置 MCP 集成

---

什么是 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

---

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 的最新版本编写。具体功能可能随版本更新有所变化，建议参考 官方文档 获取最新信息。