OpenCode 安装教程：开源终端 AI 编程助手从零上手

🚀 一句话简介：OpenCode 是一款 100% 开源的 AI 编程 Agent，直接跑在终端里，支持 75+ 模型供应商，能理解整个代码库、自主完成多文件编辑和命令执行。本文带你从零完成安装与配置。

---

📖 目录

• 一、OpenCode 是什么
• 二、环境要求
• 三、安装 OpenCode
• 四、验证安装
• 五、首次配置：连接 AI 模型
• 六、快速上手
• 七、升级与卸载
• 八、常见问题 FAQ
• 九、参考资料

---

一、OpenCode 是什么

OpenCode 是由 SST（anomalyco）团队打造的开源 AI 编程 Agent，你可以把它理解为 “开源版 Claude Code”，但它有几个独特优势：

特性	说明
🔓 100% 开源	代码完全开源，GitHub 星标数十万，社区活跃
🧠 模型中立	不绑定任何厂商，支持 Anthropic、OpenAI、Gemini、DeepSeek 等 75+ 供应商，也支持本地模型
💻 终端优先	基于 Go + Bubble Tea 构建的丝滑 TUI（终端界面），启动快、占用低
🏠 本地优先	代码与对话数据默认保存在本地
🖥️ 多形态	提供终端 TUI、桌面应用（Desktop App）、IDE 扩展三种使用方式

它能做的事情远不止“补全代码”：读懂项目 → 规划任务 → 修改多个文件 → 运行命令 → 生成测试，一条龙完成。

---

二、环境要求

在开始之前，请确认你的环境满足以下条件：

1. 操作系统

• ✅ macOS
• ✅ Linux
• ✅ Windows（推荐使用 WSL，或使用桌面版 / Scoop 安装）

2. 终端（TUI 使用建议）

官方推荐使用现代终端模拟器以获得最佳渲染效果：

• WezTerm（跨平台）
• Alacritty（跨平台）
• Ghostty（Linux / macOS）
• Kitty（Linux / macOS）

3. Node.js（仅 npm 安装方式需要）

如果选择 npm / bun 方式安装，需要 Node.js ≥ 18（推荐 20+）：

node -v   # 确认版本 ≥ 18

💡 使用官方一键脚本、Homebrew、Scoop 等方式安装则无需 Node.js。

4. API Key

准备一个你打算使用的 LLM 提供商的 API Key（如 Anthropic、OpenAI、DeepSeek、阿里云百炼、火山方舟等）。

---

三、安装 OpenCode

方式一：官方一键脚本（⭐ 最推荐，macOS / Linux）

一行命令搞定，不依赖 Node.js：

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

安装完成后重新打开终端即可使用。

方式二：Homebrew（macOS / Linux）

brew install sst/tap/opencode

方式三：npm / bun / pnpm / yarn（前端开发者友好）

# npm
npm install -g opencode-ai

# bun
bun install -g opencode-ai

# pnpm
pnpm add -g opencode-ai

方式四：Windows 用户

Scoop：

scoop bucket add extras
scoop install extras/opencode

Chocolatey：

choco install opencode

WSL 方案（推荐给重度终端用户）：
在 WSL Ubuntu 中按“方式一”执行 curl 脚本即可。

方式五：桌面应用（Desktop App）

不习惯命令行的同学可以直接下载桌面版：

1. 访问官网下载页：https://opencode.ai/download
2. 页面会自动识别你的操作系统，点击 Download 下载安装包
3. 安装后登录并配置模型即可使用

方式六：Docker（容器化部署）

docker run -it --rm \
  -v $(pwd):/app \
  ghcr.io/anomalyco/opencode:latest

⚠️ 具体镜像 tag 以官方文档为准，Docker 方式适合在隔离环境中体验。

---

四、验证安装

打开新的终端窗口，执行：

opencode --version

如果输出了版本号（如 v1.x.x），说明安装成功 🎉

---

五、首次配置：连接 AI 模型

