OpenCode 教程：从安装配置到完成一次代码修改

先选一个你了解的 bug，再接入已有的模型账号。看过一次真实的代码修改及其费用后，再判断是否值得多买一份编程工具订阅。

OpenCode 能做什么？

OpenCode 通过终端界面读取项目、修改文件、运行命令。终端是工作台，接入的模型则是引擎。换一个引擎，推理能力、速度和价格都会变化；它要处理的仍然是你的代码仓库。OpenCode 概览、Ollama 集成

模型提供方是提供模型服务的一方。API 密钥是一种凭证，程序用它访问服务，并将费用记入对应的计费账号。本地模型则通过你自己电脑上的推理服务器运行。这些选择与使用哪种智能体界面是两回事。

模型是否适配，也要靠实际任务检验。工具调用指的是模型请求执行某个动作，比如读取文件或运行命令。OpenCode 提醒，能同时做好工具调用和代码生成的模型相对较少。先用一项小任务验证模型，再考虑让它承担大范围重构。模型选择指南

OpenCode 教程：安装后打开项目

按官方文档安装，然后进入需要处理的代码仓库再启动。如果已经安装 Node.js 和 npm，可以使用文档中的包安装方式：

npm install -g opencode-ai
cd /path/to/project
opencode

把项目路径换成自己的。OpenCode 文档也提供了 curl -fsSL https://opencode.ai/install | bash，推荐的 Homebrew tap 安装命令是 brew install anomalyco/tap/opencode。选择一种安装方式即可。Windows 用户的推荐方案是 WSL，也就是用于运行 Linux 工具的 Windows 环境；文档还列出了 npm、Chocolatey 和 Scoop 安装选项。官方安装与首次运行指南

启动后，OpenCode 会在终端中打开 TUI，即文本用户界面。以 / 开头的命令，包括 /connect，要在这个界面中输入。以 opencode 开头的命令，比如 opencode stats，则在 shell 中运行。

请在 Git 仓库中操作，并先新建一个分支。Git 会记录修改，方便你在提交前查看 diff，也就是具体增加和删除了哪些代码行。

接入已有的模型订阅或 API 账号

运行 /connect，选择模型提供方，按文档完成认证，再运行 /models 选择模型。常见提供方已有预设配置；自定义端点和本地服务器可能需要额外设置。选择模型

这些接入路径来自 OpenCode 公开的提供方文档，并不代表某个付费账号一定能使用哪些具体功能。提供方接入说明

聊天产品的订阅不会自动变成 API 额度。 Anthropic 明确说明，Claude Pro 不包含 Claude Console API 用量。OpenCode 的 Anthropic 章节也提醒不要使用 Claude Pro/Max 认证插件。走这条接入路径时，应使用 Anthropic API 密钥；如果要使用订阅，则使用 Claude Code。OpenAI 同样区分 API token 计费与订阅用量。Claude Pro 计费说明、OpenCode 对 Anthropic 接入的提醒、OpenAI 订阅与 API 价格

如果使用 Ollama，先安装 Ollama 和 OpenCode，再运行 ollama launch opencode 并选择本地模型。只想完成配置而不打开会话，可以运行 ollama launch opencode --config。启动器同时提供本地和云端模型，选择时要确认自己需要哪一种。Ollama 的 OpenCode 配置指南

手动配置本地服务时，OpenCode 的提供方示例使用 @ai-sdk/openai-compatible、本地地址 http://localhost:11434/v1，以及与你实际提供的模型一致的模型 ID。LM Studio 也有单独的配置示例。对于未列出的 OpenAI 兼容服务，先在 /connect 中选择 Other，再在 opencode.json 中配置相匹配的提供方 ID、地址和模型。本地与自定义提供方

用一个真实 bug 跑通首次任务

选一个在智能体动手之前就能说清正确行为的 bug。比如，注册表单不应该接受空邮箱。这比一上来要求重新设计整个应用更适合作为首次任务。

先初始化项目。 运行 /init，它会创建或更新 AGENTS.md。这个 Markdown 文件保存后续智能体会话要遵循的指令。继续操作前，先读一遍生成内容，修正其中的命令和假设。项目初始化

接着，让它先出方案。 按 Tab 切换到 Plan。用 @ 引用仓库中实际的实现文件和测试文件。以空邮箱 bug 为例，可以这样提问：

这只是任务说明示例，并不是已经完成测试的记录。请换成自己项目中的真实 bug 和文件。Plan 通过权限限制文件修改和 shell 命令，但不提供隔离的执行环境。智能体与 Plan 的行为、引用文件

然后，按约定范围实现。 用 Tab 切换到 Build，让它先添加能复现这个 bug 的回归测试，再做最小修复。要求它展示测试在原有行为下失败、修改后通过的结果，再运行相关的现有检查。Build 是默认智能体，启用了工具。Build 智能体

