OpenCode 完全指南：开源 AI Coding Agent 从入门到精通

OpenCode 解决的不是"如何让 AI 写代码"，而是"如何让 AI 编程助手真正留在开发者自己的环境里"。它把代码生成、LSP 诊断、文件操作和终端控制全部跑在本地，模型提供商可换，数据不经过第三方——这是它与 GitHub Copilot、Claude Code 等闭源方案最根本的分界线。

截至 2026 年初，OpenCode 在 GitHub 上已获得超过 15.3 万星标、1.77 万分支。它由 Neovim 爱好者和 terminal.shop 的创建者联合开发，核心目标是为开发者提供一个完全开放、无绑定提供商的终端编程环境。

快速地图：

本文覆盖原理分析、架构解读、多平台安装配置、典型场景演示，以及二次开发路径。前置要求：基本编程经验、熟悉 CLI 工具和至少一门主流语言。

1. 核心设计理念

OpenCode 与闭源编程助手（如 GitHub Copilot、Claude Code）的差异，可以从三个设计抉择来理解。

完全开源，代码可见。 整个项目采用 MIT 许可证，核心逻辑对社区完全透明。任何人都可以审计其行为、报告安全问题或自行修改后分发。这在企业内网场景中尤为重要——OpenCode 可以部署在私有服务器上，数据不必流出到第三方。

不绑定特定 LLM 提供商。 OpenCode 推荐通过 OpenCode Zen 获取模型，但同时支持 Claude、OpenAI、Google 以及本地模型。模型能力趋同、价格下降时，用户换模型不必换工具链——provider-agnostic 策略直接保护的就是这个选择权。

终端优先的交互范式。 团队来自 Neovim 社区，产品的核心交互界面是 TUI（终端用户界面），而不是 Web UI 或 IDE 插件。Web UI 和桌面应用同样可用，但 TUI 是第一公民，也是理解 OpenCode 设计思路的关键入口。

2. 架构解析

2.1 整体架构

OpenCode 采用客户端/服务器分离架构：

┌─────────────────────────────────────────────────────────┐
│                     Client Layer                        │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐ │
│  │  TUI (SolidJS)│  │ Web UI       │  │ Desktop (Tauri) │ │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘ │
└─────────┼────────────────┼───────────────────┼──────────┘
          │                │                   │
          └────────────────┴───────────────────┘
                           │ HTTP/WebSocket
┌──────────────────────────┼────────────────────────────────┐
│                     Server Layer                           │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              OpenCode Server (Node.js/Bun)           │  │
│  │  ┌────────┐  ┌──────────┐  ┌─────────┐  ┌─────────┐  │  │
│  │  │ Agent  │  │   LSP    │  │Provider │  │ Session │  │  │
│  │  │ Engine │  │ Manager  │  │  Router │  │ Manager │  │  │
│  │  └────────┘  └──────────┘  └─────────┘  └─────────┘  │  │
│  └──────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

服务器层运行在本地，监听 HTTP/WebSocket 请求，提供会话管理、文件操作、LSP 进程控制等核心能力。客户端层通过 REST API 与之通信，这意味着 TUI 只是可选的前端——服务器可以完全脱离 UI 独立运行，甚至支持远程连接，移动端也可以作为操控端。

2.2 核心模块

2.3 技术栈选择

项目使用 Bun 1.3+ 作为运行时和打包工具，在 monorepo 架构下通过 turbo.json 组织包之间的依赖关系。主要依赖：

• SolidJS — TUI 和 Web UI 的 UI 框架选择 SolidJS 而非 React，原因是其细粒度响应式更新更契合高频交互场景
• Effect — 层级化依赖注入（Layer/Context/Service），替代传统 class DI
• Zod — 运行时 schema 验证，配合 Effect 的 Schema 系统实现类型安全的配置管理
• Drizzle ORM — 数据库访问层（SQLite），用于持久化会话记录和项目元数据
• Tauri — 桌面应用外壳，Rust 后端提供原生系统集成

2.4 多 Agent 机制

OpenCode 内置三种 Agent，可在对话中通过 Tab 键切换：

build（默认）——具备完整权限，可以读写文件、执行 shell 命令、管理 Git。适用于日常开发工作。

plan——只读模式，默认拒绝文件编辑，执行 shell 命令前需要用户确认。适用于探索陌生代码库、制定修改计划，或在 pair programming 场景中让 AI 先分析再决策。

general——内部调用的子 Agent，处理复杂搜索和多步任务。用户也可以在消息中输入 @general 直接调用。

这三个 Agent 通过 packages/opencode/src/agent/ 下的 prompt 模板驱动，prompt 本身以 .txt 文件形式存储在仓库中，社区可以自行修改或创建新 Agent。

2.5 内置 LSP 支持

OpenCode 原生集成 Language Server Protocol（LSP），通过 packages/opencode/src/lsp/ 中的 lsp.ts、client.ts、server.ts 等模块管理 LSP 进程。具体来说：

