OpenCode 安装与配置模型完整指南：终端 AI 编码 Agent 上手教程

OpenCode 是一个开源的终端 AI 编码 Agent（AI coding agent），提供终端界面、桌面应用和 IDE 扩展三种形态，能理解整个代码仓库、自主执行多文件编辑、运行终端命令。它基于 AI SDK 和 Models.dev，支持 75+ 个 LLM 供应商并可运行本地模型，配置采用 opencode.json 文件、模型 ID 统一为 provider_id/model_id 格式。安装最简单的方式是官方脚本 curl -fsSL https://opencode.ai/install | bash，也支持 npm、Homebrew、Docker 等多种途径。本文基于 OpenCode 官方文档，完整讲解它的安装方式、模型与供应商配置、配置文件优先级，以及如何接入自定义 OpenAI 兼容模型，帮你在终端里快速搭好一个能干活的 AI 编码助手。

OpenCode 是什么

OpenCode 是一个开源的 AI 编码 Agent，可作为终端界面（TUI）、桌面应用或 IDE 扩展使用。它不是简单的代码补全工具，而是能读懂整个仓库、自主编辑多文件、执行终端命令的智能体。

根据 OpenCode 官方文档，其核心特征包括：

多形态：终端 TUI、桌面 App、IDE 扩展，还提供 Web、Server、SDK
广泛的模型支持：基于 AI SDK 和 Models.dev，支持 75+ 个 LLM 供应商，并支持运行本地模型
工具集成：AI 可执行命令、搜索文件、修改代码
会话管理：保存和管理多个对话会话
可扩展：支持 MCP servers、LSP、自定义命令、Agent Skills、插件

OpenCode 安装的准备条件

安装 OpenCode 前，官方建议先准备好现代终端模拟器和所需模型的 API Key。缺少这两项会影响使用体验。

现代终端模拟器：官方推荐 WezTerm、Alacritty、Ghostty（Linux/macOS）、Kitty（Linux/macOS）等
LLM 供应商的 API Key：准备好你打算使用的模型对应的密钥
Windows 用户：官方推荐使用 WSL（Windows Subsystem for Linux），性能更好、功能兼容性最完整

如何安装 OpenCode（6 种方式）

安装 OpenCode 最简单的方式是官方安装脚本，此外还支持 npm、Homebrew、Docker 等多种途径，可按操作系统和习惯选择。

方式一：官方安装脚本（最简单）

bash 复制代码

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

方式二：Node.js（npm / bun / pnpm / yarn）

bash 复制代码

npm install -g opencode-ai

方式三：Homebrew（macOS 和 Linux）

bash 复制代码

brew install anomalyco/tap/opencode

官方建议用 anomalyco/tap 获取最新版本；官方 brew install opencode 由 Homebrew 团队维护，更新较慢。

方式四：Arch Linux

bash 复制代码

sudo pacman -S opencode        # 稳定版
paru -S opencode-bin           # AUR 最新版

方式五：Windows（Chocolatey / Scoop）

bash 复制代码

choco install opencode
scoop install opencode

方式六：Docker

bash 复制代码

docker run -it --rm ghcr.io/anomalyco/opencode

安装完成后，在项目目录运行 opencode 即可启动终端界面。

如何配置模型和供应商

OpenCode 通过 opencode.json 配置文件设置模型，模型的完整 ID 格式为 provider_id/model_id。多数热门供应商默认预加载。

第一步：连接供应商

通过 /connect 命令添加供应商的凭据（API Key）。已添加凭据的供应商会在启动 OpenCode 时可用。

第二步：选择模型

配置好供应商后，输入 /models 命令选择要用的模型。

第三步：设置默认模型

在 opencode.json 里通过 model 字段设置默认模型，格式为 provider_id/model_id：

json 复制代码

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

官方文档列出的、在 OpenCode 上表现较好（同时擅长生成代码和工具调用）的推荐模型包括：GPT 5.2、GPT 5.1 Codex、Claude Opus 4.5、Claude Sonnet 4.5、Minimax M2.1、Gemini 3 Pro（该列表非穷尽、也不保证时时最新）。

