阿超 > opencode

opencode

2025-12-18

ai

余生平所作文章，多在三上：乃马上，枕上，厕上也。——欧阳修

OpenCode 全面介绍：开源 AI 编码代理，让“终端与桌面”都能高效写代码

仓库地址：sst/opencode
官网与文档：opencode.ai | Docs
描述：The open source coding agent.
许可证：MIT
分支：默认分支为 dev（请注意不是 main）

OpenCode 是什么？

OpenCode 是一个“开源的 AI 编码代理”，以终端（TUI）为核心体验，同时提供桌面应用（Beta）。它致力于把“AI 助手写代码”的能力变得透明、可控、可扩展，并且不绑定任何一个模型或服务提供商。

与 Claude Code 的对比（摘自 README）：

  • 100% 开源
  • 不与某个单一提供商绑定（可用 Claude、OpenAI、Google 或本地模型；官方推荐通过 OpenCode Zen 提供的模型）
  • 开箱即用的 LSP 支持
  • 专注 TUI（对终端体验的深度打磨）
  • 客户端/服务端架构，未来可以在本机运行，通过移动端远程操控等

安装方式大全（YOLO 到包管理器）

项目提供了极其丰富的安装方式，适配各类用户习惯：

1
2
3
4
5
6
7
8
9
10
11
# YOLO（脚本一键）
curl -fsSL https://opencode.ai/install | bash

# 包管理器
npm i -g opencode-ai@latest        # 或 bun/pnpm/yarn
scoop bucket add extras; scoop install extras/opencode  # Windows
choco install opencode             # Windows
brew install opencode              # macOS 和 Linux
paru -S opencode-bin               # Arch Linux
mise use -g ubi:sst/opencode       # Any OS（通过 mise + ubi）
nix run nixpkgs#opencode           # 或 github:sst/opencode 获取最新 dev 分支构建

提示：在安装前卸载旧版本（0.1.x 以前版本）。

桌面 App（Beta）

除了终端/TUI，OpenCode 还有桌面版（Beta）。你可以从 Releases 或 opencode.ai/download 下载：

  • macOS (Apple Silicon)：opencode-desktop-darwin-aarch64.dmg
  • macOS (Intel)：opencode-desktop-darwin-x64.dmg
  • Windows：opencode-desktop-windows-x64.exe
  • Linux：.deb / .rpm / AppImage

也支持 Homebrew 安装桌面版：

1
brew install --cask opencode-desktop

安装目录选择（环境变量优先级）

安装脚本遵循如下优先级选择安装路径：

  1. $OPENCODE_INSTALL_DIR（用户自定义）
  2. $XDG_BIN_DIR（符合 XDG Base 规范）
  3. $HOME/bin
  4. $HOME/.opencode/bin（默认兜底）

示例：

1
2
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin      curl -fsSL https://opencode.ai/install | bash

内置 Agents：build / plan / general

OpenCode 默认包含两个主 Agent，并可在界面中用 Tab 一键切换：

  • build：默认全权限开发 Agent
  • plan：只读分析 Agent（默认禁止写文件、运行 bash 前会提示确认），适合阅读陌生代码库或规划改动

此外还有一个用于复杂搜索与多步骤任务的子代理：

  • @general：通过消息里输入 @general 调用

更多细节见文档：Agents

GitHub Action 集成：把 AI 编码代理搬进你的仓库工作流

OpenCode 提供了官方 GitHub Action（sst/opencode/github@latest），支持在 Issue、PR 评论中直接触发 Agent 执行任务：

  • 解释问题：

    1
    /opencode explain this issue

  • 自动修复并开 PR：

    1
    /opencode fix this

  • 在 PR 里迭代修改（将变更直接提交到同一个 PR）：

    1
    Delete the attachment from S3 when the note is removed /oc

  • 针对具体行评论进行精准修改：

    1
    2
    [在 Files 选项卡的代码行里评论]
    /oc add error handling here

当你在具体行评论时，OpenCode 会自动获取文件路径、精确行号和 diff 上下文，进行目标改动。

快速安装 Action

1
opencode github install

该命令会引导你安装 GitHub App、创建工作流并设置 Secrets。

手动配置工作流（示例）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
name: opencode

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  opencode:
    if: |
      contains(github.event.comment.body, '/oc') ||
      contains(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Run opencode
        uses: sst/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514

在组织或仓库设置中添加所需的 Secrets（如 ANTHROPIC_API_KEY）。

代码案例：在 PR 评论中让 OpenCode 自动“补坑修复”

下面演示一个实际工作流中常见需求：在 PR 的某段代码中“增加错误处理”。你可以在 Files 选项卡中对具体行发表评论：

1
/oc add error handling here

OpenCode 将：

  • 解析该评论对应文件与行号；
  • 读取该片段的上下文（diff）；
  • 在同一 PR 上提交补丁。

示例补丁可能是这样的（以 TypeScript/Node.js 为例）：

1
2
3
4
5
6
7
8
try {
  const data = await s3.getObject(params).promise();
  // 原有逻辑...
} catch (err) {
  logger.error({ err, params }, "Failed to read object from S3");
  // 根据语义选择是重试、返回默认值还是上抛
  throw new Error("S3 read failed");
}

你不需要在评论里贴文件路径或行号，OpenCode 会自动识别并执行。

Console 与前端技术栈（SolidStart）

仓库的 packages/console/app 使用了 SolidStart 技术栈（SolidJS 的应用框架），开发工作流与构建方式符合前端工程常规实践：

  • 创建项目：

    1
    2
    npm init solid@latest
    npm init solid@latest my-app

  • 开发：

    1
    2
    3
    npm run dev
    # 或自动打开新标签页
    npm run dev -- --open

  • 构建与部署：通过 “presets” 优化目标环境，默认生成 Node 端应用并 npm start 启动。

这意味着 OpenCode 的桌面与 Web 控制台具备现代化前端基础，易于扩展 UI、集成团队特色功能。

开发建议与最佳实践

  • TUI 党：把 OpenCode 当成“AI 编码拍档”，通过 build/plan 来回切换，保持修改有据可依、分析可记录。
  • GitHub 工作流：在 Issue/PR 中使用 /opencode 或 /oc 指令，让 Agent 自动化“解释、修复、补丁提交”，提升协作效率。
  • 模型选择：默认推荐使用 OpenCode Zen 提供的模型，也可配置到 Claude、OpenAI、Google 或本地模型。确保在 Secrets 中设置相应的 API Key。
  • 读写策略：陌生代码库优先用 plan Agent（只读与需确认的 Bash），熟悉后再用 build 完成变更。
  • 客户端/服务端：利用架构优势，把重计算留给本机或服务器，再通过不同前端（TUI/桌面/移动）远程驱动。

结语

OpenCode 用“开源 + 终端优先 + 不绑定供应商”的方式，重塑了 AI 编码代理的使用体验。你可以在本地以最自然的方式与 Agent 协作；也能把它无缝接入 GitHub 工作流，让代码评审与迭代真正“自动而可控”。

现在就用一行命令开始体验吧：

1
curl -fsSL https://opencode.ai/install | bash

让 AI 成为你和团队的编码“共创者”，高效、透明、可扩展。🚀