OpenCode 安装与配置完整指南

⚠️ 待更新·2026-08-29核验 · 更新时间待核验 · 本文信息可能已过期，请以官方文档为准更新时间：2026-08-29 · 核验状态：待更新 · 官方溯源待补

简介

OpenCode 是一款开源的终端 AI 编程助手，定位类似 Claude Code，但支持任意 OpenAI 兼容模型。它能在终端里读写文件、执行命令、自动迭代代码，并内置 MCP（Model Context Protocol）客户端，可挂载外部工具。适合在 SSH 环境、容器或纯命令行工作流中使用，不依赖任何 IDE。本指南带你完成从安装到首次对话的全流程，并把免费模型接入的常见坑一并讲清楚。

flowchart LR A["Install OpenCode"] --> B["Configure Model"] B --> C["Start Session"] C --> D["AI Reads Files"] D --> E["AI Edits Code"] E --> F["Run Commands"] F --> D

安装

OpenCode 提供三种主流安装方式，任选其一即可，跨平台支持 Linux、macOS 与 Windows（WSL）。

方式一：一键脚本（推荐）

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

脚本自动检测架构，把二进制放到 ~/.local/bin，并提示是否加入 PATH。完成后 opencode --version 能输出版本号即成功。

方式二：npm 全局安装

npm install -g opencode-ai

适合已经在用 Node 工具链的开发者。注意 npm 安装的版本可能比官网脚本慢一两天。

方式三：Homebrew（macOS/Linux）

brew install sst/tap/opencode

Homebrew 的优势是 brew upgrade 跟其他包一起更新，省心。

配置模型

OpenCode 启动时会在当前目录或 ~/.config/opencode/ 寻找 opencode.json，从里面读取模型与 provider 配置。最小可用配置如下：

{
  "provider": {
    "openrouter": {
      "type": "openai",
      "baseURL": "https://openrouter.ai/api/v1",
      "apiKey": "sk-or-v1-..."
    }
  },
  "model": "deepseek/deepseek-chat:free",
  "smallModel": "google/gemini-2.0-flash:free"
}

要点：

provider 是命名空间，名字随意，只要和 model 前缀对应即可。
:free 后缀让 OpenRouter 走免费层，零成本。
smallModel 用于摘要、补全等轻任务，单独指定能省额度。
建议把 apiKey 放到环境变量 OPENROUTER_API_KEY，配置文件用 "${OPENROUTER_API_KEY}" 引用，避免 key 进 Git。

接入 Groq / DeepSeek 直连

Groq 推理速度快，适合做日常编程：

{
  "provider": {
    "groq": {
      "type": "openai",
      "baseURL": "https://api.groq.com/openai/v1",
      "apiKey": "${GROQ_API_KEY}"
    }
  },
  "model": "llama-3.3-70b-versatile"
}

DeepSeek 推理强，适合做算法题与代码审查：

{
  "provider": {
    "deepseek": {
      "type": "openai",
      "baseURL": "https://api.deepseek.com/v1",
      "apiKey": "${DEEPSEEK_API_KEY}"
    }
  },
  "model": "deepseek-reasoner"
}

启动会话

cd my-project
opencode

进入交互式界面后，常用命令：

add file path：把文件加进 AI 上下文
/model groq/llama-3.3-70b：运行时切模型
/clear：清空当前对话历史
exit 或 Ctrl+D：退出

常见坑

PATH 没生效：重启 shell 或 source ~/.bashrc 后再试 opencode。
401 Unauthorized：检查 OPENROUTER_API_KEY 是否 export 到当前 shell，以及配置文件是否用了 ${ENV_VAR} 引用语法。
429 Too Many Requests：免费层 RPM/TPM 都有限，单次会话里别一口气刷几十个请求；或换 :free 模型轮询。
流式输出卡顿：Groq 比较快，OpenRouter :free 在高峰期可能慢——切到 Groq 或 DeepSeek 直连即可。
Windows WSL 路径混乱：在 WSL 里始终用 /mnt/c/... 访问 Windows 盘，不要混用反斜杠。

把 OpenCode 接到免费模型后，你就有了一个零成本、可脚本化、能跑在 SSH 环境里的 AI 编程助手——用法和 Claude Code 几乎一样，但账单是 0。

🚀 立即开始：免费 API 一键调用

想要无需逐一注册、统一鉴权调用以上全部免费模型？Apishare.cc 提供统一 API Key，一个 Key 调用 100+ 模型，免费模型零成本直连。

👉 立即注册 Apishare.cc → 获取你的统一 API Key

📊 想看更多免费模型排行？查看 2026年9月免费 LLM API 综合实力榜单 →

立即上手：APIShare 免费 API 目录

🆓 注册领取免费额度：立即注册 APIShare · 登录控制台
🔍 浏览全部免费 API 与实时榜单：APIShare 免费 API 目录
📊 查看免费 LLM API 排行：Free LLM API Rankings

免费 API 聚合平台说明

本文涉及的模型均由 APIShare 免费 API 聚合平台统一接入，一份 Key 调用全站模型。

完整模型目录：APIShare 免费 API 目录
注册即送免费额度：注册领取 API Key