OpenCode 完全指南：2026年开源AI编程助手安装、配置与实战教程

诺***帝2026-06-25 12:32

一句话总结： OpenCode 是一款 MIT 协议开源的终端 AI 编程助手，支持 75+ 大模型接入，提供 Plan/Build 双模式工作流，GitHub Star 突破 16.8 万，是国内开发者目前可直接使用的高性价比 AI 编程方案之一。

OpenCode 是什么？为什么值得关注？

OpenCode 由 anomalyco 团队于 2025 年底开源，定位为"终端原生的 AI 编程代理"（Coding Agent）。它不是简单的代码补全工具，而是能理解整个代码仓库、自主执行多文件编辑、运行终端命令的智能体。截至 2026 年 6 月，最新版本为 v1.16.0，GitHub Star 数约 16.8 万，Fork 数超 2 万，月活开发者超过 150 万。

与 Cursor、GitHub Copilot 等商业工具相比，OpenCode 的核心差异在于：完全开源（MIT 协议）、代码不离开本地、支持 75+ 模型自由切换。对于注重数据隐私和成本控制的国内开发者而言，这是一个值得重点关注的选项。

环境准备与安装

安装 OpenCode 前，需要确认系统环境满足基本要求。整体流程约 5-10 分钟可完成。

系统要求

项目 要求
操作系统 Windows 10+（推荐 WSL）、macOS 12+、Linux 主流发行版
Node.js v20 LTS 或更高版本（推荐 v22 LTS）
磁盘空间 约 200MB（不含模型缓存）
终端 支持 UTF-8 的终端模拟器

四种安装方式

方式一：npm 全局安装（推荐）

bash

复制代码 
bashnpm install -g @opencode/cli
复制代码 
bash
复制代码 
npm install -g @opencode/cli

方式二：macOS / Linux 使用 Homebrew

bash

复制代码 
bashbrew install opencode
复制代码 
bash
复制代码 
brew install opencode

方式三：Windows 使用 Scoop

bash

复制代码 
bashscoop install opencode
复制代码 
bash
复制代码 
scoop install opencode

方式四：从源码编译

bash

复制代码 
bashgit clone https://github.com/anomalyco/opencode.git
cd opencode
npm install
npm link
复制代码 
bash
复制代码 
git clone https://github.com/anomalyco/opencode.git cd opencode npm install npm link

安装完成后执行 opencode --version，显示版本号即表示安装成功。

Windows 用户特别说明

OpenCode 原生对 Windows 的支持持续改善，目前已支持 Windows ARM64 架构。推荐方案是通过 WSL（Windows Subsystem for Linux）运行，兼容性和性能表现更佳。也可使用 Scoop 或 npm 直接安装。

模型接入配置

OpenCode 支持 75+ 种大语言模型提供商，这是它区别于封闭工具的核心优势。配置过程通过 /connect 命令或配置文件完成。

配置文件方式

在项目根目录创建 .opencode.json 文件：

json

复制代码 
json{
  "api": {
    "baseUrl": "https://your-api-endpoint.com/v1",
    "apiKey": "your-api-key",
    "model": "deepseek-chat"
  }
}
复制代码 
json
复制代码 
{  "api": {  "baseUrl": "https://your-api-endpoint.com/v1",  "apiKey": "your-api-key",  "model": "deepseek-chat"  } }

国内可直连的模型推荐

模型 特点 免费额度 延迟（国内实测）
DeepSeek V3 性价比高，中文能力强 目前提供免费额度 约 0.8-1.5 秒
智谱 GLM-4 国内直访，稳定性好 目前提供免费额度 约 0.6-1.2 秒
Kimi API 长上下文支持（128K+） 有限免费额度 约 1.0-2.0 秒
通义千问 阿里云生态，企业级 有限免费额度 约 0.5-1.0 秒

建议初次使用从 DeepSeek 或智谱 GLM-4 开始，两者目前均提供免费额度，注册后即可获取 API Key。

交互式配置

启动 OpenCode 后，输入 /connect 命令，按提示依次填入 API 地址、Key 和模型名称即可完成连接。这种方式适合不想手动编辑配置文件的用户。

Plan/Build 双模式详解

这是 OpenCode 的标志性设计，也是它与多数 AI 编程工具的核心区别。通过 Tab 键可在两种模式间快速切换。

Plan 模式：只看不动

Plan 模式下，AI 只分析需求、拆解任务、输出执行方案，不会修改任何文件。适合以下场景：

  • 复杂功能的架构设计
  • 代码审查与优化建议
  • Bug 根因分析
  • 重构方案评估

Build 模式：说干就干

Build 模式下，AI 会按方案实际创建、修改文件，执行终端命令。适合：

  • 按已确认的方案编写代码
  • 日常编码与 Bug 修复
  • 批量文件操作
  • 自动化脚本执行

推荐工作流

先 Plan 后 Build 的流程，实测可减少约 35%-40% 的返工率。具体步骤：

  1. 1.在 Plan 模式描述需求，让 AI 输出方案
  2. 2.审查方案，必要时追问或调整
  3. 3.确认无误后，按 Tab 切换到 Build 模式
  4. 4.AI 按方案逐步执行，每步展示 diff

核心命令速查

OpenCode 的命令体系分为斜杠命令和快捷键两类。以下是日常使用频率较高的命令：

