OpenCode 接入

OpenCode 需要在 opencode.json 中显式注册自定义 provider。本站推荐走 OpenAI Responses，模型身份、日志和计费都保留真实 GPT-5.6 名称。

SDK@ai-sdk/openai

Base URLhttps://api.handsfreeclub.com/v1

模型handsfree/gpt-5.6-terra

30 秒摘要

准备 OPENAI_API_KEY，把下面 provider 合并进全局 opencode.json，再运行 opencode models handsfree 并选择 handsfree/gpt-5.6-terra。

准备环境变量

本站一键脚本只负责安全写入 Key 和 Base URL，不会覆盖 OpenCode 的 provider。已经运行过脚本的用户，重新打开终端即可。

检查变量（不显示 Key）

test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY 已加载" || echo "尚未加载"

注册 Handsfree provider

编辑 OpenCode 全局配置，保留原有 provider、MCP 和权限设置，只合并以下字段。{env:OPENAI_API_KEY} 让 Key 留在环境变量中。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "handsfree": {
      "npm": "@ai-sdk/openai",
      "name": "Handsfree Club",
      "options": {
        "baseURL": "https://api.handsfreeclub.com/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": { "name": "GPT-5.6 Sol" },
        "gpt-5.6-terra": { "name": "GPT-5.6 Terra" },
        "gpt-5.6-luna": { "name": "GPT-5.6 Luna" }
      }
    }
  },
  "model": "handsfree/gpt-5.6-terra"
}

配置位置：可放全局配置目录；如果放进项目根目录，务必确保没有真实 Key 且团队明确要共享该 provider。Key 不要直接写进 JSON。

验证并选模型

terminal / OpenCode TUI

opencode models handsfree
opencode

# TUI 内运行
/models

handsfree/gpt-5.6-sol高难度推理、架构与复杂调试

handsfree/gpt-5.6-terra默认推荐，质量与成本平衡

handsfree/gpt-5.6-luna快速、低成本任务

常见问题

401：启动 OpenCode 的终端没有读到 OPENAI_API_KEY。
403：Key 不属于 openai-default 或未开放 GPT-5.6。
404 / 路径错误：确认 baseURL 以 /v1 结尾，并使用 @ai-sdk/openai。
模型不显示：确认模型 ID 已写入该 provider 的 models，并重启 OpenCode。

不要只靠环境变量猜 provider：ANTHROPIC_AUTH_TOKEN 并不会自动把 OpenCode 注册成 HFC；必须有上面的 provider 配置。

配置依据：OpenCode 官方 provider 文档要求自定义 provider 声明 npm SDK、options.baseURL、凭据与模型表；OpenAI Responses 使用 @ai-sdk/openai。查看官方 provider 文档。