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 等多种途径，可按操作系统和习惯选择。

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

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

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

npminstall-gopencode-ai

方式三：Homebrew（macOS 和 Linux）

brewinstallanomalyco/tap/opencode

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

方式四：Arch Linux

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

方式五：Windows（Chocolatey / Scoop）

chocoinstallopencode scoopinstallopencode

方式六：Docker

dockerrun-it--rmghcr.io/anomalyco/opencode

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

如何配置模型和供应商

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

第一步：连接供应商

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

第二步：选择模型

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

第三步：设置默认模型

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

{"$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配置示例：

{ "$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 年公开信息，命令与配置字段可能随版本更新变动，建议以官方文档为准并定期核对。