Announcement

👇Official Account👇

Welcome to join the group & private message

Article first/tail QR code

PFinalClub
Search K

Appearance

OpenCode 架构实战：开源 AI 编程 Agent 如何靠模型无关设计登顶排行榜 ​

2026 年 6 月 17 日，LogRocket 发布了 6 月版《AI 开发工具实力榜》（AI Dev Tool Power Rankings）。结果出乎所有人意料——OpenCode，一个开源终端 AI 编程 Agent，超越了 Cursor、Claude Code、Codex CLI 等所有闭源对手，登顶第一。

数据令人震惊：172K+ GitHub Stars、750 万月活开发者、支持 75+ 模型。而就在同一天，SpaceX 宣布 600 亿美元收购 Cursor，Gemini CLI 宣布停服——开源和闭源两条路在同一天走到了截然不同的分岔口。

更有意思的是，OpenCode 的执行速度比 Claude Code 慢 78%，但它仍然排名第一。这说明在 AI 编程工具的评价体系里，"快"已经不是唯一指标了。模型灵活性、开源可定制性、成本可控性正在成为新的权重维度。

本篇不是安利文，而是将 OpenCode 的源码架构完整拆解——模型无关层、自定义 Tool 系统、Workflow 编排机制——并附带实际部署的踩坑记录。

一、为什么突然都在讨论 OpenCode ​

1.1 封禁事件引发的连锁反应 ​

2026 年 1 月，Anthropic 封禁第三方工具调用 Claude Code 服务。大量开发者刚把 Claude Code 集成进工作流，突然被告知"这条路走不通了"——不是模型不能用，是入口被掐了。

OpenCode 在这个时机快速迭代，从"又一个开源 CLI"变成了"模型无关的编程 Agent 平台"。三个月内 Stars 从 140K 增长到 172K，月活从 65 万飙升到 750 万。

1.2 Gemini CLI 停服加速迁移 ​

2026 年 6 月 18 日 Gemini CLI 宣布停服，大量用户需要替代品。OpenCode 的模型无关架构天然适合这类迁移——不需要换模型，只需要配一个新的 Provider。

1.3 成本压力驱动 ​

Cursor 被 SpaceX 收购后，社区普遍预期商业化加价。重度使用 Claude Code 一个月 API 费用约 200-500 美元，而 OpenCode + DeepSeek 只要 15-30 美元——差了一个数量级。

二、核心架构：模型无关层是关键 ​

2.1 双层架构设计 ​

OpenCode 的核心设计决策就一个词：模型无关（Model Agnostic）。

传统 AI 编程工具的架构是绑定的——Claude Code 绑定 Claude 系列，Codex CLI 绑定 GPT 系列。好处是体验一致，坏处是被锁死了。

OpenCode 把架构拆成两层：

┌─────────────────────────────────────────────┐
│            OpenCode Core (MIT)              │
│  ┌─────────┐ ┌──────────┐ ┌───────────────┐ │
│  │对话管理 │ │文件操作  │ │ Tool 调度引擎 │ │
│  └─────────┘ ┌──────────┘ ┌───────────────┘ │
│         ↓ 不关心用什么模型 ↓                  │
├─────────────────────────────────────────────┤
│       Provider Plugin System                │
│  ┌────────┐┌─────────┐┌──────┐┌──────────┐ │
│  │Claude  ││GPT-5.5  ││Gemini││DeepSeek  │ │
│  │Adapter ││Adapter  ││Adptr ││Adapter   │ │
│  └────────┘┌─────────┘┌──────┐┌──────────┘ │
│  ┌──────┐┌──────┐┌──────┐┌────────────────┐ │
│  │Qwen  ││GLM-5 ││Ollama││LM Studio(local)│ │
│  │Adptr ││Adptr ││Adptr ││Adapter        │ │
│  └──────┘┌──────┘┌──────┘┌────────────────┘ │
└─────────────────────────────────────────────┘
  • 核心层：负责对话管理、文件操作和 Tool 调度——完全不关心用什么模型
  • 模型适配层：负责多 LLM 接入、请求转发和响应解析

