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

OpenCode 是一个开源的终端 AI 编码 AgentAI 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、GhosttyLinux/macOS、KittyLinux/macOS等LLM 供应商的 API Key准备好你打算使用的模型对应的密钥Windows 用户官方推荐使用 WSLWindows Subsystem for Linux性能更好、功能兼容性最完整如何安装 OpenCode6 种方式安装 OpenCode 最简单的方式是官方安装脚本此外还支持 npm、Homebrew、Docker 等多种途径可按操作系统和习惯选择。方式一官方安装脚本最简单curl-fsSLhttps://opencode.ai/install|bash方式二Node.jsnpm / bun / pnpm / yarnnpminstall-gopencode-ai方式三HomebrewmacOS 和 Linuxbrewinstallanomalyco/tap/opencode官方建议用anomalyco/tap获取最新版本官方brew install opencode由 Homebrew 团队维护更新较慢。方式四Arch Linuxsudopacman-Sopencode# 稳定版paru-Sopencode-bin# AUR 最新版方式五WindowsChocolatey / Scoopchocoinstallopencode scoopinstallopencode方式六Dockerdockerrun-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、pluginsInline 内联配置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国内可直接访问就能在终端里按需切换调用平台内的模型。常见问题QOpenCode 和 Claude Code 有什么区别两者都是终端 AI 编码 Agent。OpenCode 是开源项目支持 75 供应商和本地模型、可自由切换模型并提供终端/桌面/IDE 多形态它不绑定单一模型厂商灵活性更高。QOpenCode 支持本地模型吗支持。OpenCode 基于 AI SDK 和 Models.dev明确支持运行本地模型可搭配本地推理服务如 LM Studio、Ollama 等 OpenAI 兼容端点使用。QOpenCode 的配置文件放在哪里可放多个位置并按优先级合并全局在~/.config/opencode/opencode.json项目级在项目根目录的opencode.json还支持OPENCODE_CONFIG等环境变量指定。后加载的配置覆盖冲突键。Q如何切换 OpenCode 正在使用的模型在 OpenCode 界面里输入/models命令即可选择模型用/connect添加新供应商的凭据。也可在opencode.json的model字段设默认模型。QWindows 上怎么装 OpenCode 更稳官方推荐用 WSLWindows 子系统兼容性和性能最好。也可用 Chocolateychoco install opencode或 Scoopscoop 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/docs2026 年公开信息命令与配置字段可能随版本更新变动建议以官方文档为准并定期核对。延伸资源OpenCode 官方文档opencode.ai/docsAI 编程工具配置与多模型接入developer.qiniu.com/aitokenapi/13417/tools-AI-Coding-api