Guia de práticas recomendadas do OpenCode + oh-my-opencode

Destinado a desenvolvedores com experiência no uso de assistentes de programação de IA, com foco no mundo real e com base na documentação oficial mais recente (2026-04).

I. O que é OpenCode

O OpenCode é um agente de programação de IA de código aberto executado no terminal, compatível com mais de 75 modelos, como Claude, GPT, Gemini, etc., e que oferece três formas de plug-in TUI/IDE/aplicativo de desktop.

A maior diferença em relação ao Claude Code:Sem bloqueio de modelo, com código-fonte totalmente aberto, o sistema de agentes é profundamente extensível.

II. instalação e configuração

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

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

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

Configure a chave de API:

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

Conceitos básicos do OpenCode: o sistema de agentes

Essa é a chave para entender o OpenCode, em oposição ao modelo de agente único do Claude Code.

3.1 Dois tipos de agente

Há dois tipos de agentes no OpenCode:

Agente principalA pessoa com quem você está falando diretamente, com Tab para alternar entre elas.

SubagenteO Master Agent faz a programação automaticamente ou você pode fazer manualmente @mention Assistentes especializados para chamadas.

A instalação do oh-my-opencode expande significativamente o agente principal e os subagentes, consulte a Seção V.

3.2 @ Os dois usos de

@ é o símbolo de entrada mais importante na TUI e tem dois usos completamente diferentes:

① Referências(busca difusa)

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

Aciona uma pesquisa de arquivo difusa, com o conteúdo do arquivo automaticamente injetado no contexto quando selecionado.

② @menção Subagente(chamada direta)

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

O Master Agent também pode @mencionar automaticamente subagentes para realizar tarefas especializadas durante a execução.

Ambos podem ser misturados na mesma mensagem:

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

3.3 Tab Chave: Trocar o agente principal

Tab chave em todos osAgente principal Rotação entre.Shift+Tab Comutação reversa.

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

⚠️ Equívoco comum: o Tab não está ”alternando o modo Plan/Build”, ele está alternando entre dois Master Agents separados.

O Plan Agent é essencialmente um agente restrito que ”requer confirmação manual por padrão para gravações de arquivos e comandos bash”.

Uso típico:

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

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

3.4 Teclas de atalho

O padrão da tecla Leader é Ctrl+Xpode ser encontrado no tui.json Modificado em.

IV. operações comuns da UIS

4.1 Inicialização do projeto

cd /path/to/project
opencode

É executado dentro da TUI:

/init

Analisar a estrutura do projeto e gerar no diretório raiz AGENTS.md——Certifique-se de fazer o commit no GitEssa é a memória do projeto do agente.

4.2 Execução de comandos do shell

A mensagem foi entregue na forma de ! começa com um comando shell, que é executado diretamente, e a saída é injetada no contexto como resultado da ferramenta:

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

4.3 Desfazer/Refazer

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

Confiar no Git para gerenciar alterações de arquivos.O projeto deve ser um repositório Git。

4.4 Gerenciamento de contexto

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

4.5 Outros comandos comuns

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

V. AGENTS.md e extensões personalizadas

5.1 Três posições de entrada em vigor

O OpenCode também é compatível com o CLAUDE.md (pronto para uso na migração).

5.2 O que escrever no AGENTS.md

# 项目名称

## 技术栈
- 后端：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 Personalização do agente

在 .opencode/agents/ 或 ~/.config/opencode/agents/ estabelecer .md Documentação:

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

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

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

