开源 AI 编程神器 OpenCode 从入门到进阶

这篇文章给你介绍一款正在快速走红的开源 AI 编程工具——**OpenCode**，以及它的桌面工作流搭档 **OpenWork**。

如果你想要一套**开源可控、支持多模型、还能自托管**的 AI 编程环境，这篇可以直接收藏当入门指南。

OpenCode 快速入门介绍

一、OpenCode 是什么？

> Claude Code 很棒。但如果你是一个极客，你会对 OpenCode 一见钟情。从你的 ChatGPT、Claude、Gemini 订阅开始。OpenCode 全部支持。

**OpenCode 是一款开源的 AI 编程代理（Coding Agent），可以看做是 Claude Code 的开源替代品。它不绑定任何单一模型提供商，支持 75+ LLM 提供商以及本地模型，采用隐私优先、可自托管、完全开源的路线。**

它可以运行在：

- 终端 TUI（类似 Neovim 风格界面）
- 桌面应用（Desktop App）
- IDE 插件（VS Code、JetBrains 等）

你只需要用自然语言描述需求，它就能帮你：

- 读代码：理解项目结构、依赖关系、关键模块
- 写代码：生成新功能、补全逻辑、写测试
- 改代码：重构、修 Bug、大规模重命名
- 跑命令：执行脚本、运行测试、构建项目
- 自动化任务：规划多步任务并按计划一条条执行

它完全开源（MIT 协议），支持本地部署和多种模型接入，不依赖任何单一厂商。

二、核心功能与特点

2.1 独特的 Plan / Build 双模式

OpenCode 最有代表性的设计，就是 **Plan / Build 双模式工作流**：

- Plan 模式：只读分析，不乱动代码

只读，专注于「分析与规划」
- 默认不直接修改代码；执行 Bash 命令前会请求权限
- 适合：理解陌生代码库、设计重构方案、评估修改影响

**Build 模式：真正执行修改**

- 完整读写权限，可以直接编辑文件和执行命令
- 适合：实现功能、重构代码、修 Bug、跑测试

实战推荐用法是：**先 Plan 想清楚，再 Build 动手做**，这种「先规划、再执行」的流程，能显著降低翻车风险。

2.2 多模型 + 一键接入 + 免费旗舰模型

在模型这块，OpenCode的定位可以概括为：

> 「模型中立平台」：支持多家模型提供商、本地模型、自带Key，并且开箱即用。

2.2.1 多模型统一管理

OpenCode支持 **75+ 模型提供商**，包括：

- 国际厂商：Anthropic Claude、OpenAI GPT、Google Gemini、GitHub Copilot、AWS Bedrock、Groq、Azure 等
- 国产与本地模型：GLM-4.7、DeepSeek、MiniMax 等
- 本地部署：Ollama、Llama.cpp、vLLM、TGI、LocalAI 等

你可以在同一套工作流中自由切换、对比不同模型，不被任何一家厂商锁死。

2.2.2 一键配置，降低使用门槛

多模型带来的最大问题，往往是配置复杂：不同家的 Base URL、认证方式、模型名各不相同。

OpenCode在这里做了一件非常实用的事情：

> 只需「选择提供商 → 粘贴 API Key」，即可完成一键配置。

它会自动帮你处理：

- 接口地址
- 鉴权方式
- 模型名称映射
- 请求格式细节

不需要手写复杂配置文件，也不必自己调试 HTTP 请求，大幅降低了多模型接入的复杂度。

2.2.3 内置免费顶级模型

在此基础上，OpenCode还通过官方渠道内置了**免费高质量模型通道**，例如：[2]

- Kimi K2.5 免费版（kimi-k2.5-free）
- GLM‑4.7 免费版（glm-4.7-free）

这些模型在：

- 代码生成
- 复杂逻辑推理
- 大项目重构
- 多轮对话与 Agent 场景

中都有非常亮眼的表现，已经可以对标很多闭源旗舰模型。

在 OpenCode 中使用它们非常简单：

- 无需单独去平台注册、申请 Key
- 在模型列表中直接选择 kimi-k2.5-free 或 glm-4.7-free 即可使用

这让新手可以**零成本上手 AI 编程**，老手则可以用来对比评估不同模型的效果和成本。

综合来看，多模型 + 一键配置 + 免费模型，让 OpenCode 在「模型层」兼顾了：

- 灵活性（想用谁就用谁）
- 易用性（配置足够简单）
- 成本（有不错的免费方案可用）

2.3 终端优先的 TUI 体验

对很多开发者来说，**终端就是主战场**。

