⚠️ 待更新·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。
⚠️ Pending Update · 2026-08-29 Verification · Content may be outdated, please refer to official docs
Updated: 2026-08-29 · Status: Pending Verification
Introduction
OpenCode is an open-source terminal AI coding assistant in the spirit of Claude Code, but it works with any OpenAI-compatible model. It can read and write files, run shell commands, and iterate on code autonomously, and it ships a built-in MCP (Model Context Protocol) client so external tools can be plugged in. It is well suited to SSH sessions, containers, and pure command-line workflows where an IDE is overkill. This guide walks through installation, configuration, and the first chat session, and covers the common pitfalls when wiring in free models.
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
Installation
Three mainstream install paths, all cross-platform (Linux, macOS, Windows/WSL). Pick one.
Option 1: installer script (recommended)
curl -fsSL https://opencode.ai/install | bash
The script detects the architecture, drops the binary into ~/.local/bin, and offers to update your PATH. When opencode --version prints a version, the install is successful.
Option 2: npm global install
npm install -g opencode-ai
Convenient if you already live in the Node toolchain. The npm release can lag the official script by a day or two.
Option 3: Homebrew (macOS/Linux)
brew install sst/tap/opencode
Homebrew's win is brew upgrade keeping OpenCode in sync with the rest of your packages.
Model Configuration
On startup OpenCode looks for opencode.json in the current directory or ~/.config/opencode/. Minimum viable config:
{
"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"
}
Notes:
provider is a namespace — name it anything, as long as the prefix on model matches.- The
:free suffix routes through OpenRouter's free tier — zero cost.
smallModel is used for summarization and lightweight completions; pinning it separately saves quota.- Put
apiKey in an env var OPENROUTER_API_KEY and reference as "${OPENROUTER_API_KEY}" so the key never enters Git.
Wiring Groq / DeepSeek Direct
Groq is fast, ideal for day-to-day coding:
{
"provider": {
"groq": {
"type": "openai",
"baseURL": "https://api.groq.com/openai/v1",
"apiKey": "${GROQ_API_KEY}"
}
},
"model": "llama-3.3-70b-versatile"
}
DeepSeek is strong at reasoning — algorithm problems and code review:
{
"provider": {
"deepseek": {
"type": "openai",
"baseURL": "https://api.deepseek.com/v1",
"apiKey": "${DEEPSEEK_API_KEY}"
}
},
"model": "deepseek-reasoner"
}
Starting a Session
cd my-project
opencode
Inside the interactive UI, common commands:
add file path — include a file in the AI context/model groq/llama-3.3-70b — switch model at runtime/clear — wipe the current conversation historyexit or Ctrl+D — quit
Common Pitfalls
- PATH not picked up: re-source
~/.bashrc or restart the shell before retrying opencode.
- 401 Unauthorized: check that
OPENROUTER_API_KEY is exported into the current shell and that the config uses the ${ENV_VAR} reference syntax.
- 429 Too Many Requests: free tiers have RPM and TPM limits. Don't fire dozens of requests in a single burst, or rotate
:free models.
- Streaming stalls: Groq is consistently fast; OpenRouter
:free can lag during peak hours — switch to Groq or DeepSeek direct.
- Windows WSL path confusion: always use
/mnt/c/... to reach the Windows drive from WSL; do not mix backslashes.
With OpenCode wired to free models, you have a zero-cost, scriptable, SSH-friendly AI coding assistant that behaves almost identically to Claude Code — at a bill of zero.