OpenCode 用法：开源代理，国产模型随便接

前两课的 Claude Code 和 Codex，分别绑着 Anthropic、OpenAI 两家的模型和订阅；这一课 12 分钟，看开源阵营的 OpenCode——工具本体开源免费，模型随便接：DeepSeek、Kimi、智谱、通义这些国产厂商全在官方模型目录里，手里有谁的 key 就用谁。本篇 OpenCode 教程聚焦 CLI 这个主形态——官方定位「开源 AI 编码代理」，另有桌面版和网页版，一句带过。（事实核对时间 2026-11-05；模型目录与命令会随版本更新，以官方文档为准。）

学完你能做什么

在 macOS / Linux 上装好 OpenCode CLI（Windows 用官方独立二进制），项目目录里一键启动
用 /connect 接入模型：DeepSeek、Kimi、智谱、通义等国产厂商都在官方目录里，粘贴 API key 即用
用 /models 选模型、派第一件活，看它自己读文件、改代码、跑命令
顺手操作：@ 引用文件、! 直接跑 shell、/undo 吃后悔药
用 opencode stats 盯用量、opencode upgrade 升级，凭证管理用 opencode auth

你现在的困境

Claude Code 要 Claude 订阅、Codex 要 ChatGPT 账号；我手里现成的是 DeepSeek / Kimi / 智谱的 API key
网页版聊代码，文件来回复制粘贴，改完还得自己粘回去
听说 OpenCode 是开源又免费的 AI 编程工具，装完却一脸懵：模型从哪来？终端界面怎么用？

什么时候用这一招

当你需要：

一个不绑定模型厂商的开源编码代理——谁的 API key 都能接，国产模型直接用
用现成的国产模型账号（API 按量或 Coding Plan 套餐）驱动终端里的代理
工具本体开源：源码公开在 github.com/anomalyco/opencode，想改就改

而且不想：

为用编码代理专门办海外订阅
在网页聊天框里来回搬运代码和报错
被单一模型生态锁死——今天 DeepSeek 明天 Kimi，换个 key 就换模型

🎒 开始前的准备

看过日常使用导读，知道本页讲的是四款工具里的 OpenCode（开源阵营）
至少一个模型账号：国产厂商（DeepSeek / Kimi / 智谱等）的 API key，或 ChatGPT Plus / Pro 订阅，或先连 OpenCode Console 用免费模型试水——各条路的花费见价格对比
一个练手项目目录（cd 进去就能开工的那种）
12 分钟不被打扰的时间

💡 前两课不是前置条件

本课只要求看过日常使用导读。Claude Code 用法和 Codex 用法与本课互相独立，但「像派活一样说清一件事」的心法通用。

核心思路

OpenCode 的官方定位一句话讲清：开源 AI 编码代理（open source AI coding agent），有终端、桌面、网页三种形态。它和前两课最根本的区别：模型不绑定。Claude Code 走 Claude 模型、Codex 走 GPT 模型；OpenCode 本体只是个「代理壳」，模型目录来自 models.dev，上百家国内外厂商任你接——这正是它对国内用户最友好的一点：目录里专门收了大量中国厂商和国内套餐。

和前两课摆在一起看：

	Claude Code	Codex	OpenCode
模型	Claude 系列	GPT 系列	不绑定：models.dev 目录上百家厂商任接
付费	Claude 订阅或 API key	ChatGPT 订阅或 API key	本体开源免费，模型费付给你接的厂商（另有可选订阅 OpenCode Go）
源码	闭源	闭源	开源（github.com/anomalyco/opencode）
形态	终端 / IDE / 桌面 / 网页	CLI / IDE / 桌面 / 网页	终端 / 桌面 / 网页

用法一句话：先 /connect 连账号，再 /models 选模型。凭证有四种接法：

凭证方式	怎么工作
API key	粘贴密钥，保存为该厂商的账号
OAuth	弹浏览器或设备码授权
命令	跑厂商提供的取钥命令，输出存为 key
环境变量	从服务进程读变量，不落盘保存

三种形态一句带过：除了 CLI，OpenCode 还有桌面版（官网下载安装包）和网页版（opencode pair 生成一次性登录链接，5 分钟内有效、用一次即失效）——本课不展开，CLI 是主线。

和 Claude Code、Codex 怎么选、怎么搭？ 想用谁家模型就选谁的官方工具；手里是国产模型 key、或者不想被单一生态绑住，OpenCode 是对位选择。搭着用完全可行——三款都有项目说明书机制，OpenCode 认 AGENTS.md（和 Codex 同一份文件通用，详见 AGENTS.md 与 CLAUDE.md）；四款工具怎么选的完整对比见工具对比，费用全表见价格对比。

跟我做

