opencode 起手式

opencode 是一个TUI终端开发工具，它是Claude code开源版

当前 opencode 还有以下特点

• 优秀的中文教程 opencode 中文教程
• 当前免费模型 Grok Code Fast 1、 Big Pickle、GLM 4.7、MiniMax M2.1
• 支持 Superpowers 插件

Superpowers 插件 是目前 AI 编码代理领域最受欢迎、最有影响力的技能框架之一，由开发者 obra（fsck.com 作者）创建，主要目标是为编码代理（coding agents）提供一套完整、可组合、可复用的软件开发工作流和方法论。更多请阅读 Superpowers 深度解析

它最初是为 Claude Code 设计的，后来扩展支持 OpenCode 和 OpenAI Codex 等平台，成为跨平台的事实标准技能库（截至2026年初，GitHub 星数已超过 15k+）。

缺点

• 插件、MCP安装比较麻烦，没有一键安装
• GUI客户端（不依赖终端）不成熟

一、准备

1.1 安装

参考 安装：5 分钟搞定

说明

• 通过curl安装命令客户端名叫opencode-cli
• 通过 备用安装方式npm、pnpm、bun、yarn 安装后客户端名叫 opencode （这种较多）

1.2 安装插件

推荐安装 Superpowers 插件，借鉴开源社区在工程实践中的优秀规范经验

# 克隆仓库到指定位置
mkdir -p ~/.config/opencode/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

#创建插件目录并建立软链接（让 OpenCode 能发现它）
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js

# 重启 OpenCode（最重要一步！）。退出当前 opencode 会话，然后重新打开即可

验证方案，启动 opencode 终端后问一句："do you have superpowers?" 应该明确回答有

1.3 安装MCP

• web 搜索插件 mcp-fetch 特点不用FQ，缺点不能搜github
• context7 提供最新API查询
• app.grep 提供文件内容搜索

通过编辑 ~/.config/opencode/opencode.jsonc 文件可以实现MCP服务安装，大概如下

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // 网页搜索
    "fetch": {
      "type": "local",
      "command": [
        "bun",
        "x",
        "fetch-mcp@latest"
      ],
      "enabled": true,
      "timeout": 60000,
      "environment": {
        "PLAYWRIGHT_BROWSERS_PATH": "0",
        "FETCH_MCP_HEADLESS": "true"
      }
    },
    // 开源项目最新API接口查询
    "context7": {
      "type": "local",
      "command": ["bun", "x", "@upstash/context7-mcp", "--api-key", "你的 API_KEY"],
      "enabled": true
    }, 
    // 搜索海量GitHub仓库
    "grepapp": {
      "type": "remote",
      "url": "https://mcp.grep.app",
      "enabled": true
    }
    // 智普清言的MCP...
  },
  "plugin": [
     // 本地存储跨项目长期记忆
     "opencode-mem"
  ]
}

1.4 首个提问

对于新项目以下提问可以引导你实施，提升工作效率

我想启动一个新项目：[在此用一句话描述项目]

请从头开始遵循您的完整 Superpowers 工作流程：
1. 从头脑风暴与设计优化开始
2. 使用 git worktrees 进行隔离开发
3. 将所有工作拆分为可测试的小任务
4. 对每个更改严格遵循 TDD
5. 在任务间执行两阶段代码评审

说明git worktrees隔离开发时，AI会将某个功能块创建为独立目录进行实现，待实施检验完成后会提醒你将代码其合并到当前项目。

二、界面操作说明

2.1 多项选择界面

在和AI对话过程中，有时需要我们一次选择确定多个事项，opencode 会显示这样的界面

它的操作方法是

1. 先用↑/↓定位你要选择的条目，再按回车键Enter确定选中
2. 然后通过→切换到下一个待选卡片继续选中。可以使用←回到之前选择的卡片上重选
3. 在最后一个卡片Submit上输入Enter后将提交整个选择结果

三、常见问题

问题：如何输入多行。Shift+Enter会直接发送输入内容
解决办法：使用Ctrl+J

问题：Linux TUI 选中历史对话内容提示“Copied to clipboard”但粘贴没有内容
解决办法：opencode 依赖xclip软件实现复制，检查xclip软件是否安装，是否能够正常使用。

问题：.worktrees 合并失败导致代码丢失！
问题描述 .worktrees AI合并失败后并没有提示出来，后续操作又会导致.worktrees目录被删除。由于.worktrees目录不会被git跟踪，最终无法找回代码。

解决办法：在将.worktrees合并到主分支之前先备份一次。比如 ! 进入shell模式 cp -r .worktrees .worktrees.bak。

优秀经验

设计文档约束提纲

Martin Fowler推荐的提示词框架：

我需要构建[功能]。在编写任何代码之前，带我逐步了解设计：
- 能力：[范围约束]
- 组件：[基础设施与架构约束]
- 交互：[集成与数据流模式]
- 契约：[类型与接口约定]

逐层呈现，每层需经我确认后再进入下一层。
契约未达成一致前，禁止编写代码。

多层次角度评审

寻找不同层次角度的“最佳实践”来评审几乎总是有效的

架构层面最佳实践
模块业务层面最佳实践
语言层面最佳实践
三方依赖库最佳实践
...

需要注意附加你的具体场景信息作为约束能获得更好的效果，比如明确用户数量、峰值并发量等。

反思过度设计

AI总是倾向过度设计，为此我们至少做一轮以上对此的反思。