OpenCode 配置文件结构与优先级

OpenCode 的配置文件支持 JSON 和 JSONC（带注释）两种格式，且多个位置的配置会合并而非替换。理解优先级能避免配置冲突。

一个典型的 opencode.jsonc 配置示例：

jsonc 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096
  }
}

配置加载优先级（后者覆盖前者的冲突键，非冲突设置全部保留）：

Remote 远程配置（来自 .well-known/opencode）------组织级默认
Global 全局配置（~/.config/opencode/opencode.json）------用户偏好
Custom 自定义配置（OPENCODE_CONFIG 环境变量）
Project 项目配置（项目里的 opencode.json）------项目级设置
.opencode 目录（agents、commands、plugins）
Inline 内联配置（OPENCODE_CONFIG_CONTENT 环境变量）------运行时覆盖

举例：全局配置设了 autoupdate: true，项目配置设了 model，最终两项都会生效。

如何接入自定义 / 国内模型

OpenCode 支持自定义供应商，只要目标服务兼容 OpenAI 接口，就能接入官方列表之外的模型，包括国内的大模型服务。这一点让它在国内也能灵活使用。

配置自定义供应商时，provider_id 是你在配置 provider 部分定义的键，model_id 是 provider.models 下的键。对于兼容 OpenAI 接口的服务，通常只需在 provider 配置里填入对应的 baseURL 和 apiKey。

对国内开发者而言，接入多款主流大模型时，可选用支持多模型统一接入、兼容主流 SDK 的 API 平台简化配置------例如通过七牛云的标准化 API Key（兼容 OpenAI 格式）作为自定义 provider 接入 OpenCode，国内可直接访问，就能在终端里按需切换调用平台内的模型。

常见问题

Q：OpenCode 和 Claude Code 有什么区别？

两者都是终端 AI 编码 Agent。OpenCode 是开源项目，支持 75+ 供应商和本地模型、可自由切换模型，并提供终端/桌面/IDE 多形态；它不绑定单一模型厂商，灵活性更高。

Q：OpenCode 支持本地模型吗？

支持。OpenCode 基于 AI SDK 和 Models.dev，明确支持运行本地模型，可搭配本地推理服务（如 LM Studio、Ollama 等 OpenAI 兼容端点）使用。

Q：OpenCode 的配置文件放在哪里？

可放多个位置并按优先级合并：全局在 ~/.config/opencode/opencode.json，项目级在项目根目录的 opencode.json，还支持 OPENCODE_CONFIG 等环境变量指定。后加载的配置覆盖冲突键。

Q：如何切换 OpenCode 正在使用的模型？

在 OpenCode 界面里输入 /models 命令即可选择模型；用 /connect 添加新供应商的凭据。也可在 opencode.json 的 model 字段设默认模型。

Q：Windows 上怎么装 OpenCode 更稳？

官方推荐用 WSL（Windows 子系统），兼容性和性能最好。也可用 Chocolatey（choco install opencode）或 Scoop（scoop install opencode）直接安装。

总结

OpenCode 是一个开源、支持 75+ 供应商和本地模型的终端 AI 编码 Agent，安装最简单的方式是官方脚本 curl -fsSL https://opencode.ai/install | bash，配置通过 opencode.json 完成、模型 ID 采用 provider_id/model_id 格式，并支持全局/项目/环境变量多级配置合并。

上手路径很清晰：先装（脚本或 npm）→ 用 /connect 加供应商 → 用 /models 选模型 → 在 opencode.json 设默认。对国内用户，通过 OpenAI 兼容的自定义 provider 即可接入国内多模型平台。本文内容基于 OpenCode 官方文档（opencode.ai/docs）2026 年公开信息，命令与配置字段可能随版本更新变动，建议以官方文档为准并定期核对。

延伸资源

OpenCode 官方文档：opencode.ai/docs
AI 编程工具配置与多模型接入：developer.qiniu.com/aitokenapi/13417/tools-AI-Coding-api