OpenCode 安装最简流程：终端、桌面应用与 IDE 扩展三端一次说清

OpenCode 是当前最受关注的开源 AI 编码 agent 之一，GitHub 收获 153k+ stars、月活开发者 6.5M+，由 Anomaly 团队（前 SST）维护，anomalyco/opencode 仓库采用 MIT 协议开源。OpenCode 安装最大的卖点是 provider 中立——不绑定任何模型厂商，可同时使用 Claude、GPT、Gemini、Grok、本地 Ollama 模型甚至 GitHub Copilot 订阅，对中文开发者尤其友好。

OpenCode 当前提供四个表面：终端 CLI（核心）、桌面应用 Beta、VS Code / Cursor / Zed / Windsurf 扩展、GitHub Actions 集成。本指南整理三端在 macOS、Windows、Linux 上的最简安装命令，并解决 opencode-ai 老仓库（已改名 Crush）与当前 anomalyco 主流版本的消歧义问题。

仓库消歧义：你要装的是 anomalyco/opencode

OpenCode 在 2025 年经历了一次分裂，导致 GitHub 上同时存在两个 “opencode” 仓库，初学者很容易装错版本：

• opencode-ai/opencode（旧仓库，已不再维护）：2024 年由 Kujtim Hoxha 主导用 Go 创建的原始版本，2025 年与 Charm 合作后改名为 Crush，已停止以 OpenCode 名义发布新版本
• anomalyco/opencode（当前主流版本）：2025 年由 Dax Raad、Adam Doty 等贡献者从原始版本 fork，用 TypeScript + Bun 完全重写，并采用自研 OpenTUI 框架（Zig + SolidJS）。SST 公司 2026 年改名为 Anomaly，仓库随之迁移

判断标准：

• 访问 opencode.ai 与 github.com/anomalyco/opencode，这是当前活跃维护的主流版本
• npm 包名应是 opencode-ai（Anomaly 沿用了原 npm 包名继续发布）
• Homebrew tap 应是 anomalyco/tap/opencode

本文所有命令均针对 anomalyco/opencode 当前主流版本。

系统要求与前置检查

OpenCode 由 TypeScript + Bun 构建，发布为自包含原生二进制：

• 操作系统：macOS、Windows 10/11、Linux 主流发行版（Ubuntu、Debian、Fedora、RHEL、Arch、Alpine 等）
• 系统架构：x64 或 ARM64
• Node.js：仅 npm 安装路径需要 18+；其他路径无依赖
• 账号：OpenCode 本体免费开源，使用成本取决于你接入的模型 provider——可使用 Anthropic、OpenAI、Google、Groq、OpenRouter 等付费 API，或免费的本地 Ollama 模型，也可用 OpenCode Zen 订阅（10 美元/月，提供官方测试过的模型集）
• 终端：建议使用现代终端模拟器（iTerm2、Windows Terminal、Alacritty、Kitty、Ghostty 等）以获得最佳 TUI 体验

关于 provider 中立：OpenCode 不直接消耗任何订阅额度。你需要至少一个 LLM 入口才能使用——最低成本路径是 本地 Ollama + 开源模型（零费用），最高质量路径是 Claude Sonnet/Opus 或 GPT 系列 API。

检查当前是否已安装：

opencode --version

如果返回版本号（如 v1.1.x），说明已安装。否则按下文方法安装。

安装方法

方法一：官方安装脚本（跨平台推荐）

最简单的安装路径，零依赖、自动检测平台架构、自动配置 PATH：

macOS、Linux、WSL：

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

Windows PowerShell：脚本同样兼容 Windows 子系统，建议在 WSL2 内执行。原生 PowerShell 用户改用方法三的 Scoop 或 Chocolatey 路径。

可通过环境变量自定义安装目录：

# 安装到自定义目录
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
 
# 使用 XDG 标准目录
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

完成后运行 opencode –version 验证。

方法二：Homebrew（macOS / Linux）

