安装 OpenCode 2，用免费模型改代码并跑通测试

这一课做完你会得到什么

装好 OpenCode 2，在一个小 Python 仓库里先让它只读解释代码，再让它改代码、写测试、自己把测试跑通。全程用 OpenCode 自带的免费模型，不需要注册账号，也不需要填任何 API Key。

OpenCode 2 是什么

OpenCode 是开源（MIT）的 AI 编程智能体，有终端界面、桌面应用和网页三种用法，仓库在 https://github.com/anomalyco/opencode 。2026 年 9 月发布的 2.0 换了一套新文档站，地址在 /v2/docs/ 下。对使用者影响最大的几点：

V1 和 V2 都叫 opencode 命令，默认不能同时装。用包管理器装过 V1 的，先卸掉再装 V2。

第 1 步：安装

官方给了多种装法，任选一种：

# macOS / Linux 一键脚本（会替换已有的 V1 二进制）
curl -fsSL https://opencode.ai/v2/install | bash

# Homebrew
brew install anomalyco/tap/opencode-v2

# npm（postinstall 会挑选对应平台的原生二进制）
npm install -g @opencode/cli

官方明确写了不支持 Windows 包管理器，Windows 用户请到官网下载独立二进制或桌面版。装完确认版本：

opencode --version

对照结果（2026-10-26 实测，npm 安装）：

opencode v2.1.4

再看一眼 OpenCode 把数据放在哪里。这条命令不会启动服务：

opencode debug paths

对照结果（2026-10-26 实测，Linux，节选）：

config     /home/box/.config/opencode
data       /home/box/.local/share/opencode
log        /home/box/.local/share/opencode/log
db         /home/box/.local/share/opencode/opencode.db

config 是全局配置目录，第 2 课会用到。会话记录存在 db 指向的 SQLite 文件里。

第 2 步：看看能用哪些模型

模型统一写成 provider/model 格式，比如 opencode/deepseek-v4.1-flash-free，斜杠前面是提供方。没登录任何账号时，就能看到 OpenCode 自带的免费模型：

opencode models

对照结果（2026-10-26 实测，未登录，节选）：

opencode/big-pickle
opencode/deepseek-v4.1-flash-free
opencode/glm-5.3-flash-free
opencode/mimo-v2.6-flash-free
opencode/nemotron-3-ultra-free

免费模型的几条限制，按官方 Zen 页面整理：

• 都是「限时免费」，名单会变，以你自己 opencode models 的输出为准。
• 官方写明 GLM-5.3-Flash Free 和 DeepSeek V4.1 Flash Free 的提供方零留存，不用你的数据训练。
• MiMo、Nemotron 和 Big Pickle 的免费期，官方明说是在「收集反馈、改进模型」。公司代码别用这几个。
• 免费额度有上限，用完会报错，见本课最后一节。

第 3 步：准备一个练习仓库

快照和撤销功能需要 Git 仓库，所以先建一个：

mkdir hello-opencode && cd hello-opencode
git init -q
cat > stats.py <<'PY'
def mean(numbers):
    return sum(numbers) / len(numbers)
PY
git add . && git commit -qm init

第 4 步：用 opencode run 先问、不改

opencode run 不打开全屏界面，直接把一句话交给智能体，适合脚本和 CI。-m 指定模型：

opencode run -m opencode/deepseek-v4.1-flash-free \
  "解释 stats.py 做了什么，有什么边界问题？不要改文件，3 句话以内。"

对照结果（2026-10-26 实测，模型输出每次会略有不同）：

> build · deepseek-v4.1-flash-free
$ cat stats.py
...
`stats.py` 只定义了一个 `mean(numbers)` 函数……边界问题：传入空列表会因
除零抛 `ZeroDivisionError`；非数值元素会抛 `TypeError`；传入生成器时……

第一行的 build 是默认智能体的名字。注意它没有问你就执行了 cat stats.py 和 ls -la。这是 V2 的默认策略：build 智能体默认放行所有工具，只有读取 .env 这类文件时才会先问你。想让它跑命令前先问，要自己配权限，第 2 课会讲。

第 5 步：让它改代码、写测试、跑测试

opencode run -m opencode/deepseek-v4.1-flash-free \
  "给 stats.py 的 mean 加上空列表检查（抛 ValueError），再新增 median \
函数；在 test_stats.py 写 pytest 测试，用 uv run --with pytest pytest -q \
跑通后用一句话汇报结果。"

对照结果（2026-10-26 实测，约 15 秒，节选）：

→ Read stats.py
← Write test_stats.py
← Write stats.py
$ uv run --with pytest pytest -q
......                                                     [100%]
6 passed in 0.01s
`stats.py` 的 `mean` 现在会对空列表抛出 `ValueError`，`median` 也已新增……

自己核对一下改动，别只看它的汇报：

git status --short
uv run --with pytest pytest -q

对照结果（2026-10-26 实测，git status 部分）：

 M stats.py
?? test_stats.py

自己再跑一次 pytest，结果应和智能体汇报的一样，是 6 passed。

确认没问题就提交，留一个干净的回退点：

git add stats.py test_stats.py && git commit -qm "add median"

第 6 步：继续上一次会话

每次 opencode run 都会新建一个会话。想接着上次的上下文追问，用 -c（--continue）：

opencode run -c "刚才的 median 对偶数个元素是怎么处理的？一句话。"
opencode session list

session list 按时间倒序列出当前项目的会话，第一列是会话 ID，可以用 -s <ID> 回到某个会话。-c 追问那一步本机没有重跑，因为免费额度已经用完（见本课最后一节）。session list 的对照结果（2026-10-26 实测，格式示例）：

ses_e8c267d51ffeHNagSiWq5TKBD9	Untitled session	10/26/2026, 12:16:52 AM

第 7 步：打开全屏界面（TUI）

在项目目录直接运行 opencode 就进入全屏界面。下面几条斜杠命令出自官方文档（交互界面没法在服务器上截取输出）：

/undo 能恢复文件，靠的是 Git 仓库里的快照。在非 Git 目录里，它只能回滚对话，改过的文件恢复不了。想要更简洁的界面可以用 opencode mini，想在浏览器里用就运行 opencode pair，它会打印一次性登录链接。

免费额度用完时会看到什么

免费模型按账号或网络限额。用完后，换另一个免费模型也会报同样的错：

Error: Free usage limit reached. Connect a provider or subscribe to OpenCode
Go to keep going, or switch models.

对照结果（2026-10-26 实测）：--format json 模式下，这个错误的 status 是 429，还带一个 retryAfterMs 字段，告诉你多久后恢复。想继续用，有三条路：

• 等额度恢复：什么都不用做。
• 订阅 OpenCode Go：官方价 $10/月，Go Plus $40/月。用 /connect 选 OpenCode Go，粘贴 Key。
• 接自己的模型：第 2 课讲怎么接 OpenAI 兼容接口和本地 Ollama。

本课小结

• 安装：curl -fsSL https://opencode.ai/v2/install | bash 或 npm i -g @opencode/cli。
• 免费模型：opencode models 列出可用模型，-m provider/model 指定。
• 一次性任务：opencode run "…"。追问用 -c，回到旧会话用 -s。
• 默认权限：build 智能体默认不问就执行命令，正式项目要先配权限。