加一个新模型只需要写一个 Provider 适配器，核心层零改动。 这是 OpenCode 相比 Claude Code 最本质的架构优势。

2.2 当前支持的 Provider ​

截至 v1.17.7，OpenCode 支持的 Provider 列表：

Provider模型系列认证方式
AnthropicClaude Opus 4.7 / Sonnet 4.6 / HaikuAPI Key
OpenAIGPT-5.5 / GPT-5.3-CodexAPI Key
GoogleGemini 3.5 Pro / FlashAPI Key
DeepSeekV4 Pro / V4 FlashAPI Key
通义千问Qwen 系列API Key
智谱GLM-5.2 / GLM-4（6/17 刚开源）API Key
Ollama本地模型直连本地直连
LM Studio本地模型直连本地直连

三、安装与多模型配置实战 ​

3.1 安装与初始化 ​

bash
# 环境: Node.js 18+, npm 10+
# 安装 OpenCode
npm install -g @sst/opencode

# 验证安装
opencode --version
# 输出: OpenCode v1.17.7

# 启动交互模式
opencode

启动后进入 TUI（终端用户界面），第一件事是配模型。

3.2 多模型配置 ​

OpenCode 的配置集中在 opencode.json，改一个文件就能切模型：

json
// opencode.json
{
  "models": {
    "default": "claude-sonnet-4-6",
    "fallback": "deepseek-v4-flash",
    "providers": [
      {
        "name": "anthropic",
        "api_key": "${ANTHROPIC_API_KEY}",
        "models": ["claude-opus-4-7", "claude-sonnet-4-6"]
      },
      {
        "name": "deepseek",
        "base_url": "https://api.deepseek.com",
        "api_key": "${DEEPSEEK_API_KEY}",
        "models": ["deepseek-v4-pro", "deepseek-v4-flash"]
      },
      {
        "name": "ollama",
        "base_url": "http://localhost:11434",
        "models": ["llama3:70b"]
      }
    ]
  }
}

切换模型只需一行命令：

bash
# 切换到 DeepSeek 省钱模式
opencode config set default deepseek-v4-pro
# 输出: Model switched to deepseek-v4-pro
# Context: 0/128K (0%)

# 切换到本地模型（代码不外传）
opencode config set default llama3:70b
# 输出: Model switched to llama3:70b (local)
# Warning: Local model may have limited tool-use capability

fallback 字段的意义——主模型超时或报错时自动降级到备用模型。

四、自定义 Tool 系统：不写 MCP 也能扩展 ​

OpenCode 的 Tool 系统分两类：Custom Tool 和 MCP Tool。

4.1 Custom Tool：配置文件定义 Shell 命令 ​

Custom Tool 不需要写代码，在配置文件里定义一个 Shell 命令就行：

json
// opencode.json - tools 部分
{
  "tools": {
    "custom": [
      {
        "name": "run_tests",
        "description": "运行项目的测试套件。传入test_path可指定单个测试文件。",
        "command": "pytest ${test_path:-tests/} -v",
        "parameters": {
          "test_path": {
            "type": "string",
            "description": "测试文件路径（可选）",
            "required": false
          }
        }
      },
      {
        "name": "check_types",
        "description": "运行TypeScript类型检查",
        "command": "npx tsc --noEmit",
        "parameters": {}
      },
      {
        "name": "lint_fix",
        "description": "运行ESLint检查并自动修复",
        "command": "npx eslint --fix ${files}",
        "parameters": {
          "files": {
            "type": "string",
            "required": true
          }
        }
      }
    ]
  }
}

AI 在对话中会自动调用这些 Tool：

bash
> 帮我跑一下测试看看有没有挂的