OpenCode 提供两个 Homebrew 入口，选择哪个对更新及时性有显著影响：

# 推荐：Anomaly 自维护 tap，更新最及时
brew install anomalyco/tap/opencode
 
# 备选：Homebrew 官方 formula，更新较慢
brew install opencode

差异说明：anomalyco/tap 由 OpenCode 团队自己维护，新版本发布后即时同步；而 Homebrew 官方 formula 走社区审核流程，存在 1-2 个版本的滞后。对于活跃迭代的工具优先选 anomalyco/tap。

升级用：

brew upgrade opencode

桌面应用（Beta）同样通过 Homebrew cask 安装：

brew install --cask opencode-desktop

方法三：Windows 包管理器（Scoop / Chocolatey / WinGet）

Windows 用户原生路径有三种包管理器选择，无需 WSL 即可获得完整功能。

Scoop（推荐）：

# OpenCode CLI
scoop install opencode
 
# OpenCode 桌面应用
scoop bucket add extras
scoop install extras/opencode-desktop

Chocolatey：

choco install opencode

WinGet：

winget install --id SST.opencode -e

关于 winget 包名为 SST.opencode 的历史：包 ID 仍以 SST 命名空间发布，是因为该包在 SST 公司更名为 Anomaly 之前就已提交到 winget 仓库——一旦确定的 winget 包 ID 通常不会变更，避免破坏现有用户的更新链路。但包内部的安装源（InstallerUrl）已经指向 github.com/anomalyco/opencode/releases/，所以装的就是当前主流版本。

WinGet 路径已知问题：根据 OpenCode GitHub Issue 5121，winget 包审核流程比 GitHub Releases 慢 1-2 个版本，且 winget 路径未在 OpenCode 官方文档中显式列出。对追新版本的用户，建议使用方法一的官方安装脚本或 Scoop；对企业受控环境强制使用 winget 的用户，该路径仍可用，仅需接受版本滞后。

升级：

# Scoop
scoop update opencode
 
# Chocolatey
choco upgrade opencode
 
# WinGet
winget upgrade --id SST.opencode

方法四：npm 安装（跨平台）

适合 CI/CD 中需要固定版本、团队工作流以 npm 为标准的场景：

# npm
npm install -g opencode-ai@latest
 
# 或 bun（OpenCode 自身使用 Bun 构建，bun 路径性能略好）
bun add -g opencode-ai
 
# pnpm / yarn
pnpm add -g opencode-ai
yarn global add opencode-ai

注意 npm 包名：是 opencode-ai，不是 opencode。npm 上无关同名包同样存在，安装前确认完整命令。

要求 Node.js 18+。禁止使用 sudo npm install -g，遇到 EACCES 错误改用用户级 npm prefix 或 nvm。

方法五：Linux 包管理器（Arch / Nix）

Arch Linux 用户：

# 稳定通道（pacman）
sudo pacman -S opencode
 
# AUR 最新版本（paru / yay）
paru -S opencode-bin
yay -S opencode-bin

Nix 用户：

# 从 nixpkgs 运行
nix run nixpkgs#opencode
 
# 使用 dev 分支最新版本
nix run github:anomalyco/opencode

Mise / asdf 用户：

mise use -g opencode

方法六：桌面应用（Beta）

OpenCode 桌面应用目前处于 Beta 阶段，提供图形化的项目管理界面：

macOS Homebrew：

brew install --cask opencode-desktop

Windows Scoop：

scoop bucket add extras
scoop install extras/opencode-desktop

直接下载：访问 opencode.ai/download 下载对应平台安装包：

• macOS Apple Silicon / Intel
• Windows x64
• Linux .deb / .rpm

桌面应用与 CLI 共享同一个数据目录与认证，在任一表面登录后另一表面无需再次认证。

方法七：IDE 扩展（VS Code / Cursor / Zed / Windsurf）

OpenCode 提供官方 IDE 扩展，把 agent 集成到编辑器内：

