OpenCode 配置教程

OpenCode 是 SST 团队推出的 开源 AI 编程命令行工具，可视为 100% 开源的 Claude Code 替代品。它原生兼容 Anthropic API 协议，同时支持 OpenAI、Google、本地模型等多种 Provider。

通过 ClaudeHub 中转，可在 OpenCode 中使用 Claude、GPT、Gemini 等 700+ 模型，享受 1:1 充值、官方原版、不降智的中转服务。

适合谁用 OpenCode？

想用开源工具替代 Claude Code 的开发者
需要在多个模型间切换的团队
关心代码安全审计、希望工具本身可审计的用户
想自定义命令、Hooks、Agent 行为的高级用户

前置要求

Node.js 18+ 或 Bun（任选其一）
ClaudeHub API Key（获取教程）

第一步：安装 OpenCode

bash

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

bash

npm install -g opencode-ai

bash

bun install -g opencode-ai

bash

brew install sst/tap/opencode

powershell

# 推荐使用 npm 或一键脚本（需 WSL/Git Bash）
npm install -g opencode-ai

验证安装：

bash

opencode --version

如果显示版本号说明安装成功。

第二步：设置环境变量（推荐方式）

OpenCode 默认 Provider 是 Anthropic，直接复用 Claude Code 同款环境变量即可：

变量名	值
`ANTHROPIC_BASE_URL`	`https://api.qinzhiai.com`
`ANTHROPIC_API_KEY`	`sk-你的API密钥`（获取教程）

macOS / LinuxWindows PowerShell

bash

# 临时设置（当前会话有效）
export ANTHROPIC_BASE_URL="https://api.qinzhiai.com"
export ANTHROPIC_API_KEY="sk-你的API密钥"

# 永久设置（zsh）
echo 'export ANTHROPIC_BASE_URL="https://api.qinzhiai.com"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-你的API密钥"' >> ~/.zshrc
source ~/.zshrc

# 永久设置（bash）
echo 'export ANTHROPIC_BASE_URL="https://api.qinzhiai.com"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-你的API密钥"' >> ~/.bashrc
source ~/.bashrc

powershell

# 临时设置（当前会话有效）
$env:ANTHROPIC_BASE_URL = "https://api.qinzhiai.com"
$env:ANTHROPIC_API_KEY = "sk-你的API密钥"

# 永久设置（推荐）
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.qinzhiai.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-你的API密钥", "User")

# 设置后需要重启终端

记得替换 API 密钥

将 sk-你的API密钥 替换为你在获取 API Key 中创建的实际密钥。

第三步：使用配置文件（可选）

如果你需要在多个 Provider 之间切换，或者想把配置纳入项目版本管理，可以使用配置文件。

全局配置

在 ~/.config/opencode/opencode.json（Windows: %USERPROFILE%\.config\opencode\opencode.json）中：

json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.qinzhiai.com",
        "apiKey": "sk-你的API密钥"
      }
    }
  },
  "model": "anthropic/claude-opus-4-7"
}

项目级配置

在项目根目录创建 opencode.json：

json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.qinzhiai.com",
        "apiKey": "sk-你的API密钥"
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-6"
}

同时配置多个 Provider

ClaudeHub 也提供 OpenAI 兼容接口（https://api.qinzhiai.com/v1），可以同时挂多个 Provider 调用 GPT / Gemini 等模型：

json

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.qinzhiai.com",
        "apiKey": "sk-你的API密钥"
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://api.qinzhiai.com/v1",
        "apiKey": "sk-你的API密钥"
      }
    }
  },
  "model": "anthropic/claude-opus-4-7"
}

之后用 /model 命令在 Claude / GPT 之间快速切换。

第四步：启动 OpenCode

bash

# 进入项目目录
cd your-project

# 启动 OpenCode
opencode

首次启动会让你选择主题、确认权限等，跟着提示走即可。

用途	推荐模型	推荐分组
复杂推理 / 大型重构	`claude-opus-4-7`	`Claude_code_1`
日常编程	`claude-sonnet-4-6`	`Claude_code`
快速响应 / 简单任务	`claude-haiku-4-5-20251001`	`Claude_code`
长上下文阅读	`claude-sonnet-4-6`	`Claude_code`

常用斜杠命令

命令	功能
`/help`	显示帮助信息
`/model`	切换 AI 模型
`/clear`	清除当前对话历史
`/compact`	压缩上下文
`/share`	分享当前会话（开源特性）
`/init`	初始化 AGENTS.md（项目说明文件）
`/cost`	查看本次会话消耗
`/exit`	退出 OpenCode

最佳实践

1. 创建 AGENTS.md（推荐）

OpenCode 默认读取项目根目录的 AGENTS.md 作为系统提示，相当于 Claude Code 的 CLAUDE.md：

markdown

# 项目说明