第 1 步：安装 OpenCode CLI

为什么：OpenCode 是独立安装的命令行工具，先装上才有后面的一切。

方式 A：官方安装脚本（推荐，macOS / Linux）

bash

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

方式 B：包管理器（macOS / Linux）

bash

brew install anomalyco/tap/opencode-v2

bash

npm install -g @opencode/cli

npm 包靠 postinstall 脚本挑选你平台的二进制：pnpm 要显式放行（pnpm add -g --allow-build=@opencode/cli @opencode/cli），bun 要加信任（bun install -g --trust @opencode/cli）；另有 yarn、AUR（paru -S opencode-beta）、mise 等通道（mise 需 2026.10.9 或更新版本，旧版装到的是 OpenCode 1）。

Windows 用户：独立二进制或桌面版

官方明确「Windows 包管理器不受支持」。两条路：从官网下载独立 CLI 二进制（zip，分 ARM64 / x64），解压即用；或直接装桌面应用。

装完验证：

bash

opencode --version

你应该看到：终端打出版本号。

小检查：opencode --version 能打出版本号

第 2 步：启动 OpenCode，认识终端界面

为什么：OpenCode 的主形态是全屏终端界面（TUI），第一次启动认识一下，后面所有操作都在这。

bash

cd /path/to/your/project
opencode

你应该看到：全屏终端界面，底部是输入框。直接打字描述任务、按 Enter 发送；换行用 Shift+Enter（或 Ctrl+Enter / Alt+Enter / Ctrl+J）。

不想全屏？还有两个入口：

入口	命令	适合
极简界面	`opencode mini`	喜欢朴素输入框的人
脚本 / CI 单发任务	`opencode run "Explain this repository"`	不开界面，输出直接进终端

小检查：我在项目目录里启动了 opencode，看到输入框并能打字

第 3 步：OpenCode 教程核心——用 /connect 接入国产模型

为什么：OpenCode 本体不带模型，接上你的账号才算「活」。而国产模型正是它的强项：官方模型目录（来自 models.dev）里收了一大批中国厂商和国内套餐——这是选它而非前两课工具的最大理由。

会话里输入：

text

/connect

你应该看到：厂商选择列表。选一个厂商（比如 DeepSeek），按提示粘贴 API key。

国产厂商目录（节选；同一厂商常有国际版 / 国内版 / 套餐版多个条目，认准你开通的那个）：

厂商	目录里的条目（举例）	凭证环境变量
DeepSeek	DeepSeek	`DEEPSEEK_API_KEY`
月之暗面 Kimi	Moonshot AI (China)、Kimi For Coding	`MOONSHOT_API_KEY` / `KIMI_API_KEY`
智谱 AI	Zhipu AI、Zhipu AI Coding Plan、Z.AI	`ZHIPU_API_KEY`
阿里通义	Alibaba (China)、Alibaba Coding Plan	`DASHSCOPE_API_KEY` / `ALIBABA_CODING_PLAN_API_KEY`
MiniMax	MiniMax (minimax.cn)、MiniMax Token Plan	`MINIMAX_API_KEY`
字节火山方舟	Volcengine Ark、Volcengine Ark Coding Plan	`ARK_API_KEY` / `ARK_CODING_PLAN_API_KEY`
硅基流动	SiliconFlow (China)	`SILICONFLOW_CN_API_KEY`
腾讯	Tencent Coding Plan (China)	`TENCENT_CODING_PLAN_API_KEY`
阶跃星辰	StepFun (China)	`STEPFUN_API_KEY`
ModelScope（魔搭）	ModelScope	`MODELSCOPE_API_KEY`

以 opencode 接入 deepseek 为例，不开界面也能连（厂商 ID 就是目录里的名字）：

bash

opencode auth login deepseek --method key

你应该看到：提示输入 API key，粘贴后保存为账号。

连完检查：

bash

opencode auth list

你应该看到：已连接的厂商账号列表。

💡 手里一个 key 都没有？先蹭官方免费模型

小检查：opencode auth list 里能看到我刚连的厂商

第 4 步：/models 选模型，派第一件活

为什么：连上厂商只是「有了货源」，还要告诉 OpenCode 这次用哪个模型。选完就能像前两课一样派活。

会话里输入：

text

/models

你应该看到：你已连接厂商的模型列表（比如 DeepSeek 目录下的 DeepSeek V4.1 Flash 1017 等），选中即切换，只对当前会话生效。

派第一件活——和 Codex 课一样，先让它给你讲讲这个项目：

text

Explain how authentication works in this project

你应该看到：OpenCode 自己去读文件、列出项目结构；让它改代码时它直接编辑文件，需要验证时在本地跑命令。