• VS Code：扩展市场搜索 “OpenCode”
• Cursor：扩展市场搜索 “OpenCode”（Cursor 是 VS Code fork，扩展兼容）
• Zed：从 Zed Extensions 安装
• Windsurf：扩展市场搜索 “OpenCode”
• VSCodium：从 OpenVSX 安装

或访问 opencode.ai/download 跳转到各 IDE 的对应安装链接。

认证与模型配置：你必须连一个 provider 才能用

与 Claude Code、Codex 不同，OpenCode 不内置任何模型订阅——这是它最大的灵活性，也是初次配置的主要门槛。安装后必须至少连接一个 provider 才能开始使用。

OpenCode 使用 Models.dev 维护的 provider 列表，启动后执行：

opencode auth login

会列出所有支持的 provider，选择后输入对应 API Key 即可。常见 provider 配置：

• Anthropic（Claude）：在 console.anthropic.com 创建 API Key
• OpenAI（GPT）：在 platform.openai.com 创建 API Key
• OpenRouter：聚合多家 provider，单 Key 访问 100+ 模型，国内开发者常用
• 本地 Ollama：执行 opencode auth login 选 Ollama，无需 Key，仅需本地 Ollama 服务运行
• GitHub Copilot：复用已有 Copilot 订阅，登录 GitHub 账号即可
• OpenCode Zen：OpenCode 团队自营订阅服务，10 美元/月提供官方测试过的精选模型集

凭证存储在 ~/.local/share/opencode/auth.json（Linux/macOS）或 %LOCALAPPDATA%\opencode\auth.json（Windows），需视为密码保护。

切换默认模型：在 OpenCode TUI 内执行 /connect 选择 provider 与模型，或编辑 opencode.json 配置文件。

模型选择建议：从零开始如何配第一个 provider

对完全新手而言，OpenCode 的 provider 中立性反而是部署门槛。三种典型场景的最小配置：

场景 1：完全免费体验：先装 Ollama → ollama pull qwen2.5-coder:7b → 在 OpenCode 中选 Ollama provider。零费用但模型能力受本地硬件限制。

场景 2：质量优先：使用 Anthropic Claude Sonnet/Opus API，按 token 计费但当前是公认编码能力最强的模型。月度预算 20-50 美元可覆盖日常使用。

场景 3：性价比优先：使用 OpenRouter 单 Key 访问 GLM、DeepSeek、Kimi 等中国开源模型，单价显著低于 Claude/GPT。中文项目编码场景对中文开源模型友好度较高。

不推荐做法：在第一次安装时跳过 provider 配置直接进 TUI——OpenCode 会显示 /connect 提示但无法处理任何请求，体验上像是工具坏了。

更新方式：每个安装路径不同

不同安装路径对应不同更新机制：

• 官方安装脚本：重新执行 curl -fsSL https://opencode.ai/install | bash，或使用内置 opencode upgrade 命令
• Homebrew：brew upgrade opencode
• npm：npm install -g opencode-ai@latest
• Scoop：scoop update opencode
• Chocolatey：choco upgrade opencode
• WinGet：winget upgrade –id SST.opencode
• pacman：sudo pacman -Syu opencode
• 桌面应用：通过包管理器更新或在应用内检查更新

OpenCode 内置升级命令支持指定版本：

# 升级到最新版本
opencode upgrade
 
# 升级到特定版本
opencode upgrade --version 1.1.20

常见问题排查

问题 1：装错了仓库（opencode-ai 而非 anomalyco）

原因：在 GitHub 搜索 opencode 时排在前面的可能是已停止维护的旧仓库。

解决方案：确认 npm 包名 opencode-ai、Homebrew tap anomalyco/tap、官方网站 opencode.ai、当前主仓库 github.com/anomalyco/opencode。如果已装错版本：

# 卸载旧的 opencode-ai/opencode（如有）
which opencode  # 确认当前 opencode 路径
rm -f $(which opencode)
 