最后，自己审查结果。 阅读 diff，确认测试断言确实对应你期望的行为，并检查是否夹带无关改动。测试通过，如果验证的是错误行为，也说明不了多少问题。让智能体报告实际运行过的命令，以及未能解决的失败项。

如果修改偏离了目标，/undo 可以撤销上一条消息及其改动；/redo 可以恢复已撤销的消息。这两个操作都依赖 Git。撤销与重做

OpenCode 配置：让 AGENTS.md 和规则真正有用

写下一个有能力的开发者在这个仓库中工作时需要知道的事。指令要具体，且可以核验：

• 实际使用的安装、构建、lint 和测试命令；如果执行顺序重要，也要写清。
• 应用代码、共享包和生成文件分别放在哪里。
• 应遵循哪些约定，以及哪些现有模块可以作为参考。
• 什么才算完成，包括相关检查和行为变化的说明。

把项目规则文件提交到仓库，便于团队共用。个人规则放在 ~/.config/opencode/AGENTS.md。如果对应的 OpenCode 规则文件不存在，OpenCode 可以将 CLAUDE.md 作为后备规则文件。规则与文件位置

opencode.json 是配置文件。它的 instructions 数组可以加载已有指导文档，无需把贡献指南再复制到 AGENTS.md。下面的示例还会要求在修改文件和运行 shell 命令前征求确认：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md"],
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

指令文件名要指向项目中实际存在的文件；如果已有配置，请将这些设置合并进去。仅在 AGENTS.md 中写一个其他文件的引用，不会自动加载它的内容。需要加载该文件时，应使用 instructions。自定义指令

规则描述你希望智能体如何工作，权限则决定工具动作能否执行。大多数权限默认是 allow；如果希望操作前弹出确认，需要主动选择相应的权限设置。权限配置

有明确需求时再添加插件

插件是通过事件扩展 OpenCode 的 JavaScript 或 TypeScript 代码，触发事件可以是工具运行，也可以是会话进入空闲状态。你可以用这套机制实现本地任务完成通知，或定制仓库专用的工作流程。插件钩子与示例

只用于某个项目的本地插件放在 .opencode/plugins/，所有项目共用的插件放在 ~/.config/opencode/plugins/。OpenCode 会在启动时加载这些文件。如果使用已发布的 npm 包，将其加入 opencode.json 的 plugin 数组；文档给出的包名示例包括 opencode-wakatime。启动时，Bun 会自动安装包及其依赖。把可执行代码加入开发环境之前，先检查插件源码和维护情况。加载插件

先用内置流程。等你能说清插件会替你省掉哪项重复工作，再添加它。插件装得越多，越可能在获得收益之前先增加配置和排错工作。

OpenCode 和 Zen 的费用怎么算？

把智能体工作流程与模型账单分开看。接入受支持的现有订阅，就使用该账号的访问权限；使用 API 密钥，则由提供方按用量计费；本地推理要考虑电脑性能和运行成本。Zen 是另一种购买模型访问权限的方式，可以按需选择。提供方选项

OpenCode Zen 是按量付费的模型服务。 其公开页面标示，购买 $20 余额需要另付 $1.23 银行卡处理费，因此这笔购买合计为 $21.23，其中 $20 可用于模型调用。页面还说明，请求费用不加价，可设置月度消费上限，余额降至 $5 时会自动充值 $20。这些是余额与支付条款，并非月度订阅价格。充值前请查看当时的条款。Zen 公开价格页

接入时，运行 /connect，选择 OpenCode Zen，按流程完成账号与计费设置，获取 API 密钥并粘贴到 OpenCode，然后使用 /models。如果其他提供方已经能满足需求，就不必接入 Zen。连接 Zen

用 Anthropic API 算一笔会话费用

以通过 Anthropic 直连 API 使用 Claude Sonnet 4.6 的会话为例，可以按其公布的标准费率估算：每百万输入 token 为 $3，每百万输出 token 为 $15。token 是模型处理或生成文本时使用的小单位。假设整个会话的所有请求合计包含 200,000 个未缓存输入 token 和 20,000 个输出 token。Anthropic 模型与工具价格

这只是算术示例，并非 OpenCode 会话实测，也不是修复一个 bug 的承诺价格。它假设使用标准直连 API 费率，没有缓存，也没有额外服务费。计算用量时，要计入请求中的全部内容，包括指令、重复发送的对话上下文和工具结果。缓存读取与写入采用不同费率，换服务或模型也会改变账单。这里没有估算 Zen 的费用。

按这一假定用量，二十次会话合计为 $18，三十次为 $27。作为参照，Claude Pro 在美国公布的价格是每月 $20，包含 Claude Code，但有使用额度限制。这个例子说明，浮动的 API 预算可能在哪个位置超过固定的席位价格；它并不能证明两者的产出或额度相同，也不能据此判断哪一种对你的工作更便宜。Claude Pro 价格与 API 计费区别

