02-安装与配置

OpenCode 操作指导书（二）：安装与配置

适用版本：OpenCode v1.18.3
本篇目标：在 macOS / Windows / Linux 上完成 OpenCode 安装、模型认证与基础配置，确保启动即用。

1. 安装方式总览

⚠️Windows 用户强烈建议使用 WSL：自动安装方式在原生 Windows 上兼容性较差，WSL 提供最佳性能与完整功能。

2. 各平台安装步骤

2.1 一键安装脚本（推荐，跨平台）

curl-fsSLhttps://opencode.ai/install|bash

安装脚本的目录优先级：

1. $OPENCODE_INSTALL_DIR—— 自定义安装目录（最高优先）
2. $HOME/.opencode/bin—— 默认回退目录
3. $XDG_BIN_DIR（如$HOME/.local/bin）

示例（指定安装目录）：

OPENCODE_INSTALL_DIR=/usr/local/bincurl-fsSLhttps://opencode.ai/install|bash# 或XDG_BIN_DIR=$HOME/.local/bincurl-fsSLhttps://opencode.ai/install|bash

2.2 使用 Node.js 包管理器

npminstall-gopencode-ai@latest# npmbuninstall-gopencode-ai# bunpnpminstall-gopencode-ai# pnpmyarnglobaladdopencode-ai# yarn

2.3 macOS / Linux（Homebrew）

# 官方 tap（更新最及时，推荐）brewinstallanomalyco/tap/opencode# 等价于旧写法：brew install sst/tap/opencode# Homebrew 官方公式（更新较慢）brewinstallopencode

2.4 Windows

# Scoop（推荐）scoop bucket add extras scoop install extras/opencode# Chocolateychoco install opencode

若自动方式不可用，请从 GitHub Releases 下载对应架构的二进制（opencode-windows-*.zip）解压到 PATH 目录。

2.5 Arch Linux

sudopacman-Sopencode# 稳定版# 或 AUR 最新版paru-Sopencode-bin

2.6 桌面端（Desktop）

从 GitHub Releases 下载opencode-desktop-*.deb/*.rpm/*.dmg/.exe安装；或用opencode web在浏览器中使用。

3. 验证安装

opencode--version# 预期输出类似：opencode version v1.18.3

提示：若提示命令未找到，检查安装目录是否已加入PATH（如~/.opencode/bin或~/.local/bin）。

4. 模型认证（Auth）

OpenCode 由 Models.dev 驱动，支持 75+ 提供方。首次使用需配置凭证：

opencode auth login

交互示例：

$ opencode auth login ┌ Add credential │ ◆ Select provider │ ● Anthropic (recommended) │ ○ OpenAI │ ○ Google │ ○ Amazon Bedrock │ ○ Azure │ ○ DeepSeek │ ○ Groq │ ... └

• 凭证默认存储于~/.local/share/opencode/auth.json。
• 也可通过环境变量或项目内.env文件提供 Key（见第 4.3 节）。

查看已配置的提供方：

opencode auth list# 或 opencode auth ls

注销某个提供方：

opencode authlogoutanthropic

5. 配置文件详解

5.1 文件格式与位置

• 格式：JSON / JSONC（支持注释），全局 Schema：https://opencode.ai/config.json。
• TUI 专属配置 Schema：https://opencode.ai/tui.json。

配置加载优先级（合并而非替换，后者覆盖前者冲突键）：

全局配置路径：~/.config/opencode/opencode.json
项目配置路径：项目根目录opencode.json（启动时会从当前目录向上查找到最近的 Git 根）

5.2 最小可用配置（Anthropic）

{"$schema":"https://opencode.ai/config.json","model":"anthropic/claude-sonnet-4-5","provider":{"anthropic":{"options":{"apiKey":"{env:ANTHROPIC_API_KEY}","timeout":600000}}}}

5.3 设置默认模型与轻量模型

{"model":"anthropic/claude-sonnet-4-5","small_model":"anthropic/claude-haiku-4-5"}

• model：主模型，用于编码等重任务。
• small_model：轻量任务（如生成标题）使用的更便宜模型。

5.4 多提供方共存

{"provider":{"anthropic":{"options":{"apiKey":"{env:ANTHROPIC_API_KEY}"}},"openai":{"options":{"apiKey":"{file:~/.secrets/openai-key}"}}},"model":"anthropic/claude-sonnet-4-5","enabled_providers":["anthropic","openai"]}

• enabled_providers：白名单；disabled_providers：黑名单（优先级更高）。

5.5 API Key 的安全写法（变量替换）

避免在配置中明文写 Key：

{"provider":{"openai":{"options":{"apiKey":"{file:~/.secrets/openai-key}"}}}}

• {env:VAR_NAME}：读取环境变量，未设置则为空串。
• {file:path}：读取文件内容，相对配置目录或绝对路径（/或~开头）。

5.6 提供方特定选项（示例：Amazon Bedrock）

{"provider":{"amazon-bedrock":{"options":{"region":"us-east-1","profile":"my-aws-profile","endpoint":"https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"}}}}

6. 环境变量参考

7. 安装检查清单

完成以上三步，即可进入03-界面与快捷键.md熟悉界面。

本篇为 OpenCode 操作指导书系列之一，版本 v1.18.3。