O nome do arquivo é o nome do agente (por exemplo security-auditor.md → @security-auditor），mode: subagent denotam uma propriedade que pode ser usada por @mention Chamada.

5.4 Comandos personalizados

在 .opencode/commands/ 或 ~/.config/opencode/commands/ Crie um arquivo de comando:

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

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

文件：$ARGUMENTS

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

Suporte de comando $ARGUMENTS(todos os parâmetros) ou $1、$2(parâmetro posicional), que pode ser especificado no frontmatter. agent、model。

VI. oh-my-opencode: Transformando o OpenCode em uma equipe de desenvolvimento

oh-my-opencode (agora renomeado oh-my-openagentO nome do pacote npm ainda é oh-my-opencode) é o plug-in OpenCode mais potente disponível.

Principais recursos: 11 agentes especializados + subagentes paralelos + ulw Totalmente automatizado com um clique + ferramenta LSP/AST-Grep + gerenciamento automático de contexto.

6.1 Instalação

bunx oh-my-opencode install

Verifique a instalação:

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

6.2 ulw: uma das palavras mais importantes

ulw(abreviação de ultrawork) é a palavra-chave principal do oh-my-opencode.

A palavra-chave só precisa conter ulw 或 ultraworkO plug-in aciona automaticamente o ”Modo mais forte”:

• - Auto-exploração da base de código e estudo dos padrões de implementação
• - Agendamento de vários agentes especializados proceder em paralelotrabalho
• - Execução contínua até a conclusão, sem parar para aguardar a confirmação.
• - Resultados automatizados de validação de diagnóstico

O uso é mínimo:

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

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

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

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

fórmulaQuando se deparar com uma tarefa grande e não souber por onde começar, vá direto para ulwDeixe o sistema tomar suas próprias decisões.

Outros modos de acionamento de palavras-chave:

6.3 11 Agentes profissionais

Após a instalação, oTab para alternar entre esses agentes mestres (por prioridade):

Agente principal (interruptor de guia):

Subagente (@mencionar chamada):

A maioria dos cenários não exige a seleção manual do agente.ulw Ele será agendado automaticamente.

6.4 /start-work: fluxo de trabalho de desenvolvimento funcional em larga escala

Para funções grandes que são de vários módulos e têm decisões arquitetônicas. O processo é o seguinte:

Etapa 1: Guia para o Prometheus, descreva os requisitos

A Prometheus pergunta detalhes como um verdadeiro engenheiro. Após a resposta:

好，生成计划。

O arquivo de plano é salvo na pasta .sisyphus/plans/*.mdA seguir, um exemplo do tipo de trabalho que pode ser feito com a ajuda do software.

Etapa 2: Confirmar o plano e executar

/start-work

Controle do Atlas, execução automática de acordo com a programação, retomada automática mesmo se desconectado (status presente) boulder.json）。

⚠️ Prometheus e Atlas devem ser emparelhados.Não mude diretamente para a execução do Atlas.

Quando usar o ulw e quando usar o /start-work?

VII Cenários típicos na prática

Cenário 1: Entenda rapidamente uma base de código desconhecida

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

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

Cenário 2: Desenvolvimento de novas funções

Pequenos recursos (1-2 arquivos): Direct Build Agent

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

Função média (vinculação de vários arquivos): Plan → Build

Tab（切换到 Plan Agent）

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

（审查方案）

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

Funções grandes (em todos os módulos): ulw ou /start-work

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

Cenário 3: revisão de código (sem alterações de código)

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

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

Cenário 4: depuração de bugs complexos

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

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

Cenário 5: Reconfiguração extensiva

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

Cenário 6: restauração da interface do usuário (rascunho do projeto)

Depois de arrastar e soltar a captura de tela no terminal:

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

Cenário 7: Geração de documentos

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

VIII. referência rápida de configuração

8.1 opencode.json

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

8.2 Configuração do agente oh-my-opencode

~/.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 Habilidades incorporadas (oh-my-opencode)

Personalize o caminho da habilidade:

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

IX Perguntas frequentes

Q:@ Citação de documentos e @mention Como um agente é diferenciado?

Compartilhado por ambos @ Símbolos, lógica diferenciada: enter @ Se a correspondência for um caminho para um arquivo, o conteúdo do arquivo será injetado; se a entrada for um nome de agente registrado (por exemplo @explore), então a chamada do agente filho é acionada.

Q:Tab Alternar entre Agente e Ctrl+T Qual é a diferença entre as variantes de modelos de comutação?

Tab alternar modos ou fluxos de dadosAgente principal(Troca de função, juntamente com a troca do modelo exclusivo do agente e das permissões da ferramenta);Ctrl+T Trocar ovariante do modelo(por exemplo, a versão Standard vs. Extended Thinking do mesmo modelo).

P: Qual é a diferença entre ulw e uma descrição direta dos requisitos?

Quando descrito diretamente, o Sisyphus é executado em um único thread e pode parar e perguntar quando encontrar incertezas. Adicionar ulw Modo paralelo totalmente automatizado pós-disparo: vários subagentes trabalham simultaneamente, exploram a base de código por conta própria, não esperam por confirmação no meio do processo e continuam a validar até que estejam completamente concluídos.

P: O que devo fazer se o /start-work for interrompido?

reexecução /start-workSistema de boulder.json Retomar o progresso e continuar as tarefas não concluídas.

P: E se o contexto estiver quase cheio?

estar em movimento /compact Ao compactar a sessão atual, o contexto crítico é preservado. As tarefas grandes são priorizadas usando /start-work Fluxos de trabalho, subagentes distribuem pressão contextual.

bibliografia

• - Documentação oficial do OpenCode
• - Documentação do OpenCode Agents
• - Documentação do OpenCode Keybinds
• - oh-my-opencode GitHub
• - coleção de plug-ins awesome-opencode