快速入门

本指南将帮助你在几分钟内安装并配置 Oh My OpenCode，体验多代理协作的力量。

前置条件

在开始之前，请确保你已经：

✅ 安装了 OpenCode
✅ 拥有以下订阅之一：
- Claude Max20 (推荐) - 最强大的多代理体验
- ChatGPT Plus/Pro - 良好的性能和成本平衡
- Gemini Advanced - 极高的性价比
✅ 配置了基本的 OpenCode 设置（API 密钥等）

安装步骤

方法 1：人类用户安装

如果你是人类用户，请按照以下步骤安装：

# 1. 克隆 Oh My OpenCode 仓库
git clone https://github.com/code-yeongyu/oh-my-opencode.git ~/.oh-my-opencode

# 2. 安装依赖
cd ~/.oh-my-opencode
npm install  # 或 yarn install / pnpm install

# 3. 运行安装脚本
npm run install

安装脚本将自动：

检测你的 OpenCode 配置文件位置
备份现有配置
将 Oh My OpenCode 配置合并到你的 OpenCode 设置中

方法 2：AI 代理安装

如果你正使用 AI 代理进行安装，代理可以直接使用：

# AI 代理直接运行安装脚本
opencode "使用 ultrawork 模式安装 oh-my-opencode"

AI 代理将自动处理：

下载与配置
依赖安装
配置文件合并

订阅计划配置

根据你的订阅服务选择配置：

Claude Max20 (推荐)

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3
  },
  "agents": {
    "oracle": { "enabled": true },
    "librarian": { "enabled": true },
    "frontend-engineer": { "enabled": true },
    "backend-engineer": { "enabled": true },
    "explore": { "enabled": true }
  }
}

特点:

最高并发任务数（3 个后台任务）
所有代理完全启用
最佳的多代理协作体验

ChatGPT Plus/Pro

{
  "subscription": "chatgpt-plus",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": { "enabled": true },
    "librarian": { "enabled": true },
    "frontend-engineer": { "enabled": true }
  }
}

特点:

中等并发任务数（2 个后台任务）
启用核心代理
良好的性能和成本平衡

Gemini Advanced

{
  "subscription": "gemini-advanced",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": { "enabled": false },
    "librarian": { "enabled": true },
    "explore": { "enabled": true }
  }
}

特点:

中等并发任务数（2 个后台任务）
启用精选代理
极高的性价比

验证安装

安装完成后，验证 Oh My OpenCode 是否工作正常：

1. 检查配置文件

# 查看 Oh My OpenCode 配置文件
cat .opencode/oh-my-opencode.json  # 项目级配置
# 或
cat ~/.config/opencode/oh-my-opencode.json  # 用户级配置 (macOS/Linux)
# 或
type %APPDATA%\opencode\oh-my-opencode.json  # 用户级配置 (Windows)

确认配置文件包含 Oh My OpenCode 相关的设置。

2. 测试基本功能

# 测试 Sisyphus 代理
opencode "使用 @oracle 分析当前项目的架构"

# 测试 ultrawork 模式
opencode "ulw: 列出项目中的所有配置文件"

3. 检查代理列表

# 查看所有可用代理
opencode "列出所有可用的专家代理"

你应该看到类似以下的输出：

可用代理:
- @oracle - 系统架构设计
- @librarian - 文档调研
- @frontend-engineer - 前端开发
- @backend-engineer - 后端开发
- @explore - 代码库分析

基本配置

启用 ultrawork 模式

在你的任务描述中添加 ultrawork 或 ulw 关键字：

opencode "ultrawork: 重构用户认证模块"

这将自动启用：

✅ 所有已配置的代理
✅ 后台任务并行化
✅ LSP 工具集成
✅ 智能上下文管理

自定义代理行为

编辑 OpenCode 配置文件以添加代理特定的设置：

{
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "prompt_append": "请提供详细的技术决策理由"
    }
  }
}

配置后台任务并发

控制同时运行的后台任务数量：

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  }
}

常见问题

安装失败

问题: 安装脚本报错或找不到 OpenCode 配置

解决:

确认 OpenCode 已正确安装：opencode --version

手动指定配置文件路径：

export OPENCODE_CONFIG_PATH=/path/to/your/config.json
npm run install

代理无响应

问题: 使用 @oracle 等代理时没有响应

解决:

检查代理是否已启用：
```
opencode "显示当前配置"
```
确认订阅计划支持该代理
检查 API 配额是否已耗尽

配置冲突

问题: Oh My OpenCode 配置与现有配置冲突

解决:

查看备份文件：
- 项目级：.opencode/oh-my-opencode.json.backup
- 用户级 (macOS/Linux)：~/.config/opencode/oh-my-opencode.json.backup

手动合并配置：

# 恢复备份（以项目级为例）
cp .opencode/oh-my-opencode.json.backup .opencode/oh-my-opencode.json

# 或恢复用户级备份 (macOS/Linux)
cp ~/.config/opencode/oh-my-opencode.json.backup ~/.config/opencode/oh-my-opencode.json

# 手动添加 Oh My OpenCode 配置
# 编辑配置文件，添加必要的 agents 和 sisyphus 部分

LSP 工具不起作用

问题: 代理无法使用悬停、跳转等 LSP 功能

解决:

确认项目已初始化 LSP 服务端：

# 对于 TypeScript 项目
npm install -D typescript

# 对于 Python 项目
pip install python-lsp-server

检查 LSP 配置：

{
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "go"]
  }
}

并发任务过多

问题: 过多的后台任务导致性能下降或 API 频率限制

解决: 减少并发任务数量：

{
  "sisyphus": {
    "max_concurrent_tasks": 1  // 减少到 1
  }
}

后续步骤

安装完成后，我们建议你：

📖 阅读 核心功能 了解所有功能
🎯 查看 最佳实践 学习高效使用技巧
⚙️ 探索 高级配置 进行深度定制
💡 参考 使用案例 获取灵感

获取帮助

遇到问题？

📖 查看 GitHub README
🐛 提交 Issue
💬 加入社区讨论

准备好体验多代理协作的力量了吗？尝试这条命令：

opencode "ultrawork: 分析当前项目并提供改进建议"