OpenCode 的 TUI 界面基于终端 UI 框架构建，整体风格偏 Neovim：

- 支持会话列表与快速切换
- 支持流式输出，实时看 AI 思路
- 支持代码 diff 预览、补丁确认
- 内置简易编辑器，可直接看/改代码

对习惯 Vim/Neovim 的同学来说，上手非常自然。

2.4 多会话 & 客户端 / 服务器架构

OpenCode并不是一个「单机小工具」，而是一个可以**当服务使用的编程智能体平台**：

- 多会话并行

同一项目下可以开多个会话
- 比如一个会话做重构，另一个专门调试测试用例

**客户端 / 服务器架构**

- Server 可以部署在本地、远程服务器或企业内网
- Client 可以是：
- 终端 TUI
- 桌面 App
- IDE 插件（VS Code、JetBrains）
- Web UI / 手机 / 机器人（社区拓展）

这让你可以把 OpenCode 当成一个「编程服务」，统一管理权限、模型和工具，然后用各种 UI 去驱动它。

2.5 LSP 集成与工具系统

OpenCode内置了 **LSP（Language Server Protocol）** 集成：

- 自动加载对应语言服务器（如 gopls、pylsp、clangd 等）
- 提供代码跳转、重命名、诊断等能力

同时还提供一批内置工具（glob、grep、view、patch、diagnostics 等），供 AI 智能体在内部调用，实现更复杂的编辑和分析操作。

三、安装与基础配置

3.1 一键脚本安装（Linux / macOS 推荐）

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

特点：

- 自动识别系统与架构（x64 / arm64）
- 自动选择安装目录（遵循 XDG 规范，优先 $OPENCODE_INSTALL_DIR → $XDG_BIN_DIR → $HOME/bin → $HOME/.opencode/bin）
- 自动配置 PATH
- 安装完成后可直接使用 opencode 命令

3.2 包管理器安装

**Node.js / npm：**

npm i -g opencode-ai@latest
# 或 bun/pnpm/yarn 对应命令

**Homebrew（macOS / Linux）：**

brew install anomalyco/tap/opencode   # 社区 tap，更新更快
# 或
brew install opencode                 # 官方 formula，更新较慢

**Windows：**

# Scoop
scoop bucket add extras
scoop install extras/opencode

# 或 Chocolatey
choco install opencode

**Arch Linux：**

paru -S opencode-bin

安装完后，用：

opencode --version

确认安装成功。

3.3 桌面应用安装

适合不喜欢纯命令行的用户：

- 从官网或 GitHub Releases 下载：

macOS: opencode-desktop-darwin-aarch64.dmg / ...-x64.dmg
- Windows: opencode-desktop-windows-x64.exe
- Linux: .deb/.rpm 或 AppImage

macOS 也可用：

brew install --cask opencode-desktop

桌面版提供 GUI，底层仍然驱动同一套 OpenCode 引擎。

3.4 配置模型与密钥

首次运行：

opencode

进入 TUI 后：

1. 输入 /connect
2. 选择你使用的模型提供商（如 Anthropic、OpenAI、Google、DeepSeek 等）
3. 粘贴对应 API Key 即可

也可以直接编辑配置文件：

- 全局配置：~/.config/opencode/opencode.json（或 $XDG_CONFIG_HOME/opencode/opencode.json）
- 项目级配置：<项目根目录>/opencode.json 或 .opencode/opencode.json

典型配置示例（简化版）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CanopyWave",
      "options": {
        "baseURL": "https://inference.canopywave.io/v1",
        "headers": { "Authorization": "Bearer your_key" }
      },
      "models": {
        "zai/glm-4.7": { "name": "glm47" }
      }
    }
  }
}

四、实用使用技巧（强烈建议尝试）

4.1 基础交互流程

4.1.1 基于 CLI/TUI 的交互使用

在项目根目录执行：

opencode

进入后：

1. 选择或新建一个会话
2. 用自然语言描述你的需求，例如：

> 帮我在当前项目中增加一个用户登录接口，使用 JWT 认证，并补全单元测试。
3. 先切到 Plan 模式：看它如何理解项目、计划改动
4. 确认无误后切到 Build 模式：让它执行编辑和测试

4.1.2 基于 WebUI 的远程交互使用

通过 WebUI 以浏览器的形式使用 AI 编程工具，可以实现随时随地使用手机等移动设备远程编程。对于 Claude Code 等工具需要借助如 happyCode 等第三方工具实现。

OpenCode 自带 WebUI 服务支持，可以直接运行如下命令后通过浏览器访问：

