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

如果你正在找一个能真正理解整个代码仓库、自己动手改文件、还能跑命令的AI编程助手，OpenCode值得认真看看。先扯一句，这东西不是简单的代码补全工具，它是一个开源的终端AI编码Agent，有三种形态：终端界面（TUI）、桌面应用和IDE扩展。基于AI SDK和Models.dev，它支持75个以上的LLM供应商，还能跑本地模型。配置走opencode.json文件，模型ID统一写成provider_id/model_id的形式。安装最简单的路子就是一行官方脚本，当然npm、Homebrew、Docker这些也全都支持。下面这篇东西，是基于OpenCode官方文档整理出来的，把安装、模型与供应商配置、配置文件优先级，还有怎么接入自定义的OpenAI兼容模型，全都掰扯清楚了。目的就一个：帮你在终端里快速搭好一个能真正干活的AI编码助手。

OpenCode 是什么

OpenCode是一个开源的AI编码Agent，可以跑在终端界面、桌面应用或者作为IDE扩展来用。关键在于，它不是那种只给你补个代码的工具——它能读懂整个仓库，自己决定改哪些文件，还能直接执行终端命令，是个真正的智能体。

从官方文档来看，核心特征可以这么概括：

• 多形态：终端TUI、桌面App、IDE扩展，此外还有Web、Server、SDK等形态
• 广泛的模型支持：基于AI SDK和Models.dev，支持75+个LLM供应商，本地模型也能跑
• 工具集成：AI可以执行命令、搜索文件、改代码，不是光动嘴
• 会话管理：多个对话会话都能保存和管理
• 可扩展：支持MCP servers、LSP、自定义命令、Agent Skills、插件

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 -fsSL https://opencode.ai/install | bash

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

npm install -g opencode-ai

方式三：Homebrew（macOS 和 Linux）

brew install anomalyco/tap/opencode

官方建议用 anomalyco/tap 这个tap来拿最新版本；官方那个brew install opencode是Homebrew团队维护的，更新速度慢一些。

方式四：Arch Linux

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

方式五：Windows（Chocolatey / Scoop）

choco install opencode
scoop install opencode

方式六：Docker

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：

{
  "$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
  }
}

这里就有个优先级的问题。后加载的配置会覆盖前面的冲突键，但非冲突的设置都会保留下来。优先级从低到高是这样的：

1. Remote 远程配置（来自 .well-known/opencode）——组织级默认
2. Global 全局配置（~/.config/opencode/opencode.json）——用户偏好
3. Custom 自定义配置（OPENCODE_CONFIG 环境变量）
4. Project 项目配置（项目根目录的 opencode.json）——项目级设置
5. .opencode 目录（agents、commands、plugins）
6. 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 支持本地模型吗？
支持。它基于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 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：OpenCode安装配置与模型部署终端AI编码Agent完整上手教程要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题