2. 安装与模型配置

这是什么：安装 = 把 opencode 变成一条能敲的 opencode 命令；模型配置 = 告诉它用哪家模型、拿哪把钥匙。

为什么用：opencode 自己不带模型，不配 API Key 它连一句话都说不出来；而 Windows 上装错方式，会撞上一串莫名其妙的终端兼容问题。

如何用：本章先用官方脚本或 npm 把命令装上，再走一遍 /connect 接模型，最后搞清 opencode.json 该放在哪。

2.1 前置：两样东西

1. 一个像样的终端：WezTerm、Alacritty、Ghostty、Kitty 都行。opencode 是全屏 TUI（终端用户界面）应用，Windows 自带的 cmd 渲染会明显不对味。
2. 模型提供商的 API Key：OpenAI、Anthropic、DeepSeek、OpenRouter……或者一个本地模型端点，用哪个由你决定。

2.2 安装：挑一种方式

# ① 官方安装脚本（Linux / macOS 最省事）
curl -fsSL https://opencode.ai/install | bash

# ② npm（已有 Node 环境就选它）
npm install -g opencode-ai

# ③ Homebrew（macOS / Linux）
brew install anomalyco/tap/opencode

# ④ Arch Linux
sudo pacman -S opencode      # 稳定版
paru -S opencode-bin          # AUR 的最新构建

你会看到（示意）：

  opencode installed
  version: 1.19.3

  run `opencode` to start

几点补充：

• npm 换成 bun add -g、pnpm add -g、yarn global add 一样能装。
• 安装脚本 opencode.ai/install 实际跳转到 GitHub 的发布文件（307 → raw.githubusercontent.com），网络不畅时可能拉不动——卡住就换 ② npm 方式，装出来的是同一个东西。
• Homebrew 务必用 anomalyco/tap/opencode，官方 brew install opencode 由 Homebrew 团队维护、更新比 tap 慢。
• Windows 还可以 choco install opencode、scoop install opencode，或者直接 docker run -it --rm ghcr.io/anomalyco/opencode。

⚠️ 版本互斥：opencode 这个命令，OpenCode 1 和 OpenCode 2 默认不能并存。安装脚本可能覆盖或替换掉你已有的 V2 安装，升级前先想清楚。

2.3 Windows 用户：请用 WSL

官方明确推荐 WSL（Windows Subsystem for Linux，Windows 的 Linux 子系统）：文件系统更快、终端功能更全、和各种开发工具兼容性更好。

# 在 WSL 终端里安装
curl -fsSL https://opencode.ai/install | bash

# 访问 Windows 盘符：C 盘是 /mnt/c，D 盘是 /mnt/d
cd /mnt/c/Users/YourName/project
opencode

你会看到（示意）：

  opencode v1.19.3
  project: /mnt/c/Users/YourName/project

小提示：直接把仓库 clone 到 WSL 自己的文件系统（比如 ~/code/）通常比放在 /mnt/c/ 里快得多。

2.4 验证安装

opencode --version
opencode --help

你会看到（示意）：

1.19.3

2.5 接模型：/connect 三步

启动 opencode 后，在输入框敲：

/connect

然后依次：① 选提供商 → ② 粘贴 API Key → ③ 回到输入框敲 /models 挑一个模型。

Key 会被存到 ~/.local/share/opencode/auth.json。不想进图形界面也可以走命令行：

opencode auth login     # 登录某个提供商
opencode auth list      # 看已登录的提供商
opencode models         # 列出可用模型（provider/model 形式）

你会看到（示意）：

$ opencode models anthropic
anthropic/claude-sonnet-4-5
anthropic/claude-haiku-4-5
anthropic/claude-opus-4-5

不知道 provider 叫什么？先看官方 Providers 目录，或者直接 opencode models 全量列出来。

2.6 配置放哪：opencode.json

多个配置文件会合并而不是互相覆盖，项目级覆盖全局级。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

你会看到（示意）：

$ opencode debug config
{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

$schema 那一行别删——它让编辑器能自动补全和校验字段名。small_model 专门跑「给会话起标题」这类轻活，省钱。

密钥别硬写进文件，用 {env:...} 读环境变量：

{
  "provider": {
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    }
  }
}

想写注释也行，把文件改名成 opencode.jsonc（JSON with Comments，支持注释的 JSON）。

动手改

1. 用你最顺手的安装方式装好 opencode，跑 opencode --version 把版本号记下来。
2. 在 ~/.config/opencode/opencode.json 里写上 "model" 和 "small_model" 两个字段，把模型名换成 opencode models 里列出来的真实名字。
3. 把 ANTHROPIC_API_KEY（或你用的那家）写进 shell 配置里，然后用 opencode debug config 确认配置被正确读到。

小结

• 装法四选一：官方脚本 / npm / brew install anomalyco/tap/opencode / pacman
• Windows 官方推荐 WSL，/mnt/c/ 挂载 Windows 盘
• opencode 1 与 2 共用 opencode 命令，不能并存
• 模型靠 /connect 或 opencode auth login 接，Key 存 ~/.local/share/opencode/auth.json
• 配置：opencode.json（全局在 ~/.config/opencode/，项目在根目录），tui.json 管界面，密钥用 {env:...}

下一章：会话与基本用法 🐸