opencode web --port 8881 --mdns

其中 mdns 参数用于允许可局域网访问。

OpenCode WebUI 示例

4.2 搭配 oh-my-opencode：多智能体「外挂大脑」

**oh-my-opencode** 是一个「**OpenCode 的超级插件 / 智能体管理框架**」，通过多个专业子智能体并行协作，模拟真实开发团队的工作方式，相当于给 OpenCode 安装一个「多智能体大脑」。

在 OpenCode 基础上，**oh-my-opencode（简称 OMO）** 做的核心事情就是：

> 把原本的“单一 AI 助手”，升级为一个有分工、有协作、能并行干活的多智能体开发团队。

具体实现方式包括：

- 引入一个总控智能体 Sisyphus，负责统筹全局；
- 在后台常驻多个专业智能体（前端、架构、文档、代码探索等）；
- 多个智能体可以异步、并行工作，而不是一个模型从头到尾“单线程想”。

结果是：在复杂项目、长链路任务（如重构大项目、从 0 到 1 搭项目）中，**效率和可靠性显著提升**。

**安装示例：**

# 基于 Bun 的 bunx 安装示例
bunx oh-my-opencode install # recommended

# 基于 Node.js 的 npx 安装示例
npx oh-my-opencode install # alternative

4.2.1 OMO 核心能力

**A. 多智能体协作：并行执行与任务编排**

OMO 的一个核心优势是：**后台多个智能体可以并行工作**。

典型流程（以一个“实现登录功能”的需求为例）：

1. 你只说一句：

> “帮我在当前项目里实现登录 + JWT 鉴权，并补全测试。”
2. Sisyphus 接单 → 调用 Prometheus 生成详细 Plan；
3. 为了搞清项目结构，它会并行启动多个 Explore / Librarian：

- 一个去扫路由
- 一个去看用户模型
- 一个去翻 README / 约定文档
4. 整理完背景后，由 Hephaestus 负责核心实现：

- 新增 /修改哪些文件
- 怎样对接现有中间件
- 写哪些单元测试
5. 若涉及接口设计 / 性能，交给 Oracle 做架构 & 调优；
6. 最终由 Sisyphus 汇总结果，给你可检查的 diff / patch。

**要点**：你不是在和“一个模型聊天”，而是在和 **一个由多模型、多智能体组成的“AI 团队”合作**。

**B. 深度集成 LSP + AST 工具：自动重构、重命名、结构化搜索。**

- LSP（语言服务器）

自动加载如 gopls、pylsp、clangd 等；
- 提供类型信息、符号表、跳转关系等；

**ASTGrep / AST 工具**

- 做语义级搜索和替换；
- 支持安全重命名、方法抽取、模式匹配。

这让智能体在执行诸如“重命名一个核心函数”时，不是简单字符串替换，而是通过 LSP/AST 做 **结构化、安全的重构**，极大降低“改挂项目”的风险。

**C. 上下文治理：自动注入、智能裁剪、降低 token 浪费**

1. 自动注入关键文档

- 如 README.md、AGENTS.md、约定/规范文档会自动进入上下文；
- 不需要你每次手动粘贴。
2. 上下文“分片”给不同智能体

- Librarian 拿文档相关上下文；
- Explore 拿代码结构相关上下文；
- Hephaestus 则只拿与当前修改直接相关的文件/片段；
- 由 Sisyphus 进行统一协调。
3. 智能删减噪声

- 无关注释、重复片段会被压缩或忽略；
- 避免“为了凑上下文，把整个项目塞到一个模型里”。

4.2.2 OMO 智能体矩阵及基本你工作原理

OMO 预设了一整套“专业角色”，常见的包括：

| 智能体 | 主要职责 | 使用场景示例 |
|---|---|---|
| Hephaestus | 深度 Coding 工匠 | 端到端实现复杂功能、大块重构 |
| Oracle | 设计 + 调试专家 | 架构设计、性能分析、疑难 bug 排查 |
| Frontend UI/UX Engineer | 前端工程师 | 页面布局、交互逻辑、组件拆分 |
| Librarian | 文档 / 资料专家 | 查官方文档、找开源实现、读 README/AGENTS 等 |
| Explore | 极速代码库探索者 | AST 级“语义 grep”、代码模式搜索 |
| Multimodal Looker | 多模态分析 | 对复杂多模态内容做解析（如设计稿、图表等） |

其中 **Hephaestus** 的设计非常典型，体现了 OMO 对“真正能干活的智能体”的追求：

