天工开物KAIWU AI
工具指南 › OpenCode › OpenCode 使用指南(完整全套)
核实于 2026-11-08
工具指南·其十四核实于 2026-11-08

OpenCode 使用指南(完整全套)

适用对象
想快速了解工具定位、核心功能和上手路径的中文用户
核对日期
2026-11-08
本页目录

本指南综合了 10 篇公众号实测与深度教程(2026-01-29 ~ 10-25)。文中的 [1]~[10] 对应文末「参考原文」,序号与 00_清单.md 一致。每张图下方注明出处与对应文章。素材之间说法不一致、版本重大重构或容易踩坑的地方,均用 ⚠️ 明确标出。

公众号素材涵盖了 2026 年初开源上线、下半年 2.0 架构升级、免费模型池上线以及桌面端 3D 与 MCP 联动的全套实践。指南补充了 OpenCode 官方 GitHub 规范、桌面端 Pairing 协议与 MCP 扩展文档,以 [官1]~[官6] 标注,查阅日期 2026-11-08。


一、定位:它是什么,适合谁

OpenCode(简称 OC,终端命令为 opencode)是开源社区极具代表性的自主编码智能体(Coding Agent)生态系统 [1][2]。

与绑定商业订阅的闭源工具不同,OpenCode 自诞生之初便确立了**「完全开源、全模型兼容、无厂商锁定」**的核心理念 [1][4]。它不仅提供纯终端 CLI,还推出了功能完备的跨平台桌面端(OpenCode Desktop),并支持通过云端 Web 共享会话与历史回溯(Timeline)[1][9]。

图 1 官网下载页

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

1. 核心特性

  • 双端形态同构:终端 CLI 专注于速度与无缝脚本自动化;桌面客户端支持多会话管理、文件预览、一键 MCP 配置与手机/网页扫码远程配对(Pairing)[1][9]。

  • 开箱即用的「免费模型池」:针对不愿先绑定海外信用卡或购买 API Key 的新手,OpenCode 官方及社区节点预置了内置免费模型池(涵盖 DeepSeek-Flash、Qwen 等),装好就能直接打字体验 [2][3]。

  • 时间线回溯机制(Timeline):每一个操作步骤都会自动打下代码快照,如果 AI 改崩了项目,支持一键精确倒退到任意历史节点 [1]。

  • 深度 MCP 协议生态支持:支持直接在会话中以自然语言形式安装、调试并调用各类 MCP 插件,甚至能驱动 Blender 建模生成 3D 动画 [9]。

2. 和同类 AI 编码工具怎么比

维度OpenCodeClaude Code小米 MiMo CodeCursor
代码开源度100% 完全开源,社区驱动 [1]闭源商业产品客户端开源,后端闭源闭源商业编辑器
模型自由度完全自由,原生支持几十家平台及本地 Ollama [1][9]绑定 Claude(第三方易封号)支持国内主流中转官方精选多模型
免费起步机制内置社区免费模型池,无需自备 Key [2][3]必须付费订阅 Pro/API绑定小米账号赠送额度有限次高级请求
版本回退机制内置可视化 Timeline 快照回溯 [1]依赖 Git 本地撤销依赖 Git依赖编辑器本地时光机
生态连接能力支持全套 MCP 插件与跨端 Pairing 遥控 [9]支持 MCP偏向基础工具调用支持外部文档与规则

适合谁:

  • 注重隐私与完全掌控权的开发者:不想被任何商业大厂绑死,希望在不同项目里自由切换 DeepSeek、Claude、OpenAI 或本地私有化模型的人 [1][4]。

  • 自由探索各类新模型的极客:想在同一个工作台内横向对比不同模型编码质量的人 [3]。

  • 跨平台多模态玩家:需要 Agent 不仅能敲代码,还能联动外部工具(如 Blender、数据库、浏览器爬虫)干综合杂活的人 [9]。

不适合谁:

  • 追求极致极简、完全不想看任何配置弹窗或模型设置,只想要一个单向黑盒的人 [4][10]。

  • 超老旧配置机型且对终端启动速度有极致毫秒级苛求的极客(此时更适合无头极简的 Pi Agent)[10]。