🤖 OpenCode:
  [Tool: run_tests] 执行: pytest tests/ -v
  ---
  test_user_model.py::test_create_user PASSED
  test_user_model.py::test_duplicate_email PASSED
  test_api.py::test_login PASSED
  test_api.py::test_logout FAILED
  ---
  3 passed, 1 failed in 2.34s

  test_api.py::test_logout 挂了，我看看...
  [读取 test_api.py]
  发现问题：logout接口的token校验逻辑少了一个空值判断。
  [修改 test_api.py]
  [再次运行 run_tests]
  4 passed in 2.31s ✅

4.2 Custom Tool vs MCP Tool 怎么选 ​

维度Custom ToolMCP Tool
开发成本极低（一行 Shell 命令）高（完整的 Python/Node 服务进程）
灵活性受限于 Shell 能力任意逻辑
跨工具可用仅 OpenCode 内MCP 标准可跨工具通用
适用场景测试、Lint、构建等简单命令数据库查询、第三方 API、复杂转换

90% 的场景用 Custom Tool 就够了。 只有接入数据库、调第三方 API 或做复杂数据转换时才值得写 MCP Server。别为了用 MCP 而用 MCP——见过有人为了跑 git status 都写了个 MCP Server，纯属过度工程化。

4.3 Go 项目实战配置 ​

作为 Go 开发者，以下是我的实际配置：

json
// opencode.json - Go 项目 Tool 配置
{
  "tools": {
    "custom": [
      {
        "name": "go_test",
        "description": "运行Go测试，支持指定包路径",
        "command": "go test ${pkg:-./...} -v -count=1",
        "parameters": {
          "pkg": {
            "type": "string",
            "description": "Go包路径（如 ./pkg/handler/）",
            "required": false
          }
        }
      },
      {
        "name": "go_vet",
        "description": "运行go vet静态分析",
        "command": "go vet ./...",
        "parameters": {}
      },
      {
        "name": "go_build",
        "description": "构建Go项目",
        "command": "go build -o /tmp/app-bin ./cmd/server/",
        "parameters": {}
      },
      {
        "name": "go_lint",
        "description": "运行golangci-lint",
        "command": "golangci-lint run ${path:-./...}",
        "parameters": {
          "path": {
            "type": "string",
            "required": false
          }
        }
      }
    ]
  }
}

五、Workflow 编排：把多个 Tool 串成流水线 ​

5.1 为什么需要 Workflow ​

Tool 是单个操作，Workflow 是把多个 Tool 串成流水线。解决的核心问题是——AI 有时候不知道该按什么顺序调用 Tool。

5.2 Workflow 配置示例 ​

json
// opencode.json - workflows 部分
{
  "workflows": {
    "pre-commit": [
      "go_vet",
      "go_lint",
      "go_test"
    ],
    "deploy": [
      "go_test",
      "go_build",
      { "tool": "docker", "args": "build -t app ." },
      { "tool": "docker", "args": "push app:latest" }
    ],
    "full-check": [
      "go_vet",
      "go_lint --path=${changed_files}",
      "go_test --pkg=./..."
    ]
  }
}

5.3 Workflow vs Claude Code 的 Skill ​

维度Workflow (OpenCode)Skill (Claude Code)
执行确定性硬编码顺序，AI不能跳步提示词引导，AI可能不按你说的来
适用场景部署、CI 流程等确定性操作需要灵活推理的复杂任务
开发成本JSON 配置文件提示词编写
可靠性高（确定性执行）中（依赖AI理解提示词）

对于需要确定性执行的场景——比如部署流程——Workflow 比 Skill 靠谱得多。

六、架构对比：OpenCode vs Claude Code vs Codex CLI ​

维度OpenCodeClaude CodeCodex CLI
开源协议MIT ✅闭源闭源
模型绑定75+ 模型可切换Claude 系列GPT 系列
本地模型Ollama + LM Studio ✅不支持 ❌不支持 ❌
Custom Tool配置文件 Shell 命令 ✅不支持 ❌不支持 ❌
Workflow 编排原生支持 ✅Skill 系统不支持 ❌
MCP 协议支持 ✅支持 ✅支持 ✅
私有化部署可以 ✅不可以 ❌不可以 ❌
单模型体验中等最佳良好
月费（重度使用）15-30 美元200-500 美元100-300 美元

