OpenCode Zen 实战教程：快速接入精选 AI 模型

📚 分类: AI 模型接入 / OpenCode 工具链 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode（TUI 或 CLI 版本）、一个 OpenCode Zen 账户

你将学到什么

完成本教程后，你将能够：

[ ] 理解 OpenCode Zen 是什么以及它解决了什么问题
[ ] 注册并获取 OpenCode Zen API 密钥
[ ] 在 OpenCode 中配置并使用 Zen 提供的精选模型
[ ] 了解 Zen 的定价模式、自动充值及团队管理功能
[ ] 自行通过 API 端点调用 Zen 模型

最终效果

完成本教程后，你将在 OpenCode 中拥有一个可直接使用的“Zen”提供商，可以自由切换 GPT-5.5、Claude Opus 4.8、Gemini 3.5 Flash 等经过 OpenCode 团队测试和优化的编码代理模型。你只需按使用量付费，无需再为配置各种提供商而烦恼。

前置准备

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

检查项	要求	验证命令
OpenCode	已安装（任意版本）	`opencode --version`
网络连接	可访问 `opencode.ai`	`ping opencode.ai`

1. 确保 OpenCode 已安装

如果你还没有安装 OpenCode，请先参考 OpenCode 官方安装指南完成安装。

✅ 验证：在终端运行 opencode --version，你应该看到类似 v1.2.3 的输出版本号。

第 1 步：注册 OpenCode Zen 账户并获取 API 密钥

🎯 目标：拥有一个 OpenCode Zen 账户，并生成一个可用于配置的 API 密钥。

📝 操作：

打开浏览器，访问 https://opencode.ai/zen
如果你还没有 OpenCode 账户，点击 Sign Up 进行注册（可以使用 GitHub 或 Google 账号快速登录）
登录后，进入 Zen 部分，你会看到一个仪表盘
点击 Create API Key 按钮
给你的密钥起一个名字（例如 my-zen-key），然后点击 Create
复制生成的 API 密钥（⚠️ 注意：关闭页面后你将无法再次查看完整密钥，请立即保存到安全位置）

✅ 验证：你应该看到类似 sk-zen-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 格式的密钥字符串。同时，Zen 仪表盘上会显示你的密钥列表。

💡 提示：你可以创建多个 API 密钥，用于不同的项目或团队，方便管理。

第 2 步：在 OpenCode 中配置 Zen 提供商

🎯 目标：将 OpenCode 连接到你的 Zen 账户，使其能够调用 Zen 提供的模型。

📝 操作：

打开终端，启动 OpenCode TUI（文本用户界面）：
bash
```
$ opencode
```
在 OpenCode TUI 中，输入 /connect 命令：
bash
```
/connect
```
系统会显示一个提供商列表。使用方向键选择 OpenCode Zen，然后按回车。
系统会提示你输入 API 密钥。粘贴上一步中复制的密钥（sk-zen-...），然后按回车。

✅ 验证：你应该看到类似以下的成功提示：

text

✅ 成功连接到 OpenCode Zen

💡 提示：你也可以通过配置文件手动添加 Zen 提供商。配置文件通常位于 ~/.opencode/config.yaml，添加以下内容：

yaml

# ~/.opencode/config.yaml
providers:
  - name: zen
    type: opencode-zen
    api_key: sk-zen-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 替换为你的密钥

第 3 步：查看可用模型列表

🎯 目标：了解 Zen 提供了哪些模型，并选择一个适合你的任务。

📝 操作：

在 OpenCode TUI 中，输入 /models 命令：

bash

/models

系统会显示 Zen 提供的所有可用模型列表，包括模型名称、ID、提供商和定价等信息。例如：

text

可用模型：
┌─────────────────────────────────────────────────────────────────┐
│ 模型名称                │ 模型 ID              │ 提供商         │
├─────────────────────────┼──────────────────────┼────────────────┤
│ GPT 5.5                 │ opencode/gpt-5.5     │ OpenAI         │
│ Claude Opus 4.8         │ opencode/claude-opus-4-8 │ Anthropic  │
│ Gemini 3.5 Flash        │ opencode/gemini-3.5-flash │ Google    │
│ ...                     │ ...                  │ ...            │
└─────────────────────────────────────────────────────────────────┘

✅ 验证：你应该能看到一个包含数十个模型的表格，涵盖了 GPT、Claude、Gemini、Qwen、DeepSeek 等多个系列。

💡 提示：