# 重新装当前主流版本
curl -fsSL https://opencode.ai/install | bash

问题 2：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 18+。

解决方案：执行 node –version 检查。低于 18 时通过 nvm install –lts 升级，或改用方法一的官方安装脚本（不需要 Node.js）。

问题 3：opencode –version 提示 command not found

解决方案：

• 关闭终端开新窗口
• macOS/Linux 执行 source ~/.zshrc 或 source ~/.bashrc
• 检查官方安装脚本默认目录是否在 PATH 中（通常是 ~/.opencode/bin 或 ~/.local/bin）

问题 4：TUI 显示乱码或字符错位

原因：OpenCode 使用自研 OpenTUI 框架（Zig + SolidJS），对终端模拟器的现代特性有依赖。某些老终端（默认 cmd.exe、低版本 Terminal.app）渲染异常。

解决方案：

• 切换到现代终端：iTerm2、Windows Terminal、Alacritty、Kitty、Ghostty
• 确认终端 Locale 设为 UTF-8：echo $LANG 应输出 en_US.UTF-8 或 zh_CN.UTF-8
• 确认终端字体支持 Powerline / Nerd Font 图标

问题 5：opencode auth login 看不到想要的 provider

原因：OpenCode 从 Models.dev 拉取 provider 列表，如果该数据未更新或网络不通会缺失部分选项。

解决方案：

• 升级 OpenCode 到最新版本
• 检查能否访问 models.dev
• 对于尚未在 Models.dev 列出的 provider，可在 opencode.json 中手动配置 OpenAI 兼容端点

问题 6：本地 Ollama 模型连不上

原因：OpenCode 默认期望 Ollama 监听 127.0.0.1:11434，自定义部署或远程 Ollama 需显式配置。

解决方案：在 shell 中设置：

export LOCAL_ENDPOINT=http://your-ollama-host:11434

或在 opencode.json 中配置自托管 provider。

问题 7：国内网络无法访问 Anthropic / OpenAI API

解决方案：

• 设置代理：export HTTPS_PROXY=http://proxy.example.com:port
• 使用 OpenRouter 等聚合服务（部分国内可达）
• 使用国内可达的中国开源模型 API（智谱 GLM、深度求索 DeepSeek、月之暗面 Kimi 等），通过 opencode.json 配置 OpenAI 兼容端点

问题 8：plan 模式与 build 模式如何切换

解决方案：在 TUI 内按 Tab 键即可切换。Build 是默认全权限 agent，Plan 是只读分析模式适合先做方案再改代码。OpenCode 支持自定义 agent，配置文件位于 ~/.opencode/agents/ 或项目级 .opencode/agents/。

问题 9：Copilot 订阅认证失败

原因：OpenCode 通过读取系统中已有的 GitHub Copilot 凭证文件实现 Copilot 复用，需要先在 VS Code 或其他 Copilot 客户端登录。

解决方案：

• 在 VS Code Copilot 扩展或 GitHub CLI（gh auth login）中先登录
• OpenCode 会自动从标准位置读取 token
• 仍失败时手动设置 GITHUB_TOKEN 环境变量，或在 opencode.json 的 providers.copilot.apiKey 中配置

验证安装与基础使用

安装完成后，建议执行以下命令验证：

# 检查版本
opencode --version
 
# 配置第一个 provider
opencode auth login
 
# 在项目目录启动 TUI
cd /path/to/your/project
opencode

进入 OpenCode 后可使用以下内置命令：

# 切换 provider 与模型
/connect
 
# 分析仓库结构并生成 AGENTS.md
/init
 
# 显示帮助与快捷键
/help
 
# 撤销 / 重做最近一次变更
/undo
/redo
 
# 分享当前会话（可选功能）
/share

关键快捷键：

• Tab：在 Build 与 Plan 模式之间切换
• @：模糊搜索项目文件，把文件加入上下文
• 拖拽图片到终端：把图片加入上下文，OpenCode 支持视觉模型
• Ctrl+X：默认 leader key（避免与终端快捷键冲突），后接 Leader+key 触发各种命令

