我在前面发布的文章中经常用 OpenCode 作为实验环境，用它配合不同模型推进项目，也用它搭过写作 loop、配置 Agent、安装 Skills。后面的文章还会继续出现 OpenCode。
很多同学还不是很了解这个软件，我们一直在讲怎么用它做事，却还没有从头介绍过：OpenCode 到底是什么，为什么选它，以及一个新手怎样迈出第一步。
所以这篇先补上这块基础。
跟着做，你会在 OpenCode 里打开一个本地文件夹，连接一个模型，让 Agent 读取文件并完成第一次修改。更重要的是，你会知道它改了什么、什么时候会产生费用，以及怎样避免刚上手就把权限放得太开。
OpenCode 到底是什么
OpenCode 是一个开源 AI Agent。之前我还写过关于 AI Agent 的内容，想了解这个概念可以接着看。
它也是目前关注度最高的一批开源编程 Agent 之一。OpenHands 团队在 2026 年 6 月发布的一份开源 AI 编程 Agent 对比中，将 OpenCode 称为其统计范围内 GitHub Star 数最多的项目，并记录其 Star 已超过 18.5 万。Star 不等于实际能力，但至少说明它已经不是一个无人使用的小众项目。
普通聊天工具主要给你一段回答，OpenCode 还可以在权限允许的范围内读取本地文件、修改内容、搜索项目并执行命令。
这意味着，你不用每次把文件复制进聊天框，再把回答复制回来。你可以把一个文件夹交给它，直接说：
先看懂这个文件夹里的内容，告诉我它现在是什么状态，并给出下一步方案。先不要修改文件。
它先读取项目，再根据项目里的真实内容回答。确认方案后，你可以让它继续修改文件并检查结果。
虽然官方把 OpenCode 称为编程 Agent（coding agent），但它能处理的不只是代码。只要任务以文件为中心，它就能参与：整理资料、修改 Markdown、分析表格、生成网页、维护项目文档，或者配合 Skills 完成翻译、排版和图片生成。这个公众号把选题、资料、正文、图片方案和发布脚本都放在项目目录里，所以 OpenCode 很适合作为统一入口。
OpenCode 目前有终端界面、桌面应用和 IDE 扩展。本文只讲桌面版。它保留了同一套 Agent 能力，但不用先学习终端命令，更适合大多数的同学上手。
为什么这里经常选 OpenCode
我持续使用 OpenCode，主要看中这几点：
- 开源免费：客户端采用 MIT License，不需要购买软件许可证；
- 模型自由：可接 OpenCode Zen、DeepSeek、Z.AI（GLM）、MiniMax、OpenRouter 等服务；
- 支持本地模型：可连接 Ollama、LM Studio、llama.cpp；
- 可以免费起步：Zen 当前提供部分免费模型，适合先体验；
- 纯净无广告：桌面版界面简洁，没有广告干扰。
费用可以按四种情况理解：
| 使用方式 | 主要成本 |
|---|---|
| OpenCode 客户端 | 免费 |
| Zen 免费模型 | 不收模型调用费，但可能限时开放，并有单独的数据政策 |
| Zen 付费模型或自带 API Key | 按对应模型和服务商的用量规则计费 |
| Ollama 等本地模型 | 通常没有 API 调用费，但会占用自己的硬件、电力和时间 |
OpenCode 的优势是把软件和模型分开。你可以先用当前可用的免费模型体验，再决定是否付费、为哪个模型付费。
第一步：安装桌面版
先打开官方下载页：
截至 2026 年 7 月 22 日，官方下载页列出了以下入口：
- macOS Apple Silicon；
- macOS Intel；
- Windows x64；
- Linux
.deb； - Linux
.rpm。
GitHub Releases 还可能提供其他架构和格式的安装包，完整列表以官方下载页和官方 Releases 为准。
Mac 用户如果安装了 Homebrew，也可以运行：
brew install --cask opencode-desktop不确定自己的 Mac 属于哪一种，可以点左上角苹果菜单，选择“关于本机”。芯片显示 M1、M2、M3、M4 或后续 M 系列，就下载 Apple Silicon 版；显示 Intel，就下载 Intel 版。
Windows 用户可以直接安装和使用桌面版，不必先安装 WSL。官方同时建议在 Windows 上使用 WSL，以获得更好的文件系统性能、终端支持和开发工具兼容性；有需要时，桌面版也可以连接运行在 WSL 中的 OpenCode Server。
下载完成后，按普通应用完成安装。尽量只从官网或官方 GitHub Releases 下载，不要使用来历不明的安装包。
还有一个边界要提前知道：OpenCode 官方发展迅速更新非常频繁。它已经能用于实际任务，但界面、按钮位置和部分行为仍可能随着版本更新变化。本文更强调操作逻辑，不依赖某一个版本的像素位置。
图注：安装完成后首次打开 OpenCode Desktop，可以看到新建会话、当前模型和项目入口。
如果输入框中没有 Agent 选择器，可在设置的“通用”页面打开“自定义智能体”，随后即可切换 Plan 和 Build。
图注：打开“自定义智能体”后，输入框中会显示 Agent 选择器；Plan 和 Build 是内置 Agent。
第二步：准备一个练习文件夹
第一次不要直接打开公司的核心代码、客户资料或自己的重要文档。先创建一个单独的练习文件夹，例如：
opencode-practice/
└── notes.txt用系统自带的文本编辑器创建 notes.txt，随便写几行内容：
OpenCode 练习项目
目标：学习让 Agent 读取和整理文件
今天先完成第一次任务打开 OpenCode Desktop，选择这个文件夹作为项目。不同版本的入口可能显示为 Open Project、Open Folder 或类似名称，核心动作都是让 OpenCode 知道这次工作的目录。
图注：从左下角的项目菜单选择 opencode-practice，确认工作目录后再开始会话。
这一步很重要。OpenCode 不是对着整台电脑漫无边界地工作，它以你打开的项目目录为主要工作区。清楚地划定目录，比在 Prompt 里反复提醒“不要碰其他文件”更可靠。
第三步：连接 Provider，选择模型
OpenCode 是 Agent 客户端，自己不等于大模型。
要让它开始工作，需要先连接模型提供商（Provider），再选择具体模型。
桌面版可以从模型选择或连接入口开始配置。第一次使用系统默认选择的是：Zen 免费模型，无需注册登录即可快速体验。
图注：点击输入框下方的模型名称，打开模型选择入口。
图注：模型列表会标出当前可用的免费模型，也可以继续连接 OpenCode Zen 或其他 Provider。
路线一：用 OpenCode Zen 免费模型开始
Zen 默认带有免费模型。免费模型可能限时开放，Zen 的免费模型还涉及一条容易被忽略的边界：官方说明，部分免费端点收集的数据可能用于改进模型，有的明确不适合提交个人或机密信息。
练习可以用免费模型，真实项目要先查看对应模型的数据说明。
路线二：用 OpenCode Zen 付费模型
官方建议新手从 OpenCode Zen 开始。Zen 同时提供免费和付费模型；需要使用付费模型时，按界面提示登录、添加付款信息、创建 API Key，再选择具体模型。
路线三：接入国内模型 API
如果你有 DeepSeek、Z.AI（GLM）或 MiniMax 等服务的 API Key，可以在 Provider 列表中选择对应服务并完成连接。费用由模型服务商按各自规则计算，不是 OpenCode 客户端收费。
API Key 相当于调用模型服务的密码，不要发给别人，不要贴进文章截图，也不要写进会提交到公开仓库的普通配置文件。
路线四：连接本地模型
OpenCode 支持 Ollama、LM Studio、llama.cpp 等本地模型方案。这条路线能减少对云端模型的依赖，但并不等于零成本或开箱即用：你需要下载模型，占用磁盘、内存或显存，还要选择工具调用能力较好的模型。
如果你的目标只是完成第一次体验，先选当前免费模型即可。等理解 Provider、Model 和权限之后，再考虑付费模型、国内模型 API 或本地模型。
第四步：先用 Plan，不急着让它改
图注：Agent 选择器中可以切换 Plan 和 Build；旁边的 Big Pickle 是当前模型。
对话框中会看到 Plan 和 Build 两种内置 Agent。
- Plan 适合阅读、分析和制定方案；
- Build 适合在确认任务后修改文件和执行命令。
它们不是两个模型，而是两种工作方式。具体权限会受到 OpenCode 版本和配置影响，不要仅凭模式名称判断某个操作一定会被允许或拒绝。本文会在 Prompt 中明确要求 Plan 不修改文件，真正执行前再确认工作目录和操作内容。
第一次任务先选择 Plan，然后输入：
请读取这个文件夹里的文件，告诉我它们分别有什么作用。
然后给出一个整理方案：创建 README.md，说明练习目标、现有文件和下一步任务。
先不要修改任何文件。这段 Prompt 包含四类信息：
- 工作对象：当前文件夹；
- 当前动作：先读取；
- 目标结果：规划一份 README；
- 明确边界：暂不修改。
好的 Agent 指令不需要写得很玄。把对象、目标、约束和验收标准说清楚，通常比堆很多“请认真思考”更有效。
图注：Plan 已读取 notes.txt 并给出整理方案，此时项目里还没有创建 README.md。
看看它是否准确读到了 notes.txt，有没有凭空描述不存在的文件。如果方案不合适，直接补充要求。例如：
README 面向第一次接触 OpenCode 的读者，不要使用程序员术语。
保留原始 notes.txt，不要改名或删除。Plan 的价值不是让任务变慢，而是在执行前暴露理解偏差。项目越重要，这一步越值得保留。
第五步：在 Build 前确认操作范围
AI Agent 不只是“回答问题”，它可能真的修改文件和执行命令。第一次切换到 Build 前，再确认三件事：
- 当前打开的是
opencode-practice，不是重要项目； - 文件夹里没有账号、客户资料或其他敏感内容；
- 任务只要求创建
README.md，不修改和删除其他文件。
如果桌面版弹出权限请求，先看清具体操作。界面通常会提供三种选择：
once：只批准这一次；always：当前会话后续遇到匹配操作都批准；reject：拒绝执行。
刚开始尽量选择 once，不要对不理解的操作选择 always。还要注意：没有出现弹窗，不代表 Agent 没有执行操作，是否询问取决于当前版本和权限配置。因此第一次只使用独立练习文件夹，执行后检查文件变化。
OpenCode Desktop 的会话设置中有自动批准权限开关，但它不是逐工具权限编辑器。截至 2026 年 7 月 23 日，如果你希望修改文件和运行 Bash 前都必须询问，仍需在项目的 opencode.json 中设置 edit: "ask" 和 bash: "ask"。这是进阶安全配置，不是完成本教程的前提。
第六步：切到 Build，完成第一次修改
方案确认后，切换到 Build，继续说：
按刚才确认的方案创建 README.md。
完成后检查文件内容，并告诉我实际修改了哪些文件。OpenCode 应该会创建 README.md，而不是只把 Markdown 内容回复在聊天区。打开新文件，检查三个问题：
- 有没有准确使用
notes.txt里的信息； - 有没有改动你没有授权的文件；
- 最终内容是否满足“给新手看”的要求。
图注：Build 完成后，点击右上角按钮展开文件浏览器，可以看到新建的 README.md 和实际内容。macOS 自动生成的 .DS_Store 可以忽略。
不满意时，不必硬着头皮继续叠加修改。你可以明确指出问题，让它只改对应部分。也可以使用撤销功能回退 Agent 在当前会话中的变更，再调整 Prompt 重做。
OpenCode 的快照功能默认开启，用于跟踪 Agent 操作产生的文件变化。但重要项目仍然应该使用 Git 或其他版本管理方式。会话撤销很方便，不应成为唯一备份。
新手先记住这 5 个操作
完成第一次任务后，不用立刻研究复杂配置。先把下面五件事用熟。
1. 打开正确的项目目录
一个任务一个清晰目录。不要把整个用户主目录或堆满私密文件的下载目录直接交给 Agent。
2. Plan 先看，Build 再做
陌生项目、复杂任务和重要文件先规划。简单且可回退的修改再直接执行。
3. 指向具体文件
与其说“改一下文档”，不如说“读取 notes.txt，据此创建 README.md，不要修改其他文件”。范围越清楚，结果越容易检查。
4. 每次都看变更
Agent 说“已经完成”只代表它认为完成了。真正的验收对象是文件内容、差异和运行结果。
5. 不满意就撤销，不要在错误方向上继续堆 Prompt
如果第一步理解错了，后面补十条要求往往只会让上下文更乱。回退，缩小任务，再做一次通常更快。
继续深入学习请看中文实战教程
中文实战教程：https://learnopencode.com/
我讲完了，该你动手了
如果刚好要学习 AI Agent，今天只做一件事：新建一个练习文件夹，用 Plan 让它先看懂，再用 Build 创建一份 README。
完成这一步，前面文章里出现的 loop、Agent、Skills 和 AGENTS.md，才不再是一串悬空的术语。
OpenCode 它真正吸引我的地方，是客户端开源免费，模型和费用可以自己选，项目规则也留在自己的文件里。
第一次任务跑通后，再继续了解 AGENTS.md、Skills 和 MCP：前者保存项目长期规则，Skills 沉淀一类任务的工作方法，MCP 负责连接外部工具和数据源。它们是后续能力，不必一次搞懂，随用随学。不懂的时候就问问opencode，时刻记住你是和AI结伴，你不会的他可能会多问问。