想换模型随时 /models（或按 Ctrl+X 再按 M；F2 在最近用过的模型间循环）。

小检查：/models 里能看到我连的厂商的模型，并选中了一个

第 5 步：日常顺手操作——@ 引文件、! 跑命令、/undo 后悔药

为什么：代理用不用得顺手，看的是这些小动作。OpenCode 的日常操作一张表收全：

想做什么	操作
引用某个文件	`Review @src/auth.ts for error handling problems`（可带行号 `@src/auth.ts#20-45`）
直接跑 shell	`!git status`（输出留在会话里，它看得见）
列出所有命令	输 `/`；Ctrl+P 打开命令面板
新起会话	`/new` 或 Ctrl+X 再按 N
回到旧会话	`/sessions`
吃后悔药	`/undo` 撤销上一条消息和它干的活；`/redo` 恢复
问个「不算数」的小问题	`/btw why did the test in step 2 fail?`（答案不进上下文）

你应该看到：@ 弹出文件搜索列表，越输越窄；! 进 shell 模式，Esc 退出不执行。

小检查：我用 @ 引用过文件、用 ! 跑过命令、用 /undo 撤销过一次

第 6 步：管好账号、用量与更新

为什么：OpenCode 是「工具归工具、模型费归厂商」——账号连了几个、钱花在哪，得心里有数。

bash

opencode auth list
opencode stats
opencode stats --cost

你应该看到：auth list 列出已保存账号；stats 给出可分享的用量统计，加 --cost 看费用明细。

升级版本：

bash

opencode upgrade

凭证安全两句话：API key 和 OAuth 令牌存在本地 SQLite 数据库里（路径用 opencode debug paths db 查，通常是 ~/.local/share/opencode/opencode.db）；别手动改库，增删账号一律走 /connect 或 opencode auth 命令。

小检查：opencode stats 能看到我的用量

检查点 ✅

opencode --version 打出版本号，项目目录里能启动终端界面
/connect 接上了至少一个厂商，opencode auth list 能看到它
/models 选好了模型，派了第一件活，看到它自己读文件、改文件
会用 @ 引文件、! 跑命令、/undo 撤销
opencode stats 能看到用量，知道凭证存在哪、怎么管

踩坑提醒

❌ Windows 上用包管理器装不上

官方文档写得明白：「Windows 包管理器不受支持」。正确做法：从官网下载独立 CLI 二进制（zip 解压），或装桌面应用；别在 winget / scoop 上浪费时间。

❌ pnpm / bun 装 npm 包时脚本被拦，装完跑不起来

npm 包靠 postinstall 脚本挑选平台二进制，pnpm 默认拦脚本、bun 默认不信任。放行方式：pnpm add -g --allow-build=@opencode/cli @opencode/cli、bun install -g --trust @opencode/cli。npm 用户不受影响。

❌ ChatGPT 套餐登录后感觉「模型变笨了」

OpenCode 默认给 ChatGPT 登录的模型加了上下文上限（GPT-6.1 Sol 及更新模型 500,000，更旧模型 272,000），与 Codex 的默认值对齐，免得套餐用量消耗过快。确实想放开，在配置里关掉这个内置插件：

jsonc

{ "plugins": ["-opencode.provider.openai-context-caps"] }

（- 前缀表示只关这一个内置插件，其他插件不受影响。）

❌ 把 API key 明文写进配置文件，还提交进了仓库

凭证应该走 /connect 或 opencode auth login 保存（进本地数据库），或用环境变量传给服务进程；写进 opencode.jsonc 再提交 git 等于把钥匙插在门上。临时用环境变量也行：DEEPSEEK_API_KEY=<你的key> opencode --standalone。

进阶技巧（可选）

给项目留一份「说明书」。 在项目根目录放 AGENTS.md，写上构建命令、代码约定、验证要求，每次会话 OpenCode 都会先读；全局版放 ~/.config/opencode/AGENTS.md。注意：V2 只认 AGENTS.md，不认 CLAUDE.md。写法详解见 AGENTS.md 与 CLAUDE.md：给 AI 留一份项目说明书。

接本地模型，完全离线。 装了 Ollama 的话，ollama serve 起服务、ollama pull qwen3:8b 拉模型，OpenCode 自动发现 127.0.0.1:11434 上的模型，无需连账号；LM Studio 和 vLLM 也有内置发现。

目录里没有的厂商，自己加。 OpenAI 兼容的 API 都能用自定义厂商接进 opencode.jsonc：

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "acme": {
      "name": "Acme",
      "env": ["ACME_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": { "baseURL": "https://llm.acme.example/v1" },
      "models": { "qwen3-coder": { "name": "Qwen 3 Coder" } }
    }
  }
}