在 shell 中运行 opencode stats 可以查看用量与费用统计；查看最近一天则使用 opencode stats --days 1。如果只看某次会话，opencode export 可以让你选择会话并将数据导出为 JSON。请与实际向你收费的服务账单核对；按 token 估算的费用，并不等于订阅内包含任务的价格。用量查询命令

六种值得尝试的任务：按实际价值排序

先从重复发生、且结果容易判断的工作入手。下面是建议尝试的流程，并非已经观测到的节省时间效果。

提供方和流程配置好之后，可以用 OpenCode 的非交互命令 opencode run 接收提示词，执行脚本化任务。等任务已有可靠的验证方法，再做可重复运行的自动化。CLI run 命令

OpenCode、Claude Code 和 Pi 怎么选？

如果模型选择是工作流程的核心，而且你希望开箱即用地获得 Plan、Build 智能体、项目规则和插件支持，可以选 OpenCode。它的提供方菜单让多种服务和本地配置共用一套操作界面。这是对流程适配的建议，并不意味着它生成的代码更好。OpenCode 模型、智能体

如果你主要使用 Claude，希望通过文档支持的终端或 IDE 集成使用 Claude Pro 或 Max 订阅，可以选 Claude Code。Claude 和 Claude Code 共用套餐的使用限额。关于计费方式，可参阅 2026 年 Claude Code 价格指南。Claude 的订阅集成

如果你想要一个更精简的核心，再通过扩展、提示词模板、技能和主题塑造自己的流程，可以选 Pi。Pi 也支持多个提供方，因此仅凭模型选择灵活，就不足以认定 OpenCode 比 Pi 更适合。Pi 的公开介绍说明，规划模式可以通过扩展添加，而不是内置在核心中。我的建议是：想直接使用现成流程，选 OpenCode；希望自己设计更多流程的开发者，可以考虑 Pi。Pi 公开介绍

如果还在比较其他终端智能体，可阅读 Gemini CLI 与 Claude Code 对比。比较时，分别考虑模型访问权限、偏好的工作流程和付款方式。

围绕 OpenCode，可以做哪两种产品或服务？

最值得尝试：针对特定仓库的代码审查流程

小型工程团队可能愿意为一种审查流程付费：它能检查团队反复出现的错误，并给出可复现的证据。需求信号是 “ai code review” 在美国每月约有 1,300 次搜索，来自 2026 年 10 月 4 日核查的 DataForSEO 关键词估算。CodeRabbit 公开的 Essentials 价格为按年付费时每位开发者每月 $24，按月付费时每月 $30，为这一付费品类提供了具体参照。DataForSEO 关键词数据、CodeRabbit 价格

最小可售版本可以加载团队的审查清单和项目指令，检查提供的 diff，再输出一份简短报告，列明文件位置、验证步骤和记录的模型用量。先做成可重复执行的本地命令，再在确实能减少手动操作的地方添加插件钩子。

难点在于竞争和信任。通用的审查封装很难比现有工具多提供多少价值。有潜力的细分场景，需要团队反复使用的领域规则，也需要证据证明建议能减少审查者的工作量。搜索量反映的是对这个品类的兴趣，并不能证明有人需要基于 OpenCode 的产品。这是本文最值得尝试的机会，因为审查会反复发生，而且可以用真实 diff 判断它是否有用。

面向开发服务商、经过验证的 OpenCode 上手套件

开发服务商可能会购买一项配置服务：为每个客户仓库交付可用的提供方连接、准确的 AGENTS.md、最小配置，以及一项已经审查的首次任务。同一次 DataForSEO 核查显示，“open source ai coding assistant” 在美国每月约有 1,600 次搜索，说明这一品类受到关注。DataForSEO 关键词数据

MVP 可以由配置清单和仓库专用配置组成，以成功运行的验证命令和清楚的计费路径作为交付内容。不必再做一个大而全的编程智能体界面。难点在于，免费文档已经覆盖安装步骤，搜索兴趣也不能证明付费意愿。只有开发服务商认可这项工作，才适合为客户专用配置及持续维护的交接内容收费。

哪些判断仍然需要你来做？

OpenCode 无法替你确定模型是否理解了业务需求。测试、代码审查和部署判断仍由你负责。换一个提供方，也需要重新检查输出质量和实际费用。

本地推理省去托管模型账单，同时增加对硬件性能和配置工作的要求。本地智能体界面如果接的是云端提供方，模型请求仍会发送给该提供方。在哪里运行推理，与在哪里输入提示词，要分开决定。

对于你本来就知道如何完成的小改动，配置和审查这一轮流程可能比修改本身更耗精力。需求还模糊时，先定义验收标准，再让智能体实现。真正有价值的是一次正确、经过审查的修改。

周一就做这件事： 选一个可复现的 bug，新建分支，接入一个提供方，完成读取、规划、编辑、测试和审查这一轮流程。记下用了哪个模型、哪些检查通过，以及会话如何计费。这些记录能为下一次工具选择提供依据。

如果你希望为团队定制针对特定仓库的编程或审查流程，可以进一步了解 AI 智能体开发。