模型 ID 的格式是 opencode/<model-id>，例如 opencode/gpt-5.5
你可以在 /models 输出中查看模型的输入/输出价格，以及缓存价格

第 4 步：在会话中选择并使用 Zen 模型

🎯 目标：在 OpenCode 会话中切换到一个 Zen 模型，并开始使用它。

📝 操作：

在 OpenCode TUI 中，创建一个新的会话或进入现有会话。
输入 /model 命令来切换模型：
bash
```
/model opencode/gpt-5.5
```
等待模型加载完成。你会看到类似以下信息：
text
```
已切换到模型: opencode/gpt-5.5
```
现在你可以像使用其他模型一样，向它发送消息。例如：
bash
```
写一个 Python 函数，计算斐波那契数列的第 n 项。
```

✅ 验证：模型应该会返回一个 Python 函数实现。如果能看到响应，说明配置成功。

🤔 为什么要这样做？ OpenCode Zen 的模型 ID 统一采用 opencode/<model-id> 格式，这让你可以像使用本地模型一样使用云端模型，而无需关心底层的 API 兼容性问题。Zen 会自动处理路由、认证和格式转换。

⚠️ 常见错误：如果收到错误 Model not found，请检查模型 ID 是否正确。你可以通过 /models 命令重新查看可用列表。

第 5 步：了解定价与自动充值（可选）

🎯 目标：了解 Zen 的计费模式，避免意外超支。

📝 操作：

登录 OpenCode Zen 仪表盘
点击左侧菜单的 Billing（账单）
查看你的当前余额和使用情况

✅ 验证：你应该能看到你的余额、本月已使用金额，以及自动充值设置。

💡 关键信息：

自动充值：默认情况下，当余额低于 $5 时，Zen 会自动充值 $20。你可以在仪表盘中更改自动充值金额或完全禁用它。
月度限额：你可以为整个工作区或单个成员设置月度使用限额。例如，设置为 $20 后，一个月内最多只会消费 $20。
信用卡手续费：每笔交易会收取 4.4% + $0.30 的手续费，这是按成本转嫁的，Zen 本身不额外加价。

⚠️ 注意：如果你设置了月度限额并启用了自动充值，当余额低于 $5 时自动充值可能会使当月总消费超过月度限额。

第 6 步：通过 API 直接调用 Zen 模型（进阶）

🎯 目标：了解如何通过 REST API 直接调用 Zen 模型，而无需通过 OpenCode TUI。

📝 操作：

Zen 提供 OpenAI 兼容的 API 端点。你可以使用任何支持 OpenAI API 格式的客户端（如 curl、Python 的 openai 库）来调用它。

示例：使用 curl 调用 GPT-5.5

bash

$ curl https://opencode.ai/zen/v1/responses \
  -H "Authorization: Bearer sk-zen-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/gpt-5.5",
    "input": "Hello, how are you?"
  }'

示例：使用 Python 的 openai 库

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-zen-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://opencode.ai/zen/v1"
)

response = client.chat.completions.create(
    model="opencode/gpt-5.5",
    messages=[{"role": "user", "content": "Hello, how are you?"}]
)

print(response.choices[0].message.content)

✅ 验证：你应该能收到模型的响应，内容类似 I'm doing well, thank you! How can I help you today?

💡 提示：

不同系列的模型使用不同的端点路径，请参考模型列表中的“端点”列
对于 OpenAI 系列模型（GPT、DeepSeek 等），使用 /v1/responses 或 /v1/chat/completions
对于 Anthropic 系列模型（Claude），使用 /v1/messages
对于 Google 系列模型（Gemini），使用 /v1/models/{model_id}

进阶技巧（可选）

1. 团队协作

Zen 支持团队工作区，你可以邀请队友并分配角色：

Admin：管理模型、成员、API 密钥和账单
Member：仅管理自己的 API 密钥

在仪表盘中点击 Team，然后点击 Invite Member，输入队友的邮箱即可。

2. 模型访问控制

作为 Admin，你可以为工作区启用或禁用特定模型。这对于控制成本或防止使用数据收集模型（如免费模型）非常有用。

3. 自带密钥 (BYOK)

如果你已经拥有 OpenAI 或 Anthropic 的 API 密钥，你可以在 Zen 中配置它们，使用自己的密钥调用这些模型。这样，这些模型的 tokens 会由你的提供商直接计费，而不是通过 Zen。

在仪表盘的 Settings → API Keys 中添加你的密钥即可。

常见问题 (FAQ)

