跳到正文
← 博客

Oh My OpenCode 落地使用操作手册

· renmk

Oh My OpenCode 是一款为 OpenCode 提供增强功能的插件,赋予其类似 Claude Code 的 Agent 协调能力、异步子 Agent 执行、多模型编排等高级特性。本手册旨在帮助开发团队快速理解、安装、配置并落地使用 Oh My OpenCode,提升 AI 辅助编程效率。手册涵盖环境准备、安装部署、核心功能使用、多 Agent 配置、最佳实践及常见问题解答,适用于从零基础入门到团队规模化应用的全流程指导。

第一章 概述与前置准备

1.1 什么是 Oh My OpenCode

Oh My OpenCode 是一个 OpenCode 插件,旨在:

  • 提供多 Agent 编排与异步执行能力
  • 内置经过策划的 MCPs、工具和模型
  • 最大限度提升 OpenCode 的实际生产力
  • 与 Claude Code 保持兼容并扩展原能力

通过该插件,OpenCode 不再只是单一会话助手,而能同时驱动多个智能 Agent 与工具协同工作。

1.2 前置要求

在开始安装前,请确保满足以下条件:

要求项 说明
OpenCode 已安装 OpenCode(建议版本 1.0.150+)
Node.js/Bun 已安装 Node.js 或 Bun 运行环境
模型订阅 至少准备以下之一:Claude Pro/Max、ChatGPT Plus/Pro、Gemini 订阅
终端模拟器 推荐使用 WezTerm、Alacritty、Windows Terminal 等

1.3 检查 OpenCode 版本

Bash
opencode --version

确保输出版本号,建议使用较新版本。


第二章 安装与配置

2.1 安装 Oh My OpenCode

推荐方式 - 交互式安装:

Bash
bunx oh-my-opencode install

如果系统没有 bunx,可使用 npx:

Bash
npx oh-my-opencode install

非交互式安装(适合自动化脚本):

Bash
bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=yes --gemini=yes

参数说明:

  • --claude: 启用 Claude 支持
  • --chatgpt: 启用 ChatGPT 支持
  • --gemini: 启用 Gemini 支持

注意:Ubuntu/Debian 用户如果通过 Snap 安装 Bun,可能遇到 bunx: script not found 错误,建议使用 npx 或重新安装 Bun。

2.2 验证安装

检查配置文件是否已添加插件:

Bash
cat ~/.config/opencode/opencode.json

确认其中包含 oh-my-opencode 插件标识。

2.3 配置 Provider

方式一:交互式配置

Bash
opencode
# 在 OpenCode 中执行
/connect

按提示选择 Provider 并完成授权。

方式二:手动配置 API 密钥

编辑配置文件 ~/.config/opencode/opencode.json:

JSON
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

第三章 多 Agent 配置与使用

3.1 Agent 配置文件

Oh My OpenCode 的核心优势在于多 Agent 编排。配置文件位于:

Bash
~/.config/opencode/oh-my-opencode.json

3.2 完整 Agent 配置示例

JSON
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "Sisyphus": {
      "model": "axonhub-anthropic/claude-opus-4-5-20251101",
      "comment": "主协调者 - 使用最强的 Opus 4.5 模型"
    },
    "librarian": {
      "model": "axonhub-anthropic/claude-sonnet-4-5-20250929",
      "comment": "文档查找和代码库分析 - 使用 Sonnet 4.5"
    },
    "explore": {
      "model": "axonhub-anthropic/claude-haiku-4-5-20251001",
      "comment": "快速代码库探索 - 使用快速的 Haiku 4.5"
    },
    "oracle": {
      "model": "axonhub-anthropic/claude-opus-4-1-20250805",
      "comment": "架构设计和代码审查 - 使用 Opus 4.1"
    },
    "frontend-ui-ux-engineer": {
      "model": "axonhub-anthropic/claude-sonnet-4-5-20250929",
      "comment": "前端开发 - 使用 Sonnet 4.5"
    },
    "document-writer": {
      "model": "axonhub-anthropic/claude-3-7-sonnet-20250219",
      "comment": "技术文档撰写 - 使用 Sonnet 3.7"
    },
    "multimodal-looker": {
      "model": "axonhub-anthropic/claude-3-7-sonnet-20250219",
      "comment": "视觉内容分析 - 使用 Sonnet 3.7"
    }
  }
}

3.3 Agent 角色说明

Agent 名称 职责 推荐模型
Sisyphus 主协调者,负责任务分配和整体协调 Claude Opus 4.5
librarian 文档查找、代码库分析 Claude Sonnet 4.5
explore 快速代码库探索、文件搜索 Claude Haiku 4.5
oracle 架构设计、代码审查 Claude Opus 4.1
frontend-ui-ux-engineer 前端开发、UI/UX 实现 Claude Sonnet 4.5
document-writer 技术文档撰写 Claude Sonnet 3.7
multimodal-looker 视觉内容分析、图片理解 Claude Sonnet 3.7

第四章 核心功能使用

4.1 启动与基础操作

启动 OpenCode:

Bash
# 进入项目目录
cd /path/to/your/project

# 启动 OpenCode
opencode

基础操作:

操作 命令/快捷键 说明
发送消息 Enter 发送输入给 AI
换行输入 Shift+Enter / Ctrl+Enter 插入换行
引用文件 @文件名 模糊搜索并引用文件
执行命令 !命令 执行 Shell 命令