这是一个 Next.js 14 + TypeScript + Tailwind 项目。

## 开发规范

- 使用 React Server Components 优先
- 组件文件用 PascalCase
- 类型定义放在 `types/` 目录
- 提交前必须跑 `pnpm lint` 和 `pnpm typecheck`

## 禁止操作

- 不要修改 `.env.local`
- 不要随意改 `package.json` 的依赖版本

2. 用文件引用提升精度

解释 @src/lib/auth.ts 中的 verifySession 函数

对比 @app/api/users/route.ts 和 @app/api/posts/route.ts 的鉴权差异

3. 善用 `/share` 协作

OpenCode 的 /share 会生成一个公开链接，团队成员可以查看完整对话过程，便于代码审查与知识沉淀。

OpenCode vs Claude Code 对比

维度	OpenCode	Claude Code
开源	✅ MIT 协议	❌ 闭源
模型支持	Claude / GPT / Gemini / Ollama 本地等任意 Provider	仅 Claude 系列
自定义 Provider	✅ 配置文件灵活组合	⚠ 仅 ANTHROPIC_BASE_URL
会话分享	✅ 内置 `/share` 公开链接	需手动复制
AGENTS.md	✅ 原生支持	需用 CLAUDE.md
终端 UI	现代 TUI（多 tab、状态栏）	文本流
适合场景	开源团队、多模型用户、深度自定义	Anthropic 重度用户、个人开发

两个一起用？

完全可以。环境变量是同一套，安装两个工具不冲突。日常用 Claude Code，需要切 GPT / Gemini 时跑 opencode。

常见问题

提示「无法连接到 API」

排查顺序：

确认环境变量已设置：

macOS / LinuxWindows

bash

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY

powershell

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_API_KEY

确认 Base URL 是 https://api.qinzhiai.com（不带 /v1 后缀，Anthropic 协议）
确认 API Key 在控制台是激活状态
检查网络是否能访问 api.qinzhiai.com

提示「模型 not found」

OpenCode 的模型 ID 格式是 provider/model-id，例如：

✅ anthropic/claude-opus-4-7
✅ anthropic/claude-sonnet-4-6
❌ claude-opus-4-7（缺 provider 前缀）

想同时用 GPT / Gemini

参见上面第三步的「同时配置多个 Provider」示例。

与 Claude Code 的环境变量冲突吗？

不冲突。两者用的是完全相同的 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY，配置一次两个工具都能用。

配置文件位置在哪

系统	全局配置	项目配置
macOS / Linux	`~/.config/opencode/opencode.json`	项目根目录 `opencode.json`
Windows	`%USERPROFILE%\.config\opencode\opencode.json`	项目根目录 `opencode.json`

计费如何查看？

登录控制台 → 日志 → 使用日志，每次请求都有详细 Token 消耗与计费明细。

OpenCode 配置教程

前置要求

第一步：安装 OpenCode

第二步：设置环境变量（推荐方式）

第三步：使用配置文件（可选）

全局配置

项目级配置

第四步：启动 OpenCode

推荐模型和分组

常用斜杠命令

最佳实践

1. 创建 AGENTS.md（推荐）

2. 用文件引用提升精度

OpenCode vs Claude Code 对比

常见问题

提示「无法连接到 API」

提示「模型 not found」

想同时用 GPT / Gemini

与 Claude Code 的环境变量冲突吗？

配置文件位置在哪

计费如何查看？

更多资源

OpenCode 配置教程 ​

前置要求 ​

第一步：安装 OpenCode ​

第二步：设置环境变量（推荐方式） ​

第三步：使用配置文件（可选） ​

全局配置 ​

项目级配置 ​

第四步：启动 OpenCode ​

推荐模型和分组 ​

常用斜杠命令 ​

最佳实践 ​

1. 创建 AGENTS.md（推荐） ​

2. 用文件引用提升精度 ​

3. 善用 /share 协作 ​

OpenCode vs Claude Code 对比 ​

常见问题 ​

提示「无法连接到 API」 ​

提示「模型 not found」 ​

想同时用 GPT / Gemini ​

与 Claude Code 的环境变量冲突吗？ ​

配置文件位置在哪 ​

计费如何查看？ ​

更多资源 ​

OpenCode 配置教程

前置要求

第一步：安装 OpenCode

第二步：设置环境变量（推荐方式）

第三步：使用配置文件（可选）

全局配置

项目级配置

第四步：启动 OpenCode

推荐模型和分组

常用斜杠命令

最佳实践

1. 创建 AGENTS.md（推荐）

2. 用文件引用提升精度

3. 善用 `/share` 协作

OpenCode vs Claude Code 对比

常见问题

提示「无法连接到 API」

提示「模型 not found」

想同时用 GPT / Gemini

与 Claude Code 的环境变量冲突吗？

配置文件位置在哪

计费如何查看？

更多资源