命令 功能 使用场景
/init 生成 AGENTS.md 项目记忆文件 新项目首次使用
/connect 配置 AI 模型提供商 首次使用或更换模型
/plan 切换到 Plan 模式 需要规划时
/compact 压缩对话历史，释放上下文 长对话后 token 紧张时
/clear 清空当前会话 切换任务
/undo 撤销上一步 AI 操作 AI 改错时回退
/share 生成会话分享链接 团队协作
/model 切换当前使用的模型 需要不同模型能力时

AGENTS.md 项目记忆

执行 /init 后，OpenCode 会在项目根目录生成 AGENTS.md 文件。这是项目的"记忆文件"，记录了项目结构、技术栈、编码规范等信息。AI 每次启动时会读取该文件，快速恢复上下文。建议团队将其纳入 Git 版本管理。

@ 引用文件

在对话中使用 @src/auth/index.ts 语法，可以将指定文件内容直接注入上下文，避免 AI 猜测你指的是哪个文件。

实战技巧

高效提问结构

结构化的提示词能显著提升 AI 输出质量。推荐模板：

text

复制代码 
text【任务】为 Express 项目添加 JWT 认证中间件
【约束】不引入额外 npm 依赖，使用 jsonwebtoken 库
【涉及文件】src/middleware/auth.ts, src/routes/user.ts
【期望】输出完整代码，包含错误处理和类型定义
复制代码 
text
复制代码 
【任务】为 Express 项目添加 JWT 认证中间件 【约束】不引入额外 npm 依赖，使用 jsonwebtoken 库 【涉及文件】src/middleware/auth.ts, src/routes/user.ts 【期望】输出完整代码，包含错误处理和类型定义

会话管理

OpenCode 支持多会话并行，适合在不同功能分支上同时开发。长对话后建议使用 /compact 压缩历史，避免上下文窗口溢出导致 AI "遗忘"早期指令。

对话导出

支持将会话记录导出为 Markdown 或 JSON 格式，便于团队复用 AI 分析结果，也可作为技术文档沉淀。

与主流工具对比

对比维度 OpenCode Cursor Claude Code GitHub Copilot
开源协议 MIT（完全开源） 闭源 闭源 闭源
运行方式 终端原生 独立 IDE 终端原生 IDE 插件
模型自由度 75+ 模型可切换 限定模型 仅 Claude 系列 仅 GPT 系列
数据隐私 代码不离开本地 需上传分析 需上传分析 需上传分析
目前免费额度 有（取决于模型） 有限免费 需订阅 需订阅
项目上下文 AGENTS.md + 自动索引 自动索引 自动索引 有限上下文

选择建议：如果看重开源透明和模型自由度，OpenCode 是优先选项；如果偏好图形化体验，Cursor 更友好；如果专注复杂推理任务，Claude Code 表现突出。

常见问题（FAQ）

Q1：OpenCode 完全免费吗？

OpenCode 本身 100% 开源免费，但需要接入 AI 模型才能工作。模型费用取决于你选择的提供商------DeepSeek 和智谱 GLM-4 目前提供免费额度，可零成本开始体验。

Q2：Windows 上一定要用 WSL 吗？

不是必须的。OpenCode 已支持 Windows 原生安装（npm、Scoop 均可），并且已支持 Windows ARM64 架构。但 WSL 环境下的兼容性和性能表现通常更佳，推荐优先考虑。

Q3：OpenCode 的响应速度如何？

响应速度主要取决于所选模型和网络环境。使用国内直连的模型（如 DeepSeek、智谱 GLM），实测首字延迟约 0.6-1.5 秒，与商业工具基本持平。

Q4：代码安全性有保障吗？

OpenCode 默认在本地运行，代码不会上传到外部服务器。Build 模式下，AI 对文件的修改会先展示 diff，用户确认后才实际写入。配合 Git 使用，随时可回退。

Q5：可以和 Cursor 同时使用吗？

可以。两者互不冲突。OpenCode 在终端运行，Cursor 是独立 IDE，很多开发者会在不同场景下交替使用。

总结与建议

OpenCode 在 2026 年的 AI 编程工具生态中占据了一个独特位置：完全开源、模型自由、隐私优先。它的 Plan/Build 双模式设计有效提升了代码生成的可控性，75+ 模型支持让开发者不必被单一厂商绑定。

对于国内开发者的入门建议：

  1. 1.从免费模型开始：DeepSeek 或智谱 GLM-4 目前提供免费额度，适合零成本试用
  2. 2.先 Plan 后 Build：养成先规划再执行的习惯，减少返工
  3. 3.善用 AGENTS.md：为每个项目建立记忆文件，让 AI 更快理解上下文
  4. 4.定期 /compact：长对话后压缩历史，保持响应质量
  5. 5.关注版本更新：OpenCode 迭代节奏快（2026 年 3 月一周内发布 5 个版本），新功能持续增加

无论你是 AI 编程新手还是资深开发者，OpenCode 都提供了一个低门槛、高可控的起点。它的开源特性意味着你可以完全掌控工具链，而不必依赖任何商业订阅。

官方资源：

【本文完】

热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04飞书长连接_事件订阅（接收消息，审批任务状态变更）05Trae国际版与国内版深度测评：AI原生IDE的双生花06GitHub 镜像站点07【AI】2026 年具身智能模型和世界模型总结082026年AI架构实战：彻底解决OpenAI接口超时与封号，Python调用GPT-5.2/Sora2企业级架构详解（附源码+压测报告）09Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析102026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？