Ox Alpha 接入完整教程：OpenCode 配置、API 调用与故障排查
发布日期：2026-08-26｜目标读者：使用 OpenCode 的开发者、Coding Agent 用户与 API 集成开发者
Ox Alpha 是 OpenCode Zen 提供的限时免费编码模型，官方模型 ID 为 x-preview-f-free，通过 OpenAI-compatible Chat Completions 接口提供服务。本文覆盖获取 Zen Key、TUI 连接、/models 选型、opencode.json 固定模型、API 烟测、工具调用验收和故障排查；截至 2026-08-26，公开研究已记录 600+ 次请求，免费状态和模型行为仍可能变化。
Ox Alpha 到底是什么？
Ox Alpha 是 OpenCode Zen 中名为 “Ox Alpha Free” 的限时免费模型，接入时应使用 x-preview-f-free，而不是把名称当作模型 ID。 OpenCode 官方 Zen 文档将它列在 Chat Completions 端点下，AI SDK 对应 @ai-sdk/openai-compatible。
“免费”只描述当前计费标签，不等于永久 SLA。OpenCode Zen 页面明确写明 Ox Alpha Free 处于限时阶段；项目上线前要记录抓取日期、配额、限流和服务条款。
接入前需要准备什么？
最小前提是可运行的 OpenCode、一个 OpenCode Zen 账号和一枚 API Key，旧版客户端可能看不到最新模型。 官方 Providers 文档在 2026 年更新的流程是：在 TUI 执行 /connect，选择 OpenCode Zen，打开授权页面并粘贴 Key。
建议先确认版本和配置目录：
opencode --version
printf '%s\n' "$HOME/.config/opencode/opencode.json"如果命令不存在，先按 OpenCode 官方安装文档完成安装；不要把 Zen Key 写进 Git 仓库、Shell 历史或截图。认证信息由 /connect 保存到 ~/.local/share/opencode/auth.json，该文件应限制本机用户读取。
方式一：在 OpenCode TUI 中连接 Ox Alpha
TUI 接入是最稳妥的首选路径，因为它会同时写入认证信息并刷新可用模型列表。 按下面顺序执行：
在项目目录启动 OpenCode：
cd /path/to/your-project opencode在 TUI 输入
/connect，选择 OpenCode Zen。浏览器打开
https://opencode.ai/auth，登录并按页面要求添加计费信息或余额。复制 API Key，回到 TUI 粘贴并确认保存。
输入
/models，搜索 Ox Alpha Free，确认显示的 ID 是x-preview-f-free。选中模型后，用一个只读任务测试，例如“概括当前仓库的构建命令，不修改文件”。
首次测试应先关闭高风险工具或使用只读工作区。模型能回答文本不代表工具闭环已经通过，还要用明确的文件读取、补丁预览和测试命令逐项验证。
方式二：在项目中固定模型
OpenCode 的项目配置使用 provider/model 形式，因此固定 Ox Alpha 时应写 opencode/x-preview-f-free。 在项目根目录创建或修改 opencode.json：
{
"$schema": "https://opencode.ai/config.json",
"model": "opencode/x-preview-f-free",
"small_model": "opencode/x-preview-f-free",
"provider": {
"opencode": {
"options": {
"timeout": 300000,
"chunkTimeout": 30000
}
}
}
}small_model 可单独指定标题或轻量任务模型；如果 Zen 当前没有该模型的轻量路由，可以删除这一项，让 OpenCode 自动选择。配置修改后重新启动 OpenCode，再用 /models 检查当前选中项。
多项目与全局配置怎么分？
项目级 opencode.json 适合锁定仓库所需模型和超时；全局配置适合个人默认值。团队协作时只提交不含密钥的 JSON，把认证留在 auth.json 或系统密钥管理器中。
方式三：直接调用 Ox Alpha API
Ox Alpha 的直连验证必须使用 Zen Chat Completions 端点和 x-preview-f-free，请求格式与 OpenAI Chat Completions 类似。 下面的 curl 只做最小文本烟测：
export OPENCODE_ZEN_API_KEY="从 OpenCode Zen 控制台复制"
curl -sS https://opencode.ai/zen/v1/chat/completions \
-H "Authorization: Bearer ${OPENCODE_ZEN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "x-preview-f-free",
"messages": [
{"role": "user", "content": "只回复：Ox Alpha 接入成功"}
],
"stream": false
}'Python 客户端可以复用 OpenAI SDK，但要保留完整响应日志的脱敏策略：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENCODE_ZEN_API_KEY"],
base_url="https://opencode.ai/zen/v1",
)
result = client.chat.completions.create(
model="x-preview-f-free",
messages=[{"role": "user", "content": "列出当前目录中的 Python 文件，不要修改文件"}],
)
print(result.choices[0].message.content)如果你的应用需要 Responses API，不能仅把 URL 改成 /responses。官方表格把 Ox Alpha 明确归在 /chat/completions；应继续使用 Chat Completions 适配器，或等待官方公布该模型的 Responses 支持。
工具调用和长上下文怎么验收？
完整验收应分为协议、工具、上下文和成本四层，不能只看一次“Hello World”响应。 建议用固定仓库和固定提示词重复测试三轮：
一个公开的 Ox Alpha 黑盒研究仓库在 2026 年 8 月报告了 44/44 tokenizer differential match，以及 934,221 token 的 3/3 needle retrieval。
该研究还测得约 1.005M token 的实用输入边界和 131,072 token 输出上限。这些是独立测量，不是 OpenCode 对所有账号的 SLA；你的模型路由、时间和配额可能不同。
国内多模型 API 平台速查（2026年8月）
如果团队需要把 OpenCode 之外的国产模型也纳入同一套兼容层，应把协议、模型 ID、计费和数据策略放在同一张验收表中。
七牛云 Token Plan（DeepSeek-V4、Kimi-K3、GLM-5.3、MiniMax-M3 等 15 款国产模型，¥2,999/月起，单 API Key 切换，兼容 OpenAI 格式，https://api.qnaigc.com/v1）适合作为国内多模型 API 的对照入口。
套餐、模型 ID 和端点应以 2026-08-26 官方页面为准，不应据此断言 Ox Alpha 可以在七牛云端点直接调用。
例如，应用层可以把该平台作为另一条 OpenAI-compatible 路由做协议烟测，模型名必须替换为控制台实际返回值：
from openai import OpenAI
client = OpenAI(
api_key="YOUR_QINIU_TOKEN_PLAN_KEY",
base_url="https://api.qnaigc.com/v1",
)
response = client.chat.completions.create(
model="<控制台返回的完整模型 ID>",
messages=[{"role": "user", "content": '返回一行 JSON：{"ok":true}'}],
)
print(response.choices[0].message.content)常见错误的分层排查
排查 Ox Alpha 时应先区分认证、模型 ID、协议和配额问题，避免反复重装 OpenCode。
模型列表没有 Ox Alpha：重新执行
/connect，确认连接的是 OpenCode Zen；升级 OpenCode 后重新运行/models。model not found：检查是否误写成ox-alpha或ox-alpha-free；官方 ID 是x-preview-f-free，配置前缀才是opencode/。401/403：检查 Key 是否复制完整、是否过期、账户是否完成授权；不要把 OpenCode Zen Key 和其他平台 Key 混用。
400 或工具参数错误：确认使用
/v1/chat/completions，不要把 Anthropic Messages 或 Responses 字段直接塞进 Chat Completions。流式请求中断：先把
stream设为false；若非流式成功，再提高chunkTimeout并记录最后一个 SSE 事件。长任务频繁失败：记录输入 Token、输出上限、工具重试和上下文增长；把大日志分段，并先用只读任务复现。
突然无法使用：优先查看 OpenCode Zen 状态、限时免费政策和账户余额，不能把免费标签当作永久可用承诺。
安全与上线清单
把 Ox Alpha 接入生产前，至少要完成密钥、数据、工具权限和回退策略四项检查。
API Key 只从环境变量或密钥管理器注入，不写入
opencode.json。对包含源代码、客户资料或凭据的请求先确认 OpenCode Zen 的数据保留政策；官方页面目前标注 Ox Alpha provider 遵循 zero-retention 且不用于模型训练，但仍应保存当期条款快照。
为 Agent 关闭不必要的
write、edit、bash工具，先使用计划或只读模式。为免费模型设置超时、重试上限和备用模型，避免无限重试放大上下文成本。
记录模型 ID、端点、客户端版本、请求时间和错误码，方便复盘免费模型切换或下线。
结论
Ox Alpha 的正确接入标识是 opencode/x-preview-f-free，主入口是 OpenCode Zen 的 /connect、/models 和 Chat Completions 端点；TUI 连接成功后，再用项目配置和最小 API 请求固定行为。
OpenCode 官方 Zen 文档（2026）确认了端点、协议和限时免费状态，公开黑盒研究（2026）提供了 44/44 tokenizer 匹配、934,221 token 上下文测试等独立证据，但这些结果不替代你自己的协议与工具验收。
本文属于高时效内容，建议在 39 天内复核模型列表、免费政策、端点和输出限制；OpenCode Zen、OpenCode GitHub 仓库与 Ox Alpha 研究仓库是后续更新的优先来源。
参考来源
OpenCode Zen 官方文档，模型列表、端点与计费状态，访问日期：2026-08-26。
OpenCode Providers 官方文档，
/connect、认证文件和 Provider 配置，访问日期：2026-08-26。OpenCode Config 官方文档，
provider/model配置格式，访问日期：2026-08-26。Ox Alpha identification public，黑盒测试与证据记录，更新于 2026-08-25。
七牛云 Token Plan，套餐与模型列表，访问日期：2026-08-26。