- 目标导向：你只给“目标”，它自行决定步骤；
- 行动前探索：在写代码前，会并行调用 Explore / Librarian 先把上下文摸清；
- 端到端负责：没有足够“证据”和验证，不轻易停手；
- 风格匹配：尽量贴合项目既有代码风格，避免“AI 味”太重的垃圾代码；
- 改动最小化：只改必要的地方，减少引入新坑。

**工作原理：**

Oh My OpenCode 的任务执行流程如下：

用户输入任务
    ↓
Sisyphus（主协调器）解析任务并制定执行计划
    ↓
Sisyphus 将任务分派给相应的专业子智能体
    ↓
子智能体在后台并行执行各自任务
    ↓
Sisyphus 汇总各子智能体的输出
    ↓
生成最终结果

整个过程为全自动化。用户只需输入任务描述，系统会根据任务类型自动调度相应的子智能体完成工作，无需额外干预。

4.2.3 OMO 实用指令

**几个非常实用的指令：**

1. ulw（Unified Large Worker）

- 直接把主智能体切换到「项目经理模式」
- 会自动调用不同模型、不同子智能体并行工作，适合从 0 到 1 搭建复杂项目
- 示例：

> ulw 帮我做一个基于 Vue3 + Pinia 的 Todo List，要求数据持久化到 localStorage

1. /ralph-loop

- 强制「思考–执行–验证」闭环，直到满足你设定的终止条件
- 很适合「让测试全绿」「修掉所有 Lint 错误」这类任务

1. ultrawork

- 火力全开模式，大规模重构/长任务时使用（要注意 API 费用）

4.3 日常高效用法建议

- 复杂改动（重构、多文件修改）

→ 务必先用 Plan 看清楚，再用 Build 执行
- 大项目刚接手

→ 让 OpenCode 先「画项目地图」，帮你梳理模块与数据流
- 大量 Bug / 测试不通过

→ 搭配 /ralph-loop，让 AI 自动修到测试通过为止
- 多模型对比

→ 在同一任务下切换不同模型，结合 oh-my-opencode 做 A/B 测试

五、底层技术与架构

5.1 技术栈概览

**核心 CLI / Server：**

- 主要使用 Go 语言实现（老版本 opencode-ai/opencode 仓库即为 Go-based CLI）[3]
- 使用 Cobra 作为命令行框架
- 使用 SQLite 存储会话和对话历史
- 集成 LSP 提供多语言代码智能

**终端 UI / 桌面 UI：**

- 大量使用 TypeScript + Astro / 前端组件构建 UI 部分（尤其是在 anomalyco/opencode 新架构中）[3]
- 桌面端通过 Tauri（Rust + TypeScript）构建（在 OpenWork 中尤为明显）[11]

**扩展与集成：**

- 支持 MCP（Model Context Protocol），可以集成：

websearch（Exa）、context7（文档索引）、grep_app（GitHub 搜索）等工具

提供多语言 SDK（Go、Python、TypeScript），方便自建 Agent 或集成到现有系统[3][10]

5.2 架构要点

整体架构可以简化为：

TUI / 桌面 / IDE 插件 / Web UI
                ↓
     OpenCode SDK / HTTP API
                ↓
          OpenCode Server
     （会话管理 + LSP + 工具系统）
                ↓
     模型网关 / 各家 LLM / 本地模型

- 客户端 / 服务器解耦：让 OpenCode 可以部署在开发机、远程服务器、容器甚至企业内网
- 多会话并行：每个会话独立上下文、独立文件操作
- 插件系统：通过修改 opencode.json 和 .opencode/skills 来扩展能力

六、与主流 AI 编程工具对比

6.1 与 Claude Code 对比

| 维度 | OpenCode | Claude Code |
|---|---|---|
| 授权与开源 | MIT 开源，可自托管 | 闭源，SaaS 服务 |
| 模型支持 | 75+ 提供商 + 本地模型（Ollama 等） | 仅 Claude 系列模型 |
| 工具本身定价 | 工具免费，按模型供应商付费 | 订阅费 + API 费用（如 \$20–\$200/月） |
| 界面形态 | 终端 TUI + 桌面 App + IDE 插件 | CLI + 桌面 App + VS Code 扩展 |
| 工作流 | Plan / Build 双模式，强制先规划后执行 | Plan 模式 + 高度自动化编程代理 |
| 数据与隐私 | 完全可控，可在内网部署 | 依赖云端服务 |
| Skills 生态 | 兼容 Claude Skills，且可通过插件扩展 | 原生 Skills 生态 |
| 响应速度 | 略慢于官方（通常 2.1–2.5 秒级别） | 更快（约 1.6–2.0 秒） |
| 灵活性 | 极高，可任意更换或混合模型 | 中等，受限于Anthropic 生态 |

