Handsfree Club· 接入文档
接入文档/OpenClaw
Custom provider · OpenAI Responses

OpenClaw 接入

OpenClaw 不需要迁移到 Hermes 才能使用。按当前官方配置，在 models.providers 注册 Handsfree provider，并用 provider/model 形式选择 GPT-5.6。

协议openai-responses
Base URLhttps://api.handsfreeclub.com/v1
主模型handsfree/gpt-5.6-terra
30 秒摘要

把下面 JSON5 合并进 ~/.openclaw/openclaw.json，API Key 继续从 OPENAI_API_KEY 环境变量读取，然后运行 openclaw models set handsfree/gpt-5.6-terra。

1

准备 Key，不把密钥写进 JSON

如果已经跑过本站一键脚本，新终端会拥有 OPENAI_API_KEY。否则请按操作系统安全设置该环境变量，避免把真实 Key 粘贴进项目、聊天记录或公开配置。

检查变量是否存在（不回显 Key）
test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY 已加载" || echo "尚未加载"
2

注册 Handsfree provider

备份后编辑 ~/.openclaw/openclaw.json，保留现有 channel、skills、gateway 与 agent 设置，只合并以下字段。

~/.openclaw/openclaw.json（JSON5）
{
  agents: {
    defaults: {
      model: { primary: "handsfree/gpt-5.6-terra" },
      models: {
        "handsfree/gpt-5.6-sol": { alias: "GPT-5.6 Sol" },
        "handsfree/gpt-5.6-terra": { alias: "GPT-5.6 Terra" },
        "handsfree/gpt-5.6-luna": { alias: "GPT-5.6 Luna" }
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      handsfree: {
        baseUrl: "https://api.handsfreeclub.com/v1",
        apiKey: "${OPENAI_API_KEY}",
        api: "openai-responses",
        models: [
          { id: "gpt-5.6-sol", name: "GPT-5.6 Sol" },
          { id: "gpt-5.6-terra", name: "GPT-5.6 Terra" },
          { id: "gpt-5.6-luna", name: "GPT-5.6 Luna" }
        ]
      }
    }
  }
}
为什么必须同时写两处：models.providers 注册真正的运行模型；agents.defaults.models 只负责可见性、别名和 allowlist，不能单独注册 provider。
3

验证配置与模型

terminal
openclaw models list
openclaw models set handsfree/gpt-5.6-terra
openclaw doctor
handsfree/gpt-5.6-sol高难度推理与复杂自动化
handsfree/gpt-5.6-terra默认推荐，日常 agent 工作
handsfree/gpt-5.6-luna快速、低成本任务
provider 前缀只存在于 OpenClaw 本地：OpenClaw 选择 handsfree/gpt-5.6-terra，实际请求到 HFC 的模型仍是 gpt-5.6-terra，账单和日志按实际 GPT 展示。
4

安全边界与排错

OpenClaw 权限很高：不要把 Gateway 管理界面直接暴露到公网；新设备启用配对审批；第三方 skill 安装前先做安全审查。模型 API Key 只授予所需分组。
配置依据：OpenClaw 官方文档要求自定义代理同时注册 models.providers，模型引用使用 provider/model，支持 openai-responses，并建议凭据使用环境变量/SecretRef。模型 provider 文档 · 配置字段文档。