搭建 · 部署 · 使用
安装、配置与使用指南
从零开始安装 opencode、配置 API Key、设定全局与项目级选项，掌握 TUI 交互模式与非交互单命令执行，了解插件安装与 Slash 命令速查。
📋 系统要求
Bun
≥ 1.0
主运行时，替代 Node.js + npm
Node.js
≥ 20.x
部分工具链辅助需要
LLM API Key
任意 Provider
Anthropic / OpenAI / Google 等
如使用 Ollama 本地模型，则无需 API Key。opencode 支持任何实现了 OpenAI API 规范的本地或私有端点，包括 LM Studio、vLLM 等。
📦 安装方式
opencode 提供四种安装方式，推荐使用官方脚本一键安装，也可通过 Homebrew、npm 或源码构建。
官方安装脚本自动检测平台，下载最新预编译二进制文件并配置 PATH。
curl -fsSL https://opencode.ai/install | bash
# 验证安装
opencode --version
安装位置：~/.local/bin/opencode，脚本会自动追加至 PATH。
Homebrew 用户可通过 SST 官方 tap 安装，支持 brew upgrade 自动更新。
brew install sst/tap/opencode
# 更新到最新版
brew upgrade opencode
通过 npm 全局安装，适合已有 Node.js 环境、无需 Bun 的场景。
npm install -g opencode-ai
# 或使用 npx 零安装运行
npx opencode-ai
npm 包名为 opencode-ai（含后缀），命令仍为 opencode。
从源码构建适合贡献者和需要最新 commit 的场景。
git clone https://github.com/sst/opencode
cd opencode
bun install
bun run build
# 将 opencode 链接至全局可执行
bun link
# 验证
opencode --version
🔑 认证 · API Key 配置
opencode 支持两种认证方式：交互式浏览器登录（opencode.ai 账号）或直接设置 Provider 环境变量。
方式一：浏览器交互登录
# 打开浏览器完成 OAuth 流程
opencode auth login
# 查看当前登录状态
opencode auth status
方式二：环境变量（推荐 CI/CD 场景）
# Anthropic Claude（推荐）
export ANTHROPIC_API_KEY=sk-ant-...
# OpenAI GPT 系列
export OPENAI_API_KEY=sk-...
# Google Gemini
export GOOGLE_GENERATIVE_AI_API_KEY=AIza...
# 写入 ~/.bashrc 或 ~/.zshrc 永久生效
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
使用 Ollama 本地模型时无需任何 API Key，只需保证 Ollama 服务在本地运行（默认 http://localhost:11434），opencode 会自动发现。
⚙️ 全局配置文件
全局配置保存在 ~/.config/opencode/opencode.json，控制默认模型、自动分享、插件列表等行为。
{
"model": "anthropic/claude-sonnet-4-5",
"autoshare": false,
"plugin": [
"superpowers@git+https://github.com/owner/repo"
],
"experimental": {
"chat": {
"system": {
"transform": "return system + extraContext"
}
}
}
}
配置字段说明：
model
默认使用的 LLM，格式为 provider/model-name，如 openai/gpt-4o、google/gemini-2.0-flash。
autoshare
是否自动将每个 session 发布到 opencode.ai，默认 false，设为 true 后无需手动 --share。
plugin
插件列表，支持 npm 包名或 git+https:// URL。opencode 启动时自动加载并注册插件中的技能。
experimental.
chat.system.
transform JS 表达式字符串，在构建 system prompt 时执行。可访问 system（基础提示）和 extraContext 变量，返回值替换最终 system prompt。
chat.system.
transform JS 表达式字符串，在构建 system prompt 时执行。可访问 system（基础提示）和 extraContext 变量，返回值替换最终 system prompt。
📁 项目级配置
在项目根目录创建 .opencode/ 目录可覆盖全局配置，实现团队共享的项目专属行为。项目级配置优先级高于全局配置。
your-project/
├── .opencode/
│ ├── config.json # 项目级配置（覆盖全局）
│ └── skills/
│ ├── frontend.md # 项目专属技能
│ └── api-patterns.md # API 规范技能
├── AGENTS.md # 项目级 system prompt 追加
└── ...
AGENTS.md — 项目系统提示
AGENTS.md 的内容会自动追加至 system prompt，用于告知 AI 项目的技术栈、约定、注意事项等。
# AGENTS.md 示例
## 项目简介
这是一个 FastAPI + Tortoise ORM 的微服务项目。
## 技术约定
- 所有 API 路径使用 kebab-case
- 响应体统一使用 app.core.response.success() 包装
- 模型继承 MySQLModel 或 SQLiteModel，不使用原生 ORM
## 禁止操作
- 不得修改 deploy/ 目录下的生产配置
- 不得在 main.py 中添加业务逻辑
技能解析优先级
opencode 按以下顺序从三个位置加载技能，前者优先级更高：
① 最高优先级
项目技能
.opencode/skills/*.md
→
② 个人技能
全局技能
~/.config/opencode/skills/
→
③ 最低优先级
插件技能
Plugin 注册的技能
▶️ 运行模式
🖥️ TUI 交互模式
全功能终端 UI，支持多轮对话、slash 命令、实时流式输出。
cd your-project
opencode
⚡ 单命令非交互
适合 CI/CD、脚本集成，执行后退出，返回码 0 表示成功。
opencode -p "Fix TypeScript errors in src/"
🔌 指定模型
命令行覆盖配置文件中的默认模型，格式 provider/model。
opencode --model openai/gpt-4o
opencode --model ollama/llama3.2
🔗 Session 共享
生成公开 URL，团队成员可实时查看 AI 操作过程。
opencode --share
# → https://opencode.ai/s/abc123
完整命令行参数
| 参数 | 简写 | 说明 | 示例 |
|---|---|---|---|
| --prompt | -p | 非交互执行，传入提示词 | opencode -p "add tests" |
| --model | -m | 指定 LLM provider/model | --model anthropic/claude-opus-4 |
| --share | — | 发布 session 获取公开 URL | opencode --share |
| --no-auto-compact | — | 禁用自动 context 压缩 | opencode --no-auto-compact |
| --version | -v | 显示版本号 | opencode --version |
| --help | -h | 显示帮助信息 | opencode --help |
🧩 插件安装
opencode 插件通过 config.json 的 plugin 数组声明。插件可以提供额外的技能（SKILL.md 集合）、自定义工具或扩展行为。
# ~/.config/opencode/opencode.json
{
"plugin": [
// npm 包
"opencode-plugin-example",
// GitHub 仓库（git+ 协议）
"superpowers@git+https://github.com/owner/repo",
// 带版本号的 npm 包
"opencode-skills-react@^2.0.0"
]
}
修改 plugin 配置后，下次启动 opencode 时会自动安装新插件。插件安装位置：~/.config/opencode/plugins/。
自定义 SKILL.md 技能格式
创建 .opencode/skills/my-skill.md 即可定义项目专属技能。opencode 在会话启动时自动语义匹配并注入相关技能。
---
name: frontend-design
description: Use when building React/UI components or styling with Tailwind CSS
---
## 前端设计规范
### 组件结构
- 使用 shadcn/ui 组件库，避免重复造轮子
- 样式优先使用 Tailwind CSS utility classes
- 组件文件使用 PascalCase 命名
### 响应式设计
- 移动优先原则，断点顺序：sm → md → lg → xl
- 最小点击区域 44x44px
### 可访问性
- 所有图片必须有 alt 属性
- 表单元素必须关联 label
⌨️ Slash 命令速查
在 TUI 交互模式下，输入 / 开头的命令可触发特殊功能。
| 命令 | 功能描述 | 备注 |
|---|---|---|
| /model | 切换 LLM Provider 或模型 | 交互式选择菜单，即时生效 |
| /theme | 切换终端配色主题 | 内置多套主题，实时预览 |
| /share | 发布当前 session 获取公开 URL | 发布至 opencode.ai console |
| /compact | 压缩对话历史，扩展有效 context 窗口 | 用摘要替换原始消息，保留关键信息 |
| /help | 显示所有可用命令列表 | 含插件注册的额外命令 |
| /clear | 清空当前对话，开启新 session | 不影响历史记录文件 |
| /undo | 撤销上一条消息 | 从 session 中移除最后交互 |
🌍 环境变量速查
| 变量名 | Provider | 说明 |
|---|---|---|
| ANTHROPIC_API_KEY | Anthropic | Claude 系列模型访问密钥 |
| OPENAI_API_KEY | OpenAI | GPT / o-series 模型访问密钥 |
| GOOGLE_GENERATIVE_AI_API_KEY | Gemini 系列模型访问密钥 | |
| AZURE_OPENAI_API_KEY | Azure | Azure OpenAI 服务密钥 |
| OPENCODE_SHARE | — | 设为 true 等同于 --share 标志 |
| OPENCODE_MODEL | — | 默认模型，覆盖 config.json 中的 model |
🔄 更新与卸载
# 更新（官方脚本安装）
curl -fsSL https://opencode.ai/install | bash
# 更新（Homebrew）
brew upgrade opencode
# 更新（npm）
npm update -g opencode-ai
# 卸载（官方脚本安装）
rm ~/.local/bin/opencode
rm -rf ~/.config/opencode # 可选：删除配置
opencode · Anomaly / SST · github.com/sst/opencode
深度文档 · 2026-05-22