OpenCode 的模型 ID 统一采用 provider_id/model_id 格式（如 anthropic/claude-sonnet-4-5）。配置模型有三种方式：

方式一：交互式登录（最简单）

在终端运行：

opencode auth login

按提示选择你的 AI 提供商（Anthropic / OpenAI 等），输入 API Key 或完成浏览器 OAuth 登录即可。

也可以在 OpenCode 界面内输入 /connect 命令来管理供应商。

方式二：配置文件（最灵活）

配置文件位置：

系统	路径
macOS / Linux	~/.config/opencode/opencode.json
Windows	C:\Users\<用户名>\.config\opencode\opencode.json

项目级配置也可以放在项目根目录的 opencode.json 中。

示例（自定义 OpenAI 兼容供应商）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "my-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Provider",
      "options": {
        "baseURL": "https://your-api-endpoint/v1",
        "apiKey": "{env:MY_API_KEY}"
      },
      "models": {
        "my-model": {
          "name": "My Model"
        }
      }
    }
  },
  "model": "my-provider/my-model"
}

💡 建议把 API Key 放到环境变量中（如 {env:MY_API_KEY}），避免明文写进配置文件。

方式三：指定模型启动

opencode --model anthropic/claude-sonnet-4-5

---

六、快速上手

1. 进入项目目录并启动

cd your-project
opencode

启动后进入 TUI 界面，直接用自然语言对话即可，例如：

“帮我分析这个项目的整体架构，并给 README 写一段简介。”

2. 常用操作速查

操作	快捷键 / 命令
切换模型	/models
连接供应商	/connect
切换 Agent 模式	Tab
新建会话	Ctrl+N
查看帮助	/help

3. 两种核心模式

• 🧭 Plan 模式：只规划不动手，先输出方案供你确认，适合复杂任务
• 🔨 Build 模式：直接读写文件、执行命令，干活模式

✅ 最佳实践：先用 Plan 模式让 AI 出方案，确认无误后再切到 Build 模式执行。

---

七、升级与卸载

升级

# curl 脚本安装的：重新执行一遍脚本即可
curl -fsSL https://opencode.ai/install | bash

# npm 安装的
npm install -g opencode-ai@latest

# Homebrew 安装的
brew upgrade opencode

卸载

# npm
npm uninstall -g opencode-ai

# Homebrew
brew uninstall opencode

# 清理配置（可选）
rm -rf ~/.config/opencode

---

八、常见问题 FAQ

Q1：opencode: command not found 怎么办？
重新打开终端，或检查安装路径是否在 PATH 中（curl 脚本安装的通常在 ~/.opencode/bin，需确认已写入 shell 配置）。

Q2：npm 安装时报权限错误（EACCES）？
使用 sudo npm install -g opencode-ai，或更好的方式是配置 npm 全局目录到用户目录 / 改用官方 curl 脚本。

Q3：终端界面显示乱码？
更换为官方推荐的现代终端（WezTerm / Ghostty / Alacritty / Kitty）。

Q4：国内网络访问模型 API 受限？
可在 opencode.json 中配置国内供应商（DeepSeek、阿里云百炼、火山方舟、MiniMax 等均支持 OpenAI 兼容接口），填入对应的 baseURL 和 API Key 即可。

Q5：如何查看支持的模型列表？
在 TUI 中输入 /models，或参考 models.dev。

---

九、参考资料

• 🌐 官网：https://opencode.ai
• 📚 官方文档：https://opencode.ai/docs
• 🐙 GitHub：https://github.com/anomalyco/opencode
• 🧩 模型库：https://models.dev

---

✍️ 写在最后：OpenCode 不会替代你的编程能力，但它能把重复性的“脏活累活”接管过去。如果你是终端重度用户，或者想找一个不绑定厂商、完全开源的 AI 编程助手，OpenCode 值得一试。

觉得有用的话，欢迎 点赞 👍 收藏 ⭐ 转发 🔄，我们下期见！