1. 跨语言代码理解 —— LSP 提供精确的符号索引、引用查找和语义高亮，不依赖模型对语言的推理能力
2. 实时诊断 —— 无需用户手动配置任何 IDE，OpenCode 启动时自动检测项目并启动对应语言的 LSP 服务器
3. 增量补全上下文 —— Agent 可以在执行修改前查询 LSP 获取准确的作用域信息，避免凭 token 数量"猜"代码结构

支持的 LSP 服务器覆盖主流语言，具体取决于项目中是否包含对应的语言服务器配置文件（如 tsconfig.json、rust-toolchain.toml 等）。

3. 安装与配置

3.1 安装方式

OpenCode 支持多种安装渠道，以下按推荐程度排序。

Homebrew（macOS / Linux，推荐始终保持最新）：

brew install anomalyco/tap/opencode

npm / bun / pnpm / yarn（跨平台）：

npm i -g opencode-ai@latest
# 或
bun add -g opencode-ai

YOLO 一键脚本（Linux/macOS，下载即用）：

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

安装脚本按以下优先级决定安装路径：

1. $OPENCODE_INSTALL_DIR（若设置）
2. $XDG_BIN_DIR（符合 XDG 规范）
3. $HOME/bin（若存在或可创建）
4. $HOME/.opencode/bin（默认回退）

Windows：

scoop install opencode
# 或
choco install opencode

Arch Linux：

sudo pacman -S opencode           # 稳定版
paru -S opencode-bin              # AUR 最新版

其他：

mise use -g opencode              # mise 工具链
nix run nixpkgs#opencode          # Nix/NixOS

注意：如果此前安装过 0.1.x 版本的 OpenCode，建议先卸载旧版本再安装，新版在架构上有较大变化。

3.2 桌面应用（Beta）

除了终端界面，OpenCode 还提供桌面版应用，下载文件位于 GitHub Releases 或 opencode.ai/download：

macOS 用户也可以通过 Homebrew 安装：

brew install --cask opencode-desktop

3.3 配置与权限管理

OpenCode 的配置文件位于项目根目录的 .opencode/opencode.jsonc。一个典型配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},       // LLM 提供商配置
  "permission": {      // 权限规则
    "edit": {
      "packages/opencode/migration/*": "deny"
    }
  },
  "mcp": {},           // MCP 服务器配置
  "tools": {
    "github-triage": false,
    "github-pr-search": false
  }
}

权限规则支持目录级别的 allow、deny、ask 三种策略。例如，保护迁移脚本目录不被意外修改：

"permission": {
  "edit": {
    "db/migration/*": "deny",
    "src/*": "allow"
  }
}

4. 实战演示

4.1 一次完整的修复流程

以下展示一个具体请求如何流过 OpenCode 的各个模块。假设项目 ./my-project 中 src/api/user.ts 的 getUserById 函数在用户不存在时返回类型不正确。

opencode ./my-project

在 TUI 中输入：

修复 src/api/user.ts 中的类型错误，getUserById 函数在用户不存在时没有返回正确的类型

OpenCode 的处理链路：

