OpenClaw 的腾讯云提供方默认选择 hy4-preview;要明确使用正式版,应把主模型设为 tencent-tokenhub/hy4 或 tencent-tokenplan/hy4,并确认所选端点的 API Key 有 Hy4 权限。
适合的任务:在 OpenClaw 中通过腾讯云 TokenHub 或 TokenPlan 调用 Hy4,处理文本、图像、长上下文、代码和 Agent 工作流。
不适合的任务:需要模型直接输出图像,或需要音频、视频输入的任务;文档只列出图像输入和文本输出。
适用的模型版本:hy4 正式版。文档未给出 OpenClaw 或提供方插件的最低版本要求。
适用的客户端、Agent 或 API:OpenClaw;腾讯云官方提供方插件 @openclaw/tencent-provider;OpenAI 兼容的 openai-completions API。
推荐的推理档位和参数:reasoning_effort 可用 none 或 high;其他思考档位会映射为 high,默认也是 high。
两种端点的提供方 ID、密钥变量和 API 地址如下。设置认证后,模型 ref 仍需明确指向 hy4:
| 端点 | 提供方 ID | 模型 ref | API Key 环境变量 | 默认 API 地址 |
|---|---|---|---|---|
| TokenHub | tencent-tokenhub | tencent-tokenhub/hy4 | TOKENHUB_API_KEY | https://tokenhub.tencentmaas.com/v1 |
| TokenPlan | tencent-tokenplan | tencent-tokenplan/hy4 | TOKENPLAN_API_KEY | https://api.lkeap.cloud.tencent.com/plan/v3 |
交互式认证:
openclaw onboard --auth-choice tokenhub-api-key
# 或
openclaw onboard --auth-choice tokenplan-api-key非交互式认证:
openclaw onboard --non-interactive \
--mode local \
--auth-choice tokenhub-api-key \
--tokenhub-api-key "$TOKENHUB_API_KEY" \
--skip-health \
--accept-risk
openclaw onboard --non-interactive \
--mode local \
--auth-choice tokenplan-api-key \
--tokenplan-api-key "$TOKENPLAN_API_KEY" \
--skip-health \
--accept-risk非交互模式必须同时传 --accept-risk。应在运行 Gateway 的主机上完成认证;--mode remote 只设置本地客户端连接,不会替服务器配置提供方凭据。
在 OpenClaw 主模型配置中,将 agents.defaults.model.primary 设为所用端点的模型 ref。一次只选择一个:
{
"agents": {
"defaults": {
"model": {
"primary": "tencent-tokenhub/hy4"
}
}
}
}若使用 TokenPlan,将值替换为 tencent-tokenplan/hy4。hy4-preview 是新配置的默认模型,不能仅凭已完成提供方认证就假定当前主模型已经切换到 hy4。
核对端点可见的模型:
openclaw models list --provider tencent-tokenhub
openclaw models list --provider tencent-tokenplan| 项目 | Hy4 正式版 |
|---|---|
| 输入 | 文本、图像 |
| 支持的图像格式 | JPEG、PNG、WebP、GIF |
| 输出 | 文本 |
| 上下文窗口 | 1,024,000 tokens |
| 最大输入 | 960,000 tokens |
| 最大输出 | 64,000 tokens |
| 推理参数 | reasoning_effort: none 或 high;其他档位映射到 high |
受限范围的 API Key 必须允许所选端点上的 hy4 模型。文档建议迁移到 Hy4 前确认模型访问权限,并留意 Hy4 与旧模型的定价差异。
在 TokenHub 或 TokenPlan 创建 API Key;受限 Key 需包含所选端点的 hy4 权限。
按上文选择对应端点并配置认证。
将 agents.defaults.model.primary 设置为对应的 .../hy4 模型 ref。
用 openclaw models list --provider <提供方 ID> 确认模型目录,再发起请求验证实际调用。
若 Gateway 由 launchd、systemd 或 Docker 托管,将 API Key 放在 ~/.openclaw/.env 或通过 env.shellEnv 提供给该进程。只在交互式 shell 中导出的变量对托管进程不可见。
文档列出的正式版模型 ref 为 tencent-tokenhub/hy4 与 tencent-tokenplan/hy4;两个端点的新配置默认 ref 都是 .../hy4-preview。
官方插件包名为 @openclaw/tencent-provider;两个端点均使用 OpenAI 兼容 API。
TokenHub 的全球地址覆盖值为 https://tokenhub-intl.tencentmaas.com/v1;TokenHub 也支持按账户或区域覆盖地址。
内置目录给 Hy4 标注 1,024,000 上下文、64,000 最大输出、支持文本和图像;说明另给出 960,000 tokens 的输入上限。
页面未公布 OpenClaw 或插件的最低版本号,也未给出插件安装命令。
openclaw doctor --fix 不会把旧 hy3-preview 主模型自动迁移到 Hy4。启用 TokenHub 模型白名单时,旧 hy3-preview 主模型会迁移为 hy3;显式配置的 hy3 和 hy4-preview 保持不变。
文档建议把迁移到 Hy4 作为显式选择,因为模型定价不同,且账号对具体端点的模型权限可能不同。
本文中的主模型字段示例用于将文档列出的精确模型 ref 设为默认模型;提供方页面未列出独立的 Hy4 安装或版本锁定命令。
按原文配置一个端点的 API Key,将主模型设为该端点的 hy4 模型 ref,确认 Gateway 进程可读取密钥,再调用并验证响应。TokenHub 与 TokenPlan 的模型 ref 和 API Key 不要交叉使用。
Hy4