**简要结论**：

- 不差钱、只追极致体验 → 直接用 Claude Code
- 在意开源、可控、可折腾、怕被封号「断粮」 → 必须掌握 OpenCode 作为「备胎」，很多人甚至把它当主力。[13]

6.2 与 Cursor（AI IDE）对比

| 维度 | OpenCode | Cursor（基于 VS Code 的 AI IDE） |
|---|---|---|
| 使用场景 | 更像「智能体层」，偏自动化工作流 | 更像「IDE 增强」，偏代码补全与局部修改 |
| 界面 | 终端 + 桌面 + IDE 集成 | 完整 IDE（VS Code 改造版） |
| 学习曲线 | 需要理解 Agent / Plan/Build 思路 | VS Code 用户几乎零成本 |
| 模型灵活性 | 极高，多模型+本地模型 | 多模型但集中在云端 |
| 自主性 | 强调自动完成多步复杂任务 | 更强调「人机协同」+ 实时补全 |

一句话概括：

**Cursor 像是「聪明的 VS Code」**，而 **OpenCode 更像「可编排的编程智能体平台」**。

七、OpenWork：基于 OpenCode 的桌面工作流 GUI

7.1 OpenWork 是什么？

**OpenWork** 是基于 OpenCode 引擎的开源桌面应用，定位是 **Claude Cowork / Claude Work 的开源替代品**。

可以理解为：

> OpenCode 是引擎，OpenWork 是图形界面 + 工作流编排层。

适合：

- 不熟悉命令行的知识工作者
- 需要可视化管理任务、权限、进度的用户
- 想把 AI 代理当「本地同事」来用的场景

7.2 核心功能

- 两种模式：

Host 模式：本机启动 opencode serve，工作区目录即为项目根
- Client 模式：连接已有的 OpenCode 服务器（URL）

**工作流界面**：

- 选择 workspace（工作目录）
- 启动 run（任务）
- 实时查看执行计划与进度（Execution Plan Timeline）
- 遇到敏感操作弹出权限对话框（一次性允许 / 永久允许 / 拒绝）

**Sessions & Templates**：

- 创建、切换会话
- 将常用任务保存为模板，一键重跑

**Skills 管理**：

- 读取 .opencode/skills 和 opencode.json
- 可视化安装、启用、禁用插件 / 技能（包括 OpenPackage 安装的技能）

**实时流 / SSE**：

- 界面通过 SSE 订阅 OpenCode 的事件流，实时显示任务状态和日志

7.3 技术栈与架构

- Tauri 桌面壳：Rust + TypeScript
- 前端 UI：位于 packages/app
- 桌面应用：位于 packages/desktop
- UI 通过 @opencode-ai/sdk/v2/client 连接 OpenCode Server，实现：

会话管理
- 提示发送
- SSE 事件订阅
- 权限与 ToDo 管理[11]

本质关系可以概括为一句话：

> OpenCode 是引擎，OpenWork 是体验层。
>
> OpenCode 处理「能干什么」，OpenWork 负责「怎么让人好用」。

八、整体建议与入门路线

如果你看到这里，想实际试一试，可以参考下面的步骤：

1. 先装再说

- 用脚本安装 OpenCode
- 启动后选用内置免费模型（Kimi K2.5 / GLM‑4.7），零成本体验
2. 亲手跑一个任务

- 在自己项目中，让它：

用 Plan 模式梳理项目结构
- 再用 Build 模式帮你实现一个小需求
3. 尝试 oh-my-opencode

- 安装并试用 ulw、/ralph-loop 等命令
- 体验真正意义上的「自动多步任务」
4. 按需求选择界面

- 喜欢终端 → TUI + Vim 风格
- 喜欢可视化 → 装 OpenWork 桌面应用
- 需要 IDE → 配套 VS Code / JetBrains 插件

九、总结与参考

OpenCode 解决了很多传统 AI 编程工具的痛点：

- 不再被单一厂商绑定
- 模型选择足够自由
- 通过 Plan / Build 把复杂任务做得更稳
- 通过 OpenWork、oh-my-opencode 形成了一整套可扩展的工作流生态

无论你是个人开发者，还是负责团队工程效率的技术负责人，都值得花一点时间把它搭起来，用一段时间，你会明显感到：

> 这不只是「写代码更快」，而是「整个开发流程的智能化升级」。