1. Session Manager 创建或复用当前会话，加载项目上下文。
2. LSP Manager 启动 TypeScript 语言服务器，对 src/api/user.ts 建立符号索引和类型诊断——此时已经能拿到精确的 getUserById 签名和当前返回类型。
3. Agent Engine（build Agent） 把用户请求、LSP 诊断结果、相关文件内容拼成 prompt，发给 Provider 路由器选定的模型。
4. 模型返回修改方案后，Agent 在 apply 前还会再查一次 LSP，确认修改范围内没有引入新的类型冲突。
5. 用户确认后，Agent 写入文件。如果配置了 permission.edit 规则（比如 db/migration/* 设为 deny），即使模型建议修改这些目录，Agent 也会直接拒绝。

这个流程里，LSP 不是可有可无的辅助——它让 Agent 在生成和验证两个阶段都有精确的类型信息，而不需要靠 token 数量"猜"代码结构。

4.2 使用 Plan Agent 探索代码

当接手一个陌生的代码库时，先用 Plan Agent 做一轮分析：

分析这个仓库的整体结构，重点关注认证和权限相关的代码在哪里

Plan Agent 默认只读，运行 shell 命令前会询问，非常适合在动手之前获取一份结构化分析。

4.3 API 服务模式

OpenCode 支持以 headless 服务方式运行，其他客户端通过 HTTP 调用：

opencode serve --port 4096

默认端口为 4096。启动后可以 Attach TUI 到该服务器：

opencode attach http://localhost:4096

这种分离式架构在远程开发场景中直接可用——OpenCode 服务运行在服务器上，开发者通过本地 TUI 或 Web UI 远程操控。

4.4 Web UI 模式

同时启动服务端和 Web 前端：

opencode web

这会启动一个本地 Web 服务器，提供图形化界面用于会话管理和配置调整。

5. 二次开发与扩展

5.1 本地开发调试

OpenCode 使用 Bun 作为开发时工具链，要求版本 1.3 以上。

克隆并初始化：

git clone https://github.com/anomalyco/opencode.git
cd opencode
bun install

启动开发服务器：

bun dev

默认在 packages/opencode 目录下运行。如果需要在其他目录工作：

bun dev /path/to/your/project

编译独立可执行文件：

./packages/opencode/script/build.ts --single
./packages/opencode/dist/opencode-<platform>/bin/opencode

平台标识如 darwin-arm64、linux-x64。

调试配置（VSCode）：

项目仓库中包含示例配置 �PROTECTED_68� 和 �PROTECTED_69�，复制为正式文件后即可使用。

调试 OpenCode TUI 时推荐使用 bun run --inspect=ws://localhost:6499/ 并配合 VSCode 的 “Attach to Node” 配置。如果需要在 TUI 中触发服务端断点，可以在 packages/opencode/src/index.ts serve 时单独启动服务器并 attach。

5.2 项目结构概览

packages/
├── opencode/       # 核心业务逻辑、CLI 入口、TUI（SolidJS + opentui）
├── app/            # 共享 Web UI 组件（SolidJS）
├── desktop/        # Tauri 桌面应用外壳
├── core/           # 跨包共享的工具库和全局配置
├── sdk/            # 对外 SDK，供第三方应用调用 OpenCode API
└── ui/             # 设计系统和 UI 组件库

.opencode/
├── agent/          # 自定义 Agent 配置文件
├── skills/         # 自定义 Skill 扩展
├── plugins/        # 插件目录
└── opencode.jsonc  # 主配置文件

5.3 新增 Provider

OpenCode 对 LLM 提供商的抽象在 packages/opencode/src/provider/ 中。若要接入新的提供商，官方建议先向 models.dev 提交 PR——大多数新提供商的支持不需要修改 OpenCode 核心代码，只需在 provider 路由层配置即可。

5.4 插件与 Skill 扩展

OpenCode 支持通过 .opencode/plugins/ 目录加载自定义插件，通过 .opencode/skills/ 添加自定义 Skill。插件用于扩展工具能力（如集成内部平台），Skill 用于定义 Agent 的行为模式和工作流程。

5.5 贡献代码

项目接受以下类型的贡献：Bug 修复、新增 LSP/Formatter 支持、LLM 性能优化、新提供商支持、环境兼容性问题修复和文档改进。UI 或核心功能改动需要先通过设计评审。

提交 PR 前必须关联一个已有的 Issue，使用 Fixes #123 格式在 PR 描述中链接。所有代码风格规范参见项目根目录的 AGENTS.md。开发环境要求 Bun 1.3+。

6. 常见问题

OpenCode 和 Claude Code 有什么主要差异？

功能上接近。根本区别在于 OpenCode 完全开源、不绑定提供商（可以自建模型服务或使用任何兼容 API）、内置 LSP 支持，以及客户端/服务器架构允许远程操控。OpenCode 的 TUI 是第一公民而非附加功能。

是否支持本地模型？

支持，只要本地模型提供兼容的 OpenAI 格式 API 接口。配置 provider 字段指向本地地址即可。

如何保障代码安全？

OpenCode 在本地运行，所有操作不经过第三方服务器。权限系统支持细粒度目录级别控制，可以设置 deny 规则防止误操作关键目录。通过 MCP 扩展的每次外部调用也在权限规则管控范围内。

项目用什么数据库？

会话和项目元数据使用 SQLite 存储（通过 Drizzle ORM），数据库文件位于 $HOME/.opencode/ 下。如需迁移或查看数据，可以使用 opencode db 命令。

7. 采用建议

OpenCode 把"AI 编程助手"从封闭生态里拉回了开发者本地：代码开源、模型可选、数据不出机器。终端优先和客户端/服务器架构这两个设计，让它同时适合个人开发者的日常使用和团队级部署。

谁该先用：

• 需要在内网或私有服务器上部署 AI 编程能力的团队——OpenCode 的本地运行 + 权限系统直接解决了数据主权问题。
• 对终端工具有强烈偏好的开发者——TUI 的体验深度是 IDE 插件架构难以复制的。
• 想基于开源项目做二次定制或集成的团队——MIT 许可证 + 明确的 SDK 和插件体系降低了集成门槛。

谁可以不急着上：

• 重度依赖 IDE 插件生态、不愿离开图形界面的开发者——OpenCode 的桌面应用和 Web UI 还在 Beta 阶段，不如 TUI 成熟。
• 已经有稳定闭源工具链、且对数据主权不敏感的团队——迁移成本可能高于收益。
• 项目依赖的 LSP 语言服务器在 OpenCode 中尚未支持——虽然覆盖主流语言，但需要先确认。

建议路线： 先用 opencode ./your-project 在本地终端跑几天，熟悉 TUI 和三种 Agent 的切换；确认顺手后，再考虑 opencode serve 部署到团队服务器，或通过 .opencode/skills/ 添加自定义行为。

相关资源：

• 官方文档：https://opencode.ai/docs
• GitHub 仓库：https://github.com/anomalyco/opencode
• Discord 社区：https://opencode.ai/discord
• 桌面应用下载：https://opencode.ai/download