OpenCode 上手指南：自由选择 AI 模型、Plan/Build 与成本控制

OpenCode 是一款开源 AI 编程工具，可以在项目里读取代码、修改文件和运行命令。它把编程工作入口与模型服务分开，让开发者在同一个工具里选择不同提供商的模型，也支持接入本地模型。

如果你想减少对单一 AI 工具的依赖，OpenCode 的价值在于：保留熟悉的工作流程，按任务、效果和预算选择模型。 工具本身开源免费，云端模型调用通常仍需付费。

截至 2026 年 10 月 25 日核验，OpenCode GitHub 仓库已有 221,403 个 Star。这个数字反映关注量，不能替代对任务效果、成本和权限配置的实际评估。

本文沿用 OpenCode 1 终端文档，介绍模型接入、Plan / Build、回退和首次使用流程。官方文档已区分 V1 与 V2，安装前应确认所需版本。

模型随你选，工具继续用

先把两个概念分开：OpenCode 是帮你读代码、改文件、调用工具的工作入口；模型则负责理解需求、推理和生成内容。

你可以保留这个入口，再按需要选择背后的模型服务。

根据官方接入文档，OpenCode 支持超过 75 家模型提供商，也支持接入本地模型。

注意，75+ 指的是提供商数量，并非只有 75 个模型，更不代表每个模型都适合编程。

它带来的实际变化很容易理解：

• 复杂任务，选你测试过、表现更稳的模型。
• 日常小改，换一个成本更合适的模型。
• 想用本地推理，可以研究 Ollama、LM Studio 等接入方式。

比如，给一个旧项目补文档，和排查跨模块的疑难 Bug，未必需要相同的模型预算。

遇到服务不稳定，也多了一条换提供商的路。具体能选哪些模型，仍取决于接入方式、账号权限和服务可用性。

开源工具免费使用，不等于模型调用免费。

接云端 API，通常仍有对应账单；跑本地模型，也要考虑硬件、速度和效果。代码是否发送到云端，同样取决于你选的服务与配置。

选择更多，才有机会按自己的任务和预算来安排。

它能动手，不只是陪你聊天

如果你还没用过编码 Agent，可以把它理解为：一个能在项目里调用工具的 AI 助手。

你给它一个明确任务，它可以读取相关代码、提出修改、编辑文件，再运行命令检查结果。

在 OpenCode 的终端界面里，你也不需要反复复制粘贴文件。输入 @，就能搜索并引用当前项目中的文件。

例如，把下面的路径换成你项目里的真实文件：

请分析 @src/App.tsx，说明当前路由如何组织，以及增加多语言支持会涉及哪些文件。

输入以 ! 开头的命令，还可以把命令输出带进对话。比如运行 !git status，让它看到当前改动状态。这些交互可对照终端使用文档。

在同一个工作上下文里讨论代码、需求和命令结果，有助于减少手工复制信息，也方便核对修改依据。

先看方案，再决定怎么改

分析项目和修改代码需要不同的操作范围。先明确任务处于哪个阶段，有助于控制改动。

OpenCode 内置的 Plan 和 Build，可以帮助你把分析与实施分开。在默认快捷键下，按 Tab 切换。

Plan：先分析。

适合阅读陌生项目、比较方案、梳理影响范围。默认会限制代码文件的编辑，但允许写入指定的计划文件。

这里要留意，Plan 并不默认拦住所有 Shell 命令，最终行为还受权限配置影响。别把模式名称当成绝对的只读保证，具体见官方权限说明。

Build：再实施。

等你把需求和边界聊清楚，再让它修改文件、执行检查。可执行的操作仍由权限配置约束。

一个值得养成的习惯是，先问它“要改哪些文件、为什么改、怎么验证”，再推进实现。模型换了，这套工作习惯也能继续用。

改错了，也有回退入口

在 Git 项目里，OpenCode 提供 /undo，用于撤销上一轮相关修改；需要恢复时，可以使用 /redo。

这套文件回退依赖 Git。执行过的外部操作，例如发布服务、写入远程数据库，不能指望靠它一起撤销。命令范围可查看官方说明。

日常使用时，我会把任务拆小一点：先处理一个功能，检查差异，运行相关测试，再继续下一步。

这样更容易发现问题，也方便判断：是需求没讲清楚，还是该换一个更合适的模型。

留在熟悉的编辑器里也能用

自由选模型，不必从更换整个开发环境开始。

你可以在 VS Code、Cursor 等支持终端的编辑器里运行 OpenCode，也可以安装对应扩展，配合选中代码传递上下文。具体操作见IDE 集成文档。

团队想进一步尝试自动化，还可以接入 GitHub Actions。

配置好 GitHub 集成、工作流和模型凭据后，在 Issue 或 PR 评论中用 /opencode 或 /oc 发起任务，让它分析问题、尝试修复或提交 PR。它需要事先配置，流程见GitHub 集成文档。

刚开始不用把所有功能都配齐。先拿一个小任务验证效果，再决定要不要放进日常工作流。

用一个小任务上手

下面沿用官方 OpenCode 1 终端文档演示。当前官方文档已区分 V1 和 V2，两者默认都使用 opencode 命令，安装前先确认版本，避免互相覆盖。

安装并进入项目

macOS / Linux 可使用官方安装脚本：

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

已安装 Node.js，也可以选择 npm 方式。两种方式任选其一：

npm install -g opencode-ai

Windows 用户可优先参考官方的 WSL 方案。安装方式与版本区别见官方入门文档。

进入你要处理的项目目录，再启动：

cd /path/to/your/project
opencode

连接服务，选择模型

在 OpenCode 界面中输入：

/connect

选择模型提供商，按提示填入对应凭据。接着输入：

/models

从已配置服务的可用列表中选择模型。以后想换模型，先回到这个入口查看，详见模型选择文档。

告诉它项目规则

首次使用，可以运行：

/init

它会分析项目，并引导创建或更新 AGENTS.md。检查这份文件，把项目背景、代码规范、测试命令补充清楚。

然后切到 Plan，给一个范围明确的任务：

找出项目中负责登录校验的代码。

先说明调用关系，以及增加登录失败次数限制需要改哪些文件。

暂时不要修改代码。

等方案清楚后，再切到 Build 实施。结束时，自己检查变更与测试结果。

第一轮不必挑战整个系统重构。能把一个小问题处理完整，就足够判断它是否适合你。

哪些开发者适合尝试 OpenCode

如果现有工具已经满足需求，可以继续使用。经常比较新模型、希望按任务调整成本，或想在本地模型与云端服务之间选择的开发者，可以用 OpenCode 试一个范围明确的小任务。

评估时，把模型效果、调用账单、权限设置和代码流向放在一起看。选择模型的空间更大，并不意味着每个服务都有相同的能力、价格或隐私条件。

OpenCode 提供的是一个可继续使用的编程入口。先验证一个任务能否完成，再决定是否把更多工作迁移进来。