装完之后的关键三步：

• 在项目根目录运行 /init，让 OpenCode 分析代码库并生成 AGENTS.md 作为持久上下文。该文件兼容 Claude Code 的 CLAUDE.md 与 Codex 的 AGENTS.md 约定
• 使用 Plan 模式（按 Tab 切换）让 OpenCode 先生成实施方案，确认后切回 Build 模式执行——这种”先规划后执行”的工作流是 OpenCode 相比其他工具的差异化设计
• 通过 opencode mcp add 接入 MCP 服务器，把 OpenCode 扩展为可调用 GitHub、数据库、内部 API 的完整 agent

非交互模式与 API 服务器

OpenCode 除 TUI 外还支持脚本调用与 HTTP 服务器模式，适合自动化集成：

# 单次提示 + 输出（适合 CI/CD）
opencode -p "Explain the use of context in Go"
 
# JSON 格式输出
opencode -p "List all TODO comments in this project" -f json
 
# 静默模式（脚本调用，禁用 spinner）
opencode -p "..." -q
 
# 启动 HTTP 服务器（多客户端并行连接）
opencode serve

opencode serve 启动后会暴露带 OpenAPI 文档（/doc）的 HTTP 端点，配合官方 @opencode-ai/sdk JS/TS SDK 可在自有应用内嵌入 OpenCode 能力。这是 OpenCode 的客户端/服务器架构带来的独特能力——TUI 只是众多前端之一。

卸载方式：不同安装路径对应不同清理步骤

OpenCode 提供内置卸载命令一键清理所有相关文件：

opencode uninstall

也可按安装方式分别处理：

• 官方安装脚本：删除二进制（通常在 ~/.opencode/bin/opencode）
• Homebrew：brew uninstall opencode 与 brew uninstall –cask opencode-desktop
• npm：npm uninstall -g opencode-ai
• Scoop：scoop uninstall opencode
• Chocolatey：choco uninstall opencode
• WinGet：winget uninstall –id SST.opencode
• pacman：sudo pacman -R opencode

仅删除二进制并不能完全清理。配置目录与会话历史保留在以下位置：

# Linux / macOS
~/.local/share/opencode/    # 会话历史与认证
~/.config/opencode/         # 配置文件
~/.opencode/                # 用户级 agents 与命令
 
# Windows
%LOCALAPPDATA%\opencode\
%APPDATA%\opencode\

彻底清理执行：

# Linux / macOS
rm -rf ~/.local/share/opencode ~/.config/opencode ~/.opencode
 
# Windows PowerShell
Remove-Item -Path "$env:LOCALAPPDATA\opencode" -Recurse -Force
Remove-Item -Path "$env:APPDATA\opencode" -Recurse -Force

安全提示：auth.json 存储 API Key 明文。卸载前如不打算重装，建议先 opencode auth logout 显式撤销凭证。项目级配置 .opencode/ 与 opencode.json 需在每个项目目录下单独删除。

获取方式

官方网站：opencode.ai

下载页（覆盖所有表面）：opencode.ai/download

官方文档：OpenCode Docs

CLI 命令参考：CLI Reference

GitHub 主仓库：anomalyco/opencode

支持的模型与 provider：Models.dev

JS/TS SDK：@opencode-ai/sdk

OpenCode 通过 provider 中立、客户端/服务器架构与开源协议，提供了与 Claude Code、Codex 完全不同的产品定位——它不绑定任何模型厂商，把选择权完全交给开发者。但安装本身只是入口，真正决定生产力的是后续 provider 选型、AGENTS.md 上下文设计、自定义 agent 体系搭建以及 MCP 服务器集成。对中文开发者而言，OpenCode 与 Claude Code、Codex 并存往往比单一选择更实用——OpenCode 可对接国内开源模型 API 与本地 Ollama，覆盖 Claude/Codex 难以触达的场景。