二、准备与安装

0. 先选路线:你属于哪种情况

你的情况推荐路线核心步骤
想要可视化界面、多任务并行、不想配环境OpenCode 桌面客户端(推荐)看第 1、2 步 → 第三节快速上手
习惯终端操作,喜欢全键盘极速流命令行 CLI (opencode)看第 1、3 步
完全没有自己的 API Key,想先零成本白嫖任意版本 + 启用免费模型池看第 1 步 → 第四节「2. 免费模型池用法」
有自己的商业 Key(如 DeepSeek/Claude/OpenAI)配置自定义提供商看第四节「3. 接入第三方商业模型」

1. 账号与费用结构

OpenCode 本身作为开源框架完全免费 [1]:

  1. 免费模型池(零花费):OpenCode 官方社区维护了一批免费中转节点,新安装用户可直接选择免费池中的模型体验,无需填写任何信用卡与 API Key [2][3]。

  2. 商业 API 自费(按需自付):若需处理企业级大型生产任务,填入你自购的 DeepSeek、OpenAI、Anthropic 或硅基流动 API Key,账单由对应平台直接扣除,OpenCode 无任何中介加价 [1][4]。


2. 桌面客户端安装(Windows / macOS)

第一步:下载客户端

前往官方网站或 GitHub Releases 页面下载打包好的安装包 [1]:

  • Windows:OpenCode-Desktop-Setup-x.x.x.exe。

  • macOS:支持 Apple Silicon 与 Intel 架构 Mac 的 DMG 镜像。

第二步:运行向导与设备配对(Pairing)

桌面端安装极为流畅,双击一路下一步即可完成。首次启动时,桌面端会生成唯一的配对标识(Pairing Key)与二维码:

图 2 桌面版Pairing

图源:[9] Joey的自由世界《今天不聊Coding!我用 OpenCode桌面版做了一段 3D 动画》

你可以随时用手机或远程浏览器扫描此码,在异地安全遥控本地电脑正在执行的任务 [9]。


3. 命令行 CLI 安装与启动

如果你是终端深度用户,使用包管理器进行全局安装:

前置要求

  • Node.js >= 18.0.0(推荐使用 LTS 版本)。

安装命令

bash
# 全局安装 opencode 终端工具
npm install -g opencode-ai

# 或者使用 pnpm
pnpm add -g opencode-ai

终端输出安装成功确认:

图 3 npm安装成功

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

启动 CLI

在任何项目文件夹中输入:

bash
opencode

界面会立刻弹出标志性的 OpenCode 终端交互主界面:

图 4 终端版启动界面

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》


三、上手流程:从零到第一个完整项目

下面以使用 OpenCode 终端版从零开发并部署一个精美在线双排钢琴弹奏网页为例,演示完整的操作全貌 [1]。

第一步:初始化项目规范

进入新创建的空目录,输入:

bash
opencode init
图 5 init生成AGENTS

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

系统会自动识别工作区,并生成标准的 AGENTS.md 文件,作为该项目的系统级行为基准 [1]。

第二步:选择工作模型

在交互菜单中选择你要使用的模型(可直接选免费模型池中的模型或自备的商用模型)[1]:

图 6 选择模型

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

第三步:输入需求并执行

在提示符后键入:

"在当前目录下帮我编写一个现代风格的 Web 钢琴弹奏网站。包含全套黑白琴键,支持键盘按键映射与鼠标点击发声,采用 Web Audio API 合成真实钢琴音色,界面要有琴键按下的动效。"

OpenCode 开始自动拆解步骤、编写 HTML、CSS 与音频合成 JS 脚本。任务完成后,终端会呈现结构化交付报告:

图 7 钢琴网站任务完成

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

第四步:本地预览与成果验证

在浏览器中打开 index.html,即可直接弹奏由纯代码构建的完整钢琴网站:

图 8 钢琴网站效果

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

第五步:时间线回溯(Timeline)与云端分享

  • 如果代码改错了:在界面输入 /timeline 或在桌面端点击时间轴,可以查阅历史生成的各个版本,点击任意快照即可一键时光倒流:

图 9 Timeline回溯

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

  • 如果想分享成果给团队:输入 /share,OpenCode 会生成一个只读的云端分享链接,网页端完整保留全部对话思考与代码变更过程:

图 10 分享页面

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》


四、核心功能与进阶

1. 斜杠命令速查与会话管理

在 OpenCode 提示符下键入 /,可唤醒功能齐备的操作菜单 [1]:

图 11 斜杠命令菜单

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

  • /sessions:查看当前工作区下的多会话历史列表,支持随时无缝切入与恢复旧任务 [1]:

图 12 会话列表

图源:[1] IvanCodes《开源 OpenCode 上手实测:它到底是不是平替Claude Code?》

  • /compact:压缩当前过长的会话历史,提炼关键结论并丢弃冗余中间输出,防止上下文爆仓 [6]。

  • /provider:打开模型与服务商管理控制台 [1][9]。


2. 免费模型池(Free Model Pool)深度实测

OpenCode 最受新手欢迎的功能便是其内置的免费模型服务 [2][3]。

(1)开启免费模型池

在桌面端设置或 CLI 启动向导中,勾选「Enable Community Free Pool(启用免费模型池)」[2]:

图 13 桌面版启用免费模型

图源:[2] 宁的AI小站《OpenCode 能用免费的 DeepSeek-V4.1-Flash 了,免费池里还有十几个》

系统会列出当前活跃的免费模型规格卡片(包含模型架构、上下文窗口与延迟评级)[2]:

图 14 免费模型规格卡

图源:[2] 宁的AI小站《OpenCode 能用免费的 DeepSeek-V4.1-Flash 了,免费池里还有十几个》

(2)16 个免费模型实测对比结论

根据素材 [3] 的多轮基准评测,免费池中不同模型的实际代码通过率存在差异:

图 15 免费模型实测表

图源:[3] Leonn的手账《OpenCode 实测:16 个免费模型,能跑通 9 个》

  • 表现优异(推荐使用):DeepSeek-V4.1-Flash、Qwen-2.5-Coder-32B、GLM-4-Flash。在单文件开发、Bug 修复与测试用例编写中能稳定跑通,速度飞快 [2][3]。

  • 表现平平(仅适合聊天与简单答疑):部分超轻量 7B/8B 参数模型,在面对多文件大型重构或深层依赖分析时容易发生思维循环 [3]。


3. 重点:接入第三方商业模型与配置指南

对于重度研发任务,挂载稳定的第三方模型是最佳选择。OpenCode 提供了极简的可视化设置与配置文件两种路径 [9]。

(1)桌面端设置界面添加

在桌面版中点击左下角「Settings → Model Providers」[9]:

图 16 桌面版提供商设置

图源:[9] Joey的自由世界《今天不聊Coding!我用 OpenCode桌面版做了一段 3D 动画》

点击「+ Add Custom Provider」,填入:

  • Provider ID:服务商英文标识(如 deepseek、siliconflow、openrouter)。

  • Base URL:服务地址(如 https://api.deepseek.com/v1)。

  • API Key:你的商用秘钥。

  • Models:填入模型技术名称列表。

(2)命令行配置文件结构

OpenCode 在全局目录 ~/.config/opencode/config.json(Windows 为 %USERPROFILE%\.config\opencode\config.json)中维护完整的供应商映射字典:

json
{
  "active_provider": "deepseek",
  "providers": {
    "deepseek": {
      "name": "DeepSeek Official",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
      "models": ["deepseek-chat", "deepseek-reasoner"]
    },
    "anthropic": {
      "name": "Anthropic Claude",
      "base_url": "https://api.anthropic.com/v1",
      "api_key": "sk-ant-xxxxxxxxxxxxxxxxxxxx",
      "models": ["claude-3-5-sonnet-20241022"]
    },
    "local_ollama": {
      "name": "Ollama Local",
      "base_url": "http://localhost:11434/v1",
      "api_key": "ollama",
      "models": ["deepseek-r1:14b", "qwen2.5-coder:7b"]
    }
  },
  "behavior": {
    "auto_approve": false,
    "max_tokens_per_turn": 8192
  }
}

4. 进阶:自然语言联动 MCP 与跨模态制作(以 Blender 为例)

OpenCode 拥有极强的 MCP(Model Context Protocol)扩展生态。开发者可以直接在对话框里对 AI 提出要求,让其自动搜寻并挂载系统级 MCP 服务 [9]:

例如对 OpenCode 输入:

"我想在本地通过 Python 脚本控制 Blender 渲染一套 3D 低多边形场景,请帮我检查并配置 Blender MCP 插件。"

图 17 桌面版提问装MCP

图源:[9] Joey的自由世界《今天不聊Coding!我用 OpenCode桌面版做了一段 3D 动画》

AI 会自动在后台执行配置脚本、连接 Blender 守护进程并调用材质与机位 API,最终一键渲染输出完整的 3D 动效作品:

图 18 Blender场景成品

图源:[9] Joey的自由世界《今天不聊Coding!我用 OpenCode桌面版做了一段 3D 动画》


五、避坑与注意(⚠️ 关键避坑)

1. ⚠️ 2.0 版本架构重构引发的插件兼容性问题

  • 现象:素材 [5] 实测反馈,升级到 OpenCode 2.0 后,虽然启动速度大幅提升了 5.8 倍,但早期为 1.x 开发的非标准社区插件会出现无法加载或全局报错 [5]。

  • 解决策略:升级后建议使用 opencode plugin list 检查老插件状态,对于报错的插件执行 opencode plugin update --all,尽量使用基于标准 MCP 协议开发的扩展 [5]。

2. ⚠️ 上下文超限(Context Overflow)导致的会话卡死

  • 现象:当多轮会话持续产生大量终端输出与长文件 Diff 时,接口容易返回 400 Context window full,甚至出现界面假死 [6]。

  • 避坑建议:

    • 在大项目开发中,养成每完成一个明确子功能就执行 /compact 或开启新会话的习惯 [6]。

    • 在 AGENTS.md 中增加防啰嗦规则:如素材 [7] 验证的技巧——在规则中硬性要求"修改代码时严禁输出完整未改动的上下文函数,仅输出变更差异",可立省 50% Token 并彻底消除爆仓崩溃 [7]。

3. ⚠️ 免费模型池的速率限制(Rate Limit)

  • 现象:在用量高峰期(如北京时间下午或晚间),免费池的部分热门模型可能会返回 429 Too Many Requests [3][4]。

  • 建议:免费池适合日常小修小补和测试验证;如果是关键生产力任务,请配置并切换到商用 DeepSeek 或自建 API Key [4]。


六、参考原文与出处

1. 本文参考微信公众号素材清单

#文章标题与链接来源公众号发布日期配图数为什么入选与核心引用点
1[开源 OpenCode 上手实测:它到底是不是平替Claude Code?]IvanCodes2026-01-293838 张图保姆级教程,系统评测官网下载、npm 安装、主界面、钢琴网站实操、Timeline 回溯与分享(引用图 01~11)
2[OpenCode 能用免费的 DeepSeek-V4.1-Flash 了,免费池里还有十几个]宁的AI小站2026-10-193免费模型池启用指南,详解模型规格卡与免费节点配置(引用图 12、13)
3[OpenCode 实测:16 个免费模型,能跑通 9 个]Leonn的手账2026-10-202严谨的横向基准实测,统计 16 个免费模型在编码任务中的真实通过率(引用图 14)
4[三个月实测弄明白 OpenCode 5 个误区后,我不再焦虑 Token 额度]这也终会过去2026-08-103三个月深度使用总结,讲清资费结构、自备 Key 策略与心理预期管理
5[实测 OpenCode 2.0:配置零改动,启动快 5.8 倍,但插件全挂]智能体折腾日记2026-09-2302.0 大版本升级纪实,客观分析启动加速、底层架构优化与旧插件兼容性陷阱
6[OpenCode上下文超限崩溃?原因、配置、任务快照模板一次收好]阿黎逸阳的代码2026-10-258上下文管理排错宝典,给出任务快照模板、会话压缩与分段工程规范
7[我给opencode加了两段规则,代码少了一半却更好(实测)]神器每日推送2026-10-126高效 Prompt 技巧,演示通过添加精简规则减少冗余代码输出与 Token 消耗
8[耗时半年,5个vibe coding项目沉淀出的opencode使用心得]大饼AI叙事2026-07-280半年实战心得,梳理长期多项目运作中的规则沉淀与目录组织
9[今天不聊Coding!我用 OpenCode桌面版做了一段 3D 动画]Joey的自由世界2026-10-2533桌面版高级场景探索,手把手演示桌面端设置、设备配对、MCP 自动安装与 Blender 3D 渲染(引用图 15、16、17、18)
10[我为什么卸载 OpenCode,转向更轻量的 Pi]Jacky阿猫2026-08-044客观横评对比,讲透 OpenCode 功能大而全与极简 Agent 之间的权衡

2. 官方技术文档与生态规范列表

编号来源与页面名称查阅日期补充与核实用到的核心内容
[官1]OpenCode 官方 GitHub 仓库 (opencode-ai/opencode)2026-11-08官方架构规范、CLI 命令全集、跨平台发布日志与最低环境依赖
[官2]OpenCode Desktop Pairing RFC2026-11-08桌面端与移动端/Web 端端到端加密配对通信协议规范
[官3]OpenCode Community Free Pool Policy2026-11-08社区免费模型池轮转规则、速率控制与模型技术清单
[官4]OpenCode MCP Integration Guide2026-11-08MCP 插件自动安装与工具调度的标准生命周期钩子

3. 本文使用图片清单核对表

图片文件名图片内容说明引用章节对应素材来源
01-官网下载页.png官方网站全平台客户端下载入口第一节 定位[1] IvanCodes
02-npm安装成功.png终端通过 npm 成功安装 OpenCode 全局包确认第二节 3. CLI 安装[1] IvanCodes
03-终端版启动界面.png终端输入 opencode 后展示的主交互界面第二节 3. CLI 安装[1] IvanCodes
04-斜杠命令菜单.png键入斜杠唤醒的快捷操作与配置命令菜单第四节 1. 斜杠命令速查[1] IvanCodes
05-选择模型.png交互式模型切换菜单与供应商列表第三节 上手流程[1] IvanCodes
06-钢琴网站任务完成.png自动编写全套钢琴代码完成后的终端总结报告第三节 上手流程[1] IvanCodes
07-钢琴网站效果.png浏览器内实际弹奏 Web 钢琴网站的视觉效果第三节 上手流程[1] IvanCodes
08-会话列表.png/sessions 查看当前工作区多任务会话面板第四节 1. 斜杠命令速查[1] IvanCodes
09-分享页面.png通过 /share 生成的云端只读任务分享页面第三节 上手流程[1] IvanCodes
10-Timeline回溯.png时间轴版本快照历史与一键代码撤回界面第三节 上手流程[1] IvanCodes
11-init生成AGENTS.pngopencode init 自动生成项目规范文档过程第三节 上手流程[1] IvanCodes
12-桌面版启用免费模型.png桌面客户端设置中开启社区免费模型池选项第四节 2. 免费模型池[2] 宁的AI小站
13-免费模型规格卡.png免费模型池中各模型的参数与上下文规格卡第四节 2. 免费模型池[2] 宁的AI小站
14-免费模型实测表.png16 个免费模型在实际代码开发中的实测对照表第四节 2. 免费模型池[3] Leonn的手账
15-桌面版提供商设置.png桌面客户端管理与添加第三方商业模型界面第四节 3. 接入第三方商业模型[9] Joey的自由世界
16-桌面版Pairing.png桌面端跨设备配对(Pairing)密钥与二维码第二节 2. 桌面客户端安装[9] Joey的自由世界
17-桌面版提问装MCP.png对话中要求 Agent 自主安装与配置 Blender MCP第四节 4. 联动 MCP 与跨模态[9] Joey的自由世界
18-Blender场景成品.png由 Agent 控制 Blender 自动构建渲染的 3D 成品第四节 4. 联动 MCP 与跨模态[9] Joey的自由世界
更新于 2026-11-08来源:用户提供《工具指南_完整全套_含所有MD与图片.zip》;正文保留原文参考来源