Claude Code 在单模型体验上仍然最好——Anthropic 对 Claude 模型的调优确实到位。但 OpenCode 赢在灵活性和成本可控。

七、实际踩坑记录 ​

坑 1：本地模型 Tool Use 不完整 ​

Ollama 跑的 llama3:70b 对 Tool 调用支持不完整，复杂任务会丢参数。让它"读取项目里的 test 文件，找出失败的测试，分析原因并修复"，它直接跳过了 Tool 调用，用幻觉编了一段不存在的测试结果。

原因：本地模型没有经过 Tool Use 专项微调，指令遵循能力不如 API 模型。

解决方案：本地模型只用于简单代码补全和问答，涉及多步骤 Tool 调用的任务切回 API 模型。

坑 2：fallback 机制有延迟 ​

主模型超时后切到备用模型，中间有 3-5 秒等待。如果主模型频繁超时，体验会断断续续。

解决方案：设置合理的 timeout（建议 30 秒），备用模型选 API 模型（如 DeepSeek）而非本地模型。

坑 3：AGENTS.md 和 CLAUDE.md 不兼容 ​

官方文档说"可以复制 Claude Code 的 CLAUDE.md 改名为 AGENTS.md"，但实际上两者格式有差异——CLAUDE.md 支持的前置指令语法在 OpenCode 里不认。

解决方案：手写一份精简版 AGENTS.md，只保留项目结构说明和编码规范，不依赖特定格式语法：

markdown
# AGENTS.md — 项目约定

## 项目结构
- `cmd/server/` — 入口
- `pkg/handler/` — HTTP handlers
- `pkg/service/` — 业务逻辑
- `pkg/store/` — 数据存储

## 编码规范
- 错误处理：使用 `fmt.Errorf("context: %w", err)` 链式包装
- 日志：使用 `slog` 结构化日志
- 测试：Table-driven tests，文件名 `*_test.go`

坑 4：Windows TUI 渲染偶发错位 ​

Bubble Tea 框架在 Windows Terminal 上偶尔边框错位，不影响功能。Linux 和 macOS 下正常。

坑 5：社区生态比 Claude Code 薄 ​

遇到问题搜 Stack Overflow 和 GitHub Issues，结果比 Claude Code 少很多。但 OpenCode 的 GitHub Issues 响应速度还不错——提了一个 Workflow 变量展开的 Issue，6 小时就有人回复了。

八、开源生态现状与趋势 ​

8.1 第三方扩展包 ​

项目功能状态
oh-my-opencode多 Agent 编排层早期
opencode-drawer-workflowsPipeline + Phase 编排早期
skillware模块化 AI 技能管理早期
CCS多 Provider Profile 管理器相对成熟

8.2 Skill Registry 趋势 ​

社区有人在做 Skill Registry——类似 npm之于Node.js，把可复用的 AI 编程能力打包成可安装的模块。如果这个方向跑通，OpenCode 的生态壁垒会快速建立。

8.3 反直觉的登顶逻辑 ​

OpenCode 比 Claude Code 慢 78% 但仍然登顶，说明在 AI 编程工具的评价体系里，"快"已经不是唯一指标。社区活跃度、模型灵活性、开源可定制性、成本可控性的权重正在上升。

九、我的实际使用策略 ​

任务类型使用模型月费估算
日常开发（接口实现、Bug 修复）Claude Sonnet 4.6~20 美元
预算敏感任务（脚本、数据清洗）DeepSeek V4 Pro~5 美元
简单问答（不涉及代码改动）Ollama llama3:70b0 美元
复杂多步骤任务Claude Opus 4.7~8 美元

月费总计约 33 美元，之前全用 Claude Code 时是 200-500 美元。

参考资料 ​

上次更新于: