OpenCode + oh-my-opencode Leitfaden für bewährte Praktiken

Dieser Kurs richtet sich an Entwickler, die Erfahrung im Umgang mit KI-Programmierassistenten haben, konzentriert sich auf die reale Welt und basiert auf der neuesten offiziellen Dokumentation (2026-04).

I. Was ist OpenCode?

OpenCode ist ein quelloffener KI-Programmieragent, der im Terminal läuft und mehr als 75 Modelle wie Claude, GPT, Gemini usw. unterstützt und drei Formen von TUI/IDE-Plugins/Desktop-Anwendungen bietet.

Größter Unterschied zu Claude Code:Keine Modellsperre, vollständig quelloffen, Agentensystem ist stark erweiterbar.

II. die Installation und Konfiguration

# 方式一：官方安装脚本（推荐）
curl -fsSL <https://opencode.ai/install> | bash

# 方式二：Homebrew（最新版本）
brew install anomalyco/tap/opencode

# 方式三：Node.js
npm install -g opencode-ai

Konfigurieren Sie den API-Schlüssel:

export ANTHROPIC_API_KEY="sk-ant-..."
# 或在 TUI 里运行 /connect，按提示授权

OpenCode Core Concepts: Das Agentensystem

Dies ist der Schlüssel zum Verständnis von OpenCode, im Gegensatz zum Einzelagentenmodell von Claude Code.

3.1 Zwei Arten von Agenten

Es gibt zwei Arten von Agenten in OpenCode:

HauptvertreterDie Person, mit der Sie direkt sprechen, mit Tab Taste, um zwischen ihnen zu wechseln.

UntervertreterDer Master-Agent plant automatisch, oder Sie können manuell @mention Spezialisierte Assistenten für Anrufe.

Die Installation von oh-my-opencode erweitert sowohl den Hauptagenten als auch die Unteragenten erheblich, siehe Abschnitt V.

3.2 @ Die beiden Verwendungen von

@ ist das wichtigste Eingabesymbol in der TUI und hat zwei völlig unterschiedliche Verwendungszwecke:

① Referenzen(Fuzzy-Suche)

这段鉴权逻辑有没有问题？@src/middleware/auth.ts

Löst eine unscharfe Dateisuche aus, wobei der Inhalt der Datei bei Auswahl automatisch in den Kontext eingefügt wird.

② @Erwähnung Subagent(Direktanruf)

@explore 找出所有调用了 sendEmail 的地方
@general 帮我并行处理这三个模块的文档生成

Der Hauptagent kann auch automatisch @Unteragenten benennen, die während der Ausführung spezielle Aufgaben übernehmen.

Beide können in derselben Nachricht gemischt werden:

@explore 分析 @src/api/ 目录下所有接口的结构

3.3 Tab Taste: Hauptagent wechseln

Tab alle eintippenHauptvertreter Rotation zwischen.Shift+Tab Rückwärts schalten.

Tab          # 切换主 Agent（Build → Plan → 自定义 Agent → ...）
Shift+Tab    # 反向切换

⚠️ Häufiges Missverständnis: Die Registerkarte ist kein ”Wechsel zwischen Planungs- und Baumodus”, sondern ein Wechsel zwischen zwei separaten Master-Agenten.

Der Plan Agent ist im Wesentlichen ein eingeschränkter Agent, der ”standardmäßig eine manuelle Bestätigung für das Schreiben von Dateien und Bash-Befehlen erfordert”.

Typische Verwendung:

# 先切到 Plan Agent 规划，只提方案不改代码
Tab  →  描述需求，拿到方案后审查

# 方案确认后切回 Build Agent 执行
Tab  →  好，按计划执行。

3.4 Tastenkombinationen

Die Taste Leader ist standardmäßig auf Ctrl+XIm Folgenden finden Sie ein Beispiel für die Art von Daten, die in der Datei tui.json Geändert in.

IV. gemeinsame Operationen der TUI

4.1 Initialisierung des Projekts

cd /path/to/project
opencode

Läuft innerhalb der TUI:

/init

Analysieren Sie die Projektstruktur und erzeugen Sie im Stammverzeichnis AGENTS.md——Vergewissern Sie sich, dass Sie in GitDies ist der Projektspeicher des Agenten.

4.2 Ausführen von Shell-Befehlen

Die Botschaft wurde in Form von ! beginnt mit einem Shell-Befehl, der direkt ausgeführt wird, und die Ausgabe wird als Ergebnis des Werkzeugs in den Kontext injiziert:

!git log --oneline -20
!npm test -- --coverage
!cat package.json

4.3 Rückgängig/Wiederherstellen

/undo    # 撤销最近一次修改（含文件变更），可多次执行
/redo    # 重新应用已撤销的修改

Verlassen Sie sich auf Git, um Dateiänderungen zu verwalten.Das Projekt muss ein Git-Repository sein。

4.4 Verwaltung des Kontextes

/compact    # 压缩当前会话，保留关键上下文，释放 token（alias: /summarize）
/new        # 开启新会话（alias: /clear）
/sessions   # 查看并切换历史会话（alias: /resume）

4.5 Andere gängige Befehle

/share      # 生成会话分享链接（复制到剪贴板）
/unshare    # 取消分享
/export     # 导出会话为 Markdown，用外部编辑器打开
/thinking   # 切换是否显示 Extended Thinking 内容
/models     # 列出可用模型
/themes     # 切换主题

V. AGENTS.md und benutzerdefinierte Erweiterungen

5.1 Drei Positionen für den Einstieg in den Beruf

OpenCode ist auch kompatibel mit Claude Codes CLAUDE.md Format (sofort einsatzbereit für die Migration).

5.2 Was in AGENTS.md zu schreiben ist

# 项目名称

## 技术栈
- 后端：Java 21 + Spring Boot 3.x
- 数据库：PostgreSQL（ORM 用 jOOQ，禁止使用 Hibernate）
- API 风格：RESTful，响应统一用 Result<T> 包装

## 构建与测试
- 构建：`mvn clean package`
- 单元测试：`mvn test`
- 集成测试：`mvn verify -P integration`

## 代码规范
- 所有 public 方法必须有 Javadoc
- 禁止在循环内执行数据库查询
- 异常统一通过 GlobalExceptionHandler 处理

## 架构说明
- 请求链路：Controller → Service → Repository → DB
- 跨模块只能通过 service 层调用，不能跨层调用 repository

5.3 Anpassen des Agenten

在 .opencode/agents/ 或 ~/.config/opencode/agents/ einrichten. .md Dokumentation:

---
description: 安全审计，检查代码安全漏洞
mode: subagent
model: anthropic/claude-opus-4-6
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

你是一名安全专家，专注以下方面的代码审计：
- SQL 注入、XSS、CSRF 漏洞
- 不安全的反序列化
- 硬编码的密钥或密码
- 权限校验缺失

只提供分析报告，不直接修改代码。

Der Dateiname ist der Agentenname (z. B. security-auditor.md → @security-auditor），mode: subagent eine Eigenschaft bezeichnen, die verwendet werden kann von @mention Anrufen.

5.4 Benutzerdefinierte Befehle

在 .opencode/commands/ 或 ~/.config/opencode/commands/ Erstellen Sie eine Befehlsdatei:

---
description: Code Review，重点关注安全和性能
agent: build
---

请对以下代码进行 Code Review，重点关注：
1. 安全漏洞（注入、权限、加密）
2. 性能问题（N+1 查询、内存泄漏）
3. 边界条件和异常处理
4. 命名和可读性

文件：$ARGUMENTS

Verwendung:/code-review src/api/OrderController.java

Kommando-Unterstützung $ARGUMENTS(alle Parameter) oder $1、$2(Positionsparameter), der im Frontmatter angegeben werden kann. agent、model。

VI. oh-my-opencode: OpenCode in ein Entwicklungsteam verwandeln

oh-my-opencode (jetzt umbenannt in oh-my-openagentDer npm-Paketname ist immer noch oh-my-opencode) ist das stärkste verfügbare OpenCode-Plugin.

Kernkompetenzen: 11 spezialisierte Agenten + parallele Unteragenten + ulw Vollautomatisch mit einem Klick + LSP/AST-Grep-Tool + automatische Kontextverwaltung.

6.1 Einbau

bunx oh-my-opencode install

Überprüfen Sie die Installation:

cat ~/.config/opencode/opencode.json
# plugins 数组中应包含 "oh-my-opencode"

6.2 ulw: eines der wichtigsten Wörter

ulw(kurz für Ultrawork) ist das zentrale Schlüsselwort von oh-my-opencode.

Das Stichwort muss nur Folgendes enthalten ulw 或 ultraworkDas Plug-in löst automatisch den ”stärksten Modus” aus:

• - Selbstexploration der Codebasis und Untersuchung von Implementierungsmustern
• - Planung mehrerer Fachagenten parallel dazu verfahrenJob
• - Kontinuierliche Ausführung bis zum Abschluss, ohne Unterbrechung, um auf eine Bestätigung zu warten.
• - Ergebnisse der automatisierten Diagnosevalidierung

Die Nutzung ist minimal:

ulw 给 /api/orders 接口增加分页功能，参考 /api/products 的实现方式

ulw 找出所有 N+1 查询问题并修复

ulw 将整个项目的错误处理统一改为 Result 模式

ulw 重构 src/payment/ 为策略模式，现有支付方式三种，对外接口不变

FormelWenn Sie vor einer großen Aufgabe stehen und nicht wissen, wo Sie anfangen sollen, gehen Sie direkt zu ulwlassen Sie das System seine eigenen Entscheidungen treffen.

Andere Arten der Auslösung von Schlüsselwörtern:

6.3 11 Freiberufliche Vermittler

Nach der Installation wird dieTab Taste, um zwischen diesen Master-Agenten (nach Priorität) zu wechseln:

Hauptagent (Registerkarte Schalter):

Unterbevollmächtigter (@Anruf nennen):

Die meisten Szenarien erfordern keine manuelle Agentenauswahl.ulw Sie wird automatisch eingeplant.

6.4 /start-work: Arbeitsablauf der funktionalen Entwicklung im großen Maßstab

Für große Funktionen, die modulübergreifend sind und Architekturentscheidungen beinhalten. Der Prozess ist wie folgt:

Schritt 1: Reiter zu Prometheus, Anforderungen beschreiben

Prometheus fragt wie ein echter Ingenieur nach Details. Nach der Antwort:

好，生成计划。

Die Plandatei wird im Verzeichnis .sisyphus/plans/*.mdIm Folgenden finden Sie ein Beispiel für die Art von Arbeit, die mit Hilfe der Software erledigt werden kann.

Schritt 2: Bestätigen Sie den Plan und führen Sie

/start-work

Atlas-Übernahme, automatische Ausführung nach Zeitplan, automatische Wiederaufnahme auch bei Unterbrechung der Verbindung (Status vorhanden) boulder.json）。

⚠️ Prometheus und Atlas müssen gepaart werden.Wechseln Sie nicht direkt zur Atlas-Ausführung.

Wann ist ulw und wann ist /start-work zu verwenden?

VII. typische Szenarien in der Praxis

Szenario 1: Schnelles Verstehen einer unbekannten Codebasis

@explore 找出所有 API 入口点，列出路由和对应的 Handler

ulw 分析这个项目的整体架构，重点是请求的完整链路，
输出一份给新人的 onboarding 文档

Szenario 2: Entwicklung einer neuen Funktion

Kleine Funktionen (1-2 Dateien): Direct Build Agent

在 @src/user/UserService.java 增加手机号登录方法，
参考邮箱登录 @src/user/EmailLoginStrategy.java

Mittlere Funktion (Mehrfachverknüpfung von Dateien): Planen → Bauen

Tab（切换到 Plan Agent）

给删除订单功能加软删除：deleted_at 标记删除时间，
新增回收站页面支持恢复和彻底删除

（审查方案）

Tab（切回 Build Agent）
好，按计划执行。

Große Funktionen (modulübergreifend): ulw oder /start-work

ulw 实现完整的优惠券系统：
固定金额/百分比两种折扣，限制使用次数和有效期，与购物车集成

Szenario 3: Codeüberprüfung (keine Codeänderungen)

@explore 全量扫描 src/api/ 目录，找出所有没有做权限校验的接口

@oracle 对 @src/payment/PaymentService.java 做架构审查，
重点：并发安全、幂等性、异常边界

Szenario 4: Fehlersuche bei komplexen Fehlern

ulw 追踪这个 NPE 的根本原因，从堆栈顶部到数据来源全链路分析，
找到根因后给出修复方案。堆栈：

java.lang.NullPointerException
    at com.example.OrderService.process(OrderService.java:142)
    ...

Szenario 5: Umfassende Umstrukturierung

ulw 将 src/payment/ 模块重构为策略模式，
现有支付方式：支付宝、微信、信用卡，
要求：对外接口不变，所有现有测试继续通过

Szenario 6: Wiederherstellung der Benutzeroberfläche (Design-Entwurf)

Ziehen Sie den Screenshot auf das Terminal und legen Sie ihn dort ab:

@multimodal-looker 分析这张设计稿的布局和样式
按照图中的设计实现 @src/components/Dashboard.tsx

Szenario 7: Generierung von Dokumenten

ulw 为 src/api/ 下所有公开接口生成 OpenAPI 3.0 规范，
输出到 docs/openapi.yaml，参考 @docs/openapi-sample.yaml 的格式

VIII. die Kurzanleitung zur Konfiguration

8.1 opencode.json

{
  "$schema": "<https://opencode.ai/config.json>",
  "model": "anthropic/claude-opus-4-6",
  "autoshare": false,
  "plugins": ["oh-my-opencode"]
}

8.2 oh-my-opencode Agent Konfiguration

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

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6"
    },
    "oracle": {
      "thinking": {
        "type": "enabled",
        "budgetTokens": 200000
      }
    },
    "explore": {
      "textVerbosity": "low"
    }
  }
}

8.3 Eingebaute Fertigkeiten (oh-my-opencode)

Passen Sie den Skill-Pfad an:

.opencode/skills/my-skill/SKILL.md
~/.config/opencode/skills/my-skill/SKILL.md

IX. häufig gestellte Fragen

Q:@ Zitieren von Dokumenten und @mention Wie unterscheidet sich ein Agent?

Von beiden geteilt @ Symbole, differenzierte Logik: eingeben @ Wenn die Übereinstimmung ein Pfad zu einer Datei ist, wird der Inhalt der Datei injiziert; wenn die Eingabe ein registrierter Agentenname ist (z. B. @explore), wird der Aufruf des untergeordneten Agenten ausgelöst.

Q:Tab Umschalten zwischen Agent und Ctrl+T Worin besteht der Unterschied zwischen den Varianten des Schaltmodells?

Tab Modi oder Datenströme wechselnHauptvertreter(Rollenwechsel, zusammen mit dem Wechsel des exklusiven Modells und der Werkzeugberechtigungen des Agenten);Ctrl+T Schalten Sie den aktuellen AgentModellvariante(z. B. Standard- vs. Extended Thinking-Version desselben Modells).

F: Was ist der Unterschied zwischen ulw und einer direkten Beschreibung der Anforderungen?

Bei direkter Beschreibung wird Sisyphus in einem einzigen Thread ausgeführt und kann anhalten und nachfragen, wenn er auf Unsicherheit stößt. hinzufügen ulw Vollautomatischer Parallelmodus nach dem Auslösen: Mehrere Unteragenten arbeiten gleichzeitig, erkunden die Codebasis eigenständig, warten nicht auf eine Bestätigung in der Mitte des Prozesses und validieren weiter, bis sie vollständig fertig sind.

F: Was soll ich tun, wenn /start-work unterbrochen wird?

erneut ausführen. /start-workSystem von boulder.json Wiederaufnahme des Fortschritts und Fortführung unerledigter Aufgaben.

F: Was ist, wenn der Kontext fast voll ist?

in Bewegung sein /compact Durch die Komprimierung der aktuellen Sitzung bleiben kritische Kontexte erhalten. Große Aufgaben werden priorisiert mit /start-work Workflows, Unterbeauftragte verteilen kontextbezogenen Druck.

bibliographie

• - Offizielle OpenCode-Dokumentation
• - OpenCode Agents Dokumentation
• - OpenCode Keybinds Dokumentation
• - oh-my-opencode GitHub
• - awesome-opencode Plugin-Sammlung