4.2 Plan 与 Build 模式

OpenCode 提供两种核心工作模式:

模式 说明 适用场景
Plan 只读模式,仅分析规划 代码审查、需求规划、方案设计
Build 完整操作权限,可修改文件 实际开发、编写代码、修复 bug

切换方式: 按 Tab 键切换模式

使用示例:

Bash
# Plan 模式 - 规划方案
实现一个用户删除功能,要求软删除,并提供恢复界面

# Build 模式 - 执行实现
按照刚才的计划开始实现

4.3 常用内置命令

命令 快捷键 功能
/connect - 连接/切换 LLM Provider
/init - 初始化项目,生成 AGENTS.md
/undo Ctrl+Z 撤销上一个操作
/redo Ctrl+Y 重做已撤销的操作
/models - 查看可用模型列表
/clear Ctrl+L 清空终端界面
/exit Ctrl+D 退出 OpenCode

4.4 项目初始化

首次使用新项目时,执行初始化:

Bash
opencode
# 在 OpenCode 中执行
/init

此命令会:

  • 自动分析项目结构
  • 生成 AGENTS.md 文件
  • 建议将 AGENTS.md 提交到 Git 仓库

第五章 高级配置

5.1 完整配置文件示例

JSON
{
  "$schema": "https://opencode.ai/config.json",
  
  "theme": "tokyonight",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  },
  
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  },
  
  "permission": {
    "edit": "allow",
    "bash": "ask"
  },
  
  "compaction": {
    "auto": true,
    "prune": true
  },
  
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md"
  ]
}

5.2 环境变量配置

使用环境变量保护敏感信息:

JSON
{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

5.3 本地模型配置(Ollama)

JSON
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        },
        "codellama": {
          "name": "Code Llama"
        }
      }
    }
  }
}

第六章 团队落地最佳实践

6.1 项目规范化

  1. 创建 AGENTS.md

    • 每个项目根目录包含 AGENTS.md
    • 描述项目架构、技术栈、编码规范
    • 提交到版本控制
  2. 统一配置管理

    • 团队共享基础配置文件
    • 使用环境变量管理个人密钥
    • 版本控制共享配置模板

6.2 Agent 分工策略

Plain Text
大型任务处理流程:
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Sisyphus  │───→│  librarian  │───→│   explore   │
│  (任务协调)  │    │ (代码分析)   │    │ (快速探索)   │
└─────────────┘    └─────────────┘    └─────────────┘
       │
       ↓
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   oracle    │    │ frontend-   │    │   document- │
│  (架构审查)  │    │ ui-ux-      │    │   writer    │
│             │    │  engineer   │    │  (文档生成)  │
└─────────────┘    │ (前端开发)   │    └─────────────┘
                   └─────────────┘

6.3 工作流建议

场景 推荐模式 Agent 操作步骤
新功能开发 Build Sisyphus + 专业 Agent Plan 规划 → Build 实现
代码审查 Plan oracle 只读分析,输出报告
Bug 修复 Build explore + Sisyphus 定位问题 → 修复验证
文档编写 Build document-writer 自动生成 + 人工审核
代码重构 Plan/Build oracle + librarian 分析影响 → 执行重构

6.4 安全与权限管理

JSON
{
  "permission": {
    "edit": "allow",
    "bash": "ask"
  }
}
  • edit: allow 允许 AI 编辑文件,ask 每次询问
  • bash: ask 执行命令前确认,allow 自动执行

第七章 常见问题与解决方案

7.1 安装问题

问题 解决方案
bunx: script not found 使用 npx 替代,或重新安装 Bun
安装后插件未生效 检查 ~/.config/opencode/opencode.json
Provider 连接失败 检查 API 密钥和网络连接

7.2 使用问题

问题 解决方案
Agent 未按预期工作 检查 oh-my-opencode.json 配置
模型响应慢 切换至轻量级模型(Haiku)
上下文过长 启用 compaction.auto: true
工具调用失败 检查本地模型上下文长度设置

7.3 性能优化

  1. 启用自动压缩

    JSON
    "compaction": {
      "auto": true,
      "prune": true
    }
  2. 合理选择模型

    • 简单任务:使用 Haiku 系列
    • 复杂任务:使用 Opus 系列
    • 日常开发:使用 Sonnet 系列
  3. 定期清理会话

    • 使用 /clear 清理界面
    • 长时间会话建议重启

第八章 附录

8.1 配置文件优先级

优先级 位置 说明
1 .well-known/opencode 远程组织配置
2 ~/.config/opencode/opencode.json 全局用户配置
3 OPENCODE_CONFIG 环境变量 自定义配置路径
4 项目根目录 opencode.json 项目专属配置
5 .opencode 目录 Agent、命令配置
6 OPENCODE_CONFIG_CONTENT 运行时临时配置

8.2 参考资源

8.3 快速参考卡

Bash
# 安装
bunx oh-my-opencode install

# 启动
opencode

# 连接 Provider
/connect

# 初始化项目
/init

# 切换 Plan/Build 模式
Tab

# 撤销/重做
/undo 或 Ctrl+Z
/redo 或 Ctrl+Y

# 引用文件
@文件名

# 执行命令
!命令