Q1: 为什么我连接 Zen 后，模型列表是空的？A: 请检查你的 API 密钥是否有效。如果密钥无效或已过期，Zen 将无法返回模型列表。尝试在仪表盘中重新生成一个密钥。

Q2: 使用 Zen 模型时，我的数据会被用于训练吗？A: 大部分模型遵循零保留政策，不会将你的数据用于训练。但请注意：

免费模型（Big Pickle、DeepSeek V4 Flash Free、MiMo-V2.5 Free）：在免费期间，收集的数据可能会被用于改进模型。
OpenAI 和 Anthropic 的模型：请求会根据它们的数据政策保留 30 天。
如果你有隐私顾虑，建议使用付费模型，或禁用会收集数据的模型。

Q3: 如何设置月度限额？A: 在 Zen 仪表盘中进入 Billing → Monthly Limit，输入你想要的金额（例如 $20），然后保存即可。你也可以为团队中的每个成员单独设置限额。

Q4: 为什么我看到已弃用的模型？A: 已弃用的模型仍然可以使用，但会在指定日期后停止服务。建议尽快迁移到替代模型。你可以在 /models 输出中查看模型的弃用状态。

Q5: 如何获取完整的模型元数据？A: 你可以通过 API 端点 https://opencode.ai/zen/v1/models 获取所有可用模型的完整列表，包括 ID、名称、提供商、定价等信息。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

OpenCode Zen 是什么：一个由 OpenCode 团队提供的精选模型网关，解决了模型选择、配置和性能优化的问题。
配置流程：注册账户 → 获取 API 密钥 → 在 OpenCode 中 /connect → 选择模型 /model。
定价模式：按量付费，按 tokens 计费，支持自动充值和月度限额，免费模型限时提供。
团队功能：支持工作区、角色分配、模型访问控制和成员限额。
API 调用：提供 OpenAI 兼容的 REST API，可直接通过 curl 或编程语言调用。

下一步

如果你想继续深入，建议学习：

📖 OpenCode 官方文档 - 高级配置：学习如何自定义模型参数、使用工具和插件。
📖 OpenCode Zen 定价详情：查看最新的模型价格和免费模型状态。
📖 OpenCode 团队管理：深入了解如何设置工作区和团队协作。

💡 练习任务：尝试在 OpenCode 中创建一个使用 Zen 模型的自动化脚本，让它每天自动生成一份技术报告摘要。这是巩固知识的最佳方式。

yaml


## 相关文档

- [终端 AI 编程实战指南：Claude Code 与 OpenCode 双工具上手](/docs/chu-ci-shi-yong/zhong-duan-ai-bian-cheng-shi-zhan-zhi-nan-claude-code-yu-opencode-shuang-gong-ju-shang-shou.html)
- [OpenCode 终端 AI 编程助手 实战教程](/docs/chu-ci-shi-yong/opencode-zhong-duan-ai-bian-cheng-zhu-shou-shi-zhan-jiao-cheng.html)
- [OpenCode 实战教程：在终端里玩转 AI 编程助手](/docs/chu-ci-shi-yong/opencode-shi-zhan-jiao-cheng-zai-zhong-duan-li-wan-zhuan-ai-bian-cheng-zhu-shou.html)

OpenCode Zen 实战教程：快速接入精选 AI 模型 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 确保 OpenCode 已安装 ​

第 1 步：注册 OpenCode Zen 账户并获取 API 密钥 ​

第 2 步：在 OpenCode 中配置 Zen 提供商 ​

第 3 步：查看可用模型列表 ​

第 4 步：在会话中选择并使用 Zen 模型 ​

第 5 步：了解定价与自动充值（可选） ​

第 6 步：通过 API 直接调用 Zen 模型（进阶） ​

进阶技巧（可选） ​

1. 团队协作 ​

2. 模型访问控制 ​

3. 自带密钥 (BYOK) ​

常见问题 (FAQ) ​

总结 ​

下一步 ​

OpenCode Zen 实战教程：快速接入精选 AI 模型

你将学到什么

最终效果

前置准备

1. 确保 OpenCode 已安装

第 1 步：注册 OpenCode Zen 账户并获取 API 密钥

第 2 步：在 OpenCode 中配置 Zen 提供商

第 3 步：查看可用模型列表

第 4 步：在会话中选择并使用 Zen 模型

第 5 步：了解定价与自动充值（可选）

第 6 步：通过 API 直接调用 Zen 模型（进阶）

进阶技巧（可选）

1. 团队协作

2. 模型访问控制

3. 自带密钥 (BYOK)

常见问题 (FAQ)

总结

下一步