已有 ChatGPT 订阅？直接用。 /connect 选 OpenAI，登录方式选 Sign in with ChatGPT——用量算进你的 Plus / Pro 套餐，模型显示为无费用。

想要「包月随便用」？看 OpenCode Go。 官方打包的一批编码模型订阅：Go $10/月、Go Plus $40/月、Go Teams $20/成员/月，在控制台订阅后像普通厂商一样 /connect 连接。完全可选，不订不影响任何功能。

脚本和 CI 里跑。 opencode run 单发任务不开界面：opencode run --model anthropic/claude-sonnet-5-5 "Refactor parseToken"；加 --continue 接着上一会话继续。

本课小结

✅ OpenCode 教程的日常主线 = 装好 CLI → /connect 接模型（国产厂商随便挑）→ /models 选模型 → 派活 → @/!//undo 顺手操作 → stats 盯用量。

✅ 它是开源代理不绑定模型：本体免费开源，模型费付给你接的厂商；国产模型目录最全——DeepSeek、Kimi、智谱、通义、MiniMax、火山方舟、硅基流动、腾讯、阶跃、ModelScope 都在。

✅ 三种形态：CLI（本课主线）、桌面版、网页版（opencode pair 一次性链接，5 分钟内有效）。

✅ 凭证四种接法（API key / OAuth / 命令 / 环境变量），账号凭证存本地 SQLite 数据库（环境变量不落盘），管理只走 /connect 和 opencode auth 命令。

✅ 项目说明书认 AGENTS.md 不认 CLAUDE.md——和 Codex 共用同一份文件，换工具不用重写。

关键操作回顾：

操作	怎么做	说明
安装	`curl -fsSL https://opencode.ai/v2/install \| bash`	备用：brew、npm；Windows 用独立二进制
启动	项目目录里 `opencode`	极简版 `opencode mini`；脚本 `opencode run`
连模型	`/connect` 选厂商粘贴 key	命令行方式 `opencode auth login <厂商> --method key`
选模型	`/models`	只对当前会话生效；F2 循环最近模型
引文件 / 跑命令	`@src/auth.ts` / `!git status`	`@` 可带 `#20-45` 行号
撤销	`/undo`、`/redo`	撤掉上一条消息和它干的活
查用量	`opencode stats`、`opencode stats --cost`	升级用 `opencode upgrade`

下一课预告

命令行用到现在，最后一课给完全不想碰终端的人：WorkBuddy 用法：腾讯出品的桌面 AI 工作台。

你会学到：

WorkBuddy 是什么：腾讯出品的桌面 AI 工作台，微信扫码就能登录
不写命令行怎么让 AI 做网站、做小程序
积分怎么算、套餐怎么选
四款工具费用全表见价格对比

OpenCode 用法：开源代理，国产模型随便接 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

跟我做 ​

第 1 步：安装 OpenCode CLI ​

方式 A：官方安装脚本（推荐，macOS / Linux） ​

方式 B：包管理器（macOS / Linux） ​

Windows 用户：独立二进制或桌面版 ​

第 2 步：启动 OpenCode，认识终端界面 ​

第 3 步：OpenCode 教程核心——用 /connect 接入国产模型 ​

第 4 步：/models 选模型，派第一件活 ​

第 5 步：日常顺手操作——@ 引文件、! 跑命令、/undo 后悔药 ​

第 6 步：管好账号、用量与更新 ​

检查点 ✅ ​

踩坑提醒 ​

❌ Windows 上用包管理器装不上 ​

❌ pnpm / bun 装 npm 包时脚本被拦，装完跑不起来 ​

❌ ChatGPT 套餐登录后感觉「模型变笨了」 ​

❌ 把 API key 明文写进配置文件，还提交进了仓库 ​

进阶技巧（可选） ​

本课小结 ​

下一课预告 ​

OpenCode 用法：开源代理，国产模型随便接

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

跟我做

第 1 步：安装 OpenCode CLI

方式 A：官方安装脚本（推荐，macOS / Linux）

方式 B：包管理器（macOS / Linux）

Windows 用户：独立二进制或桌面版

第 2 步：启动 OpenCode，认识终端界面

第 3 步：OpenCode 教程核心——用 /connect 接入国产模型

第 4 步：/models 选模型，派第一件活

第 5 步：日常顺手操作——@ 引文件、! 跑命令、/undo 后悔药

第 6 步：管好账号、用量与更新

检查点 ✅

踩坑提醒

❌ Windows 上用包管理器装不上

❌ pnpm / bun 装 npm 包时脚本被拦，装完跑不起来

❌ ChatGPT 套餐登录后感觉「模型变笨了」

❌ 把 API key 明文写进配置文件，还提交进了仓库

进阶技巧（可选）

本课小结

下一课预告