一、概述
CLI 命令入口统一为 thcli <命令> [子命令] [–参数]，任意层级均可加 -h 或 –help 查看完整参数说明。
注意：说明：
注意：安装完成后提供两个等价命令：thcli 与短别名 th。下文示例统一使用 thcli；将其替换为 th 效果完全一致，例如 th models list = thcli models list。
二、准备工作
在使用 TokenHub CLI 之前，你需要：
·注册腾讯云 并完成 实名认证。
·登录 腾讯云大模型服务平台 TokenHub 控制台，按照界面提示开通大模型服务平台 TokenHub 。
·本机已安装 Node.js ≥ 18（用于运行 CLI）。
三、安装与登录
手动安装AI Agent安装
1. 在终端输入安装指令。
npm i -g tencent-tokenhub-cli# （可选）一键将 TokenHub 能力作为 Skill 注入本地 Agent，使 Agent 可通过自然语言调用 TokenHub 的只读能力thcli +connect
2. 登录鉴权。
·方式一：OAuth 快捷登录（推荐）——登录腾讯云账号后，自动生成并在本地保存一个数据面 API Key（名为 thcli-key），用于后续推理调用，无需手动配置。
thcli auth login
·方式二：无浏览器环境（远程开发机、CI、容器）使用 –browser no，按提示将网页上的凭据串粘贴回终端。
thcli auth login –browser no
·方式三：手动填入密钥——已有 腾讯云永久密钥（SecretId/SecretKey）时可直接填入。
thcli auth set –secret-id <SecretId> –secret-key <SecretKey>
3. 验证登录状态。
thcli auth status
复制以下 Prompt 发给 Agent，自动完成安装与登录：
请阅读以下文档，帮我安装 TokenHub CLI：https://tokenhub-cli.tencentmaas.com/tokenhub-cli-skills/install.md
注意：说明：
注意：为避免 AI Agent 在自动执行任务时因理解偏差而误触发删除、创建、变更等操作，对生产环境造成不可预期的影响，当前版本注入 Agent 的 Skill 仅封装只读命令：
四、1. 认证与身份
| 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| 登录与凭证 | 登录腾讯云账号（OAuth，登录后自动生成并保存一个名为 thcli-key 的数据面 API Key，用于推理调用）或手动填入密钥。 | thcli auth login / set | “查一下我现在登录的账号、站点和凭证有效期” |
| | 查看当前凭证来源、有效期。 | thcli auth status | |
| | 登出。 | thcli auth logout | |
| API Key 管理 | 查看 Key 列表、详情、明文。 | thcli key list / get / reveal | “列出我名下所有的 API Key，包括名称和访问范围”。“查一下这把 Key 的额度用得怎么样了” |
| | 创建 Key（可限定可访问的模型、服务与 Token 额度）；修改备注与 IP 白名单。 | thcli key create / update / quota | |
| | 启用、停用、删除；调整额度限制。 | thcli key enable / disable / delete | |
| 多账号、多站点 | 查看 / 创建 / 切换默认 Profile（同站多账号身份隔离）。 | thcli profile list / current / use / create | “看看我当前用的是哪个 Profile、哪个站点” |
| | 查看 / 切换默认站点（cn 中国站 / intl 国际站）。 | thcli site list / current / use | |
五、2. 模型发现
| 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| 模型列表与详情 | 查看平台全量模型（含语言、视觉、多模态、语音、向量等各类型）；可按类型、厂商、标签筛选；查看单个模型的上下文窗口、最大输出、限流值等规格与计费信息。 | thcli models listthcli models searchthcli models get | “有哪些模型，能力和厂商分别是什么”“deepseek-v3 的上下文窗口和输出上限是多少” |
| 比价 | 横向比较多个模型的输入、输出、缓存单价。 | thcli models comparethcli models pricing | “帮我对比一下 deepseek-v3 和 glm-5v-turbo 的价格” |
六、语言模型相关
| 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| 对话 | 对语言模型发起推理调用，支持多轮对话、图片/文档多模态输入、联网搜索、深度思考、流式输出。 | thcli +chat –model <模型 Id> "你好"说明：+chat 按 token 计费，优先使用模型的免费额度，免费额度耗尽时，需通过endpoint postpaid on开通按量付费才可继续调用。 | “用 deepseek-v4-flash 这个模型帮我看看这张截图里的报错并解释”“证明一下勾股定理，帮我一步步推导” |
七、视觉模型（图像、视频、3D生成）、语音模型相关
| 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| 图片生成 | 文生图、图生图、多轮会话编辑、组图、透明底、图层拆分。覆盖混元 Hy、WAND-Vega、Vidu、Kling 等系列模型。 | thcli +gen <接口 ID（接口路径）> –model <模型 Id> –prompt "<图片描述>" [–images <参考图>]示例：文生图：thcli +gen wand/hunyuan-image/v35-generation –model hy-image-v3.5-preview –messages '[{"role":"user","content":[{"type":"text","text":"一只橘猫趴在窗台上"}]}]' –size 1024×1024 –output ./out图生图：thcli +gen wand/hunyuan-image/v35-generation –model hy-image-v3.5-preview –messages '[{"role":"user","content":[{"type":"text","text":"改成水彩风格"},{"type":"image_url","image_url":{"url":"./ref.png"}}]}]' –output ./out说明：+gen 按 token 计费，优先使用模型的免费额度，若模型不含免费额度，或免费额度耗尽时，需通过endpoint postpaid on开通按量付费才可继续调用。 | “用 hy-image-v3.5-preview 画一张赛博朋克风格的城市夜景，保存到 ./out”“用 hy-image-v3 参考这张图，生成一张水彩风格的版本” |
| 视频生成 | 文生视频、图生视频、首尾帧生视频、参考生视频、动作控制。覆盖混元 Hy、Kling、Vidu、PixVerse、MiniMax、WAND-Vega 等系列模型。 | thcli +gen <接口 ID（接口路径）> –model <模型 Id> –prompt "<视频描述>" [–image <首帧图>] [–no-wait]示例：文生视频：thcli +gen wand/hunyuan-video/generation –model hy-video-v1.5 –prompt "海边日落" –aspect-ratio 16:9 –output ./out图生视频：thcli +gen wand/hunyuan-video/generation –model hy-video-v1.5 –image ./cat.jpg –prompt "猫咪转头" –no-wait说明：+gen 按 token 计费，优先使用模型的免费额度，若模型不含免费额度，或免费额度耗尽时，需通过endpoint postpaid on开通按量付费才可继续调用。 | “用 hy-video-v1.5 生成一段 16:9 的海边日落视频”“用 hy-video-v1.5 以这张图做首帧，生成一段猫咪转头的视频” |
| 3D 与世界模型 | 文生 3D、图生 3D 模型。生成 3D 世界 360° 全景图、3D 世界场景。 | thcli +gen <接口 ID（接口路径）> –model <模型 Id> –prompt "<场景或物体描述>" [–<参考图字段> <参考图>]示例：360° 全景图：thcli +gen wand/hunyuan-image/world2-panorama –model hy-world2-panorama –prompt "清晨的江南古镇" –output ./out说明：+gen 按 token 计费，优先使用模型的免费额度，若模型不含免费额度，或免费额度耗尽时，需通过endpoint postpaid on开通按量付费才可继续调用。 | “用 hy-world2-panorama 生成一张清晨江南古镇的 360° 全景图” |
| 语音生成与识别 | 语音合成（TTS）、音色复刻、音色设计。语音识别（ASR，输出文本与字幕）、AI 配音、音乐生成。 | 语音识别：thcli +gen <接口 ID（接口路径）> –model <模型 Id> –data <本地音频> 或 –input-url <音频 URL>语音合成：thcli +gen <接口 ID（接口路径）> –model <模型 Id> –text "<文本>" –voice-setting '<音色配置>'示例：语音识别：thcli +gen wand/asrproxy/sync_transcribe –model hy-asr-3.0-preview –data ./speech.wav –output ./out语音合成：thcli +gen wand/minimax-tts/sync_tts –model minimax-speech-2.8-hd –text "你好" –voice-setting '{"voice_id":"male-qn-qingse"}' –output ./out说明：+gen 按 token 计费，优先使用模型的免费额度，若模型不含免费额度，或免费额度耗尽时，需通过endpoint postpaid on开通按量付费才可继续调用。 | “用 hy-asr-3.0-preview 识别这段录音的内容，输出 SRT 字幕”“用 minimax-speech-2.8-hd 把这段文案合成语音，音色 ID 用 xxx” |
| 生成接口与任务管理 | 查看全部生成接口、调用方式（同步 / 异步）及单个接口的完整参数。查询异步任务状态并下载结果；列出本机提交过的任务。 | 查看生成接口参数： thcli +gen apis [接口 ID（接口路径）]查询异步任务：thcli +gen status <接口 ID（接口路径）> <任务 ID> [–wait] [–output <目录>]列出本机生成任务： thcli +gen tasks示例：查看混元图片生成模型接口参数：thcli +gen apis wand/hunyuan-image/v35-generation查询并下载任务结果：thcli +gen status wand/hunyuan-video/generation <任务 ID> –wait –output ./out说明：以上查询类命令不会产生费用。 | “TokenHub 有哪些混元图片生成模型，哪些是同步的”“我刚才提交的 hy-video-v1.5 视频任务好了没，好了就下载到 ./out” |
注意：更多说明：
八、4. 推理服务与部署
| 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| 服务查询 | 查看服务（endpoint）列表与详情，包括运行状态、计费方式、限流阈值、免费额度用量。 | thcli endpoint listthcli endpoint get | “我有哪些服务，分别是什么状态”“这个服务当前的限流是多少” |
| 部署 / 改配 / 删除 | 自定义服务创建（设置计费方式、RPM / TPM 限流）。修改配置；删除。开启/关闭服务的按量付费。 | thcli deploythcli endpoint update / deletethcli endpoint postpaid on / off说明：endpoint postpaid on、deploy 会产生费用、默认二次确认。 | 无注意：部署、修改、删除接入点属于写操作，当前不支持通过自然语言直接触发。 |
九、5. 套餐与额度
| 类型 | 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| 企业版套餐 | 套餐查询 | 查看已持有的企业版 Token Plan 套餐详情、可用模型范围、用量明细。 | thcli plan listthcli plan info / models / detail | “我有哪些企业版套餐，分别还剩多少额度”“这个套餐下能用哪些模型”“我要看这个套餐用量明细” |
| | 购买 / 续费 / 升配 | 购买企业版套餐（专业版/轻享版）、续费、升配规格额度。 | thcli plan buythcli plan renew / upgrade说明：plan buy/renew/upgrade 会产生费用、默认二次确认。 | 无注意：购买、续费、升配属于产生费用的写操作，当前不支持通过自然语言直接触发。 |
| | 套餐专属 Key | 查看、创建、修改、重置、删除企业套餐的专属 API Key（与平台 Key 相互独立，额度单独计算）。 | thcli plan key list / getthcli plan key create / update / rotate / delete | “这个套餐下有哪些专属 Key” |
| 个人版套餐 | 套餐查询 | 查看已持有的个人版 Token Plan 套餐详情、可用模型范围、用量明细。 | thcli plan personal listthcli plan personal info / models / usage –series <common / hy> | “我有哪些个人版套餐，分别还剩多少额度”“这个套餐下能用哪些模型”“我要看这个套餐用量明细” |
| | 个人版共享 Key | 查看 / 生成 / 显示明文 / 重置 / 删除个人版共享 Key（通用 / Hy 共用一把，额度单独计算） | thcli plan personal key show / create / reveal / rotate / delete | 「我的个人版共享 Key 是什么状态」「生成一把个人版共享 Key」 |
十、6. 观测与诊断
| 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| 用量统计 | 按模型、接入点、API Key 维度查看 Token 消耗排行与趋势，支持按小时、天等粒度聚合；导出用量明细为 CSV 用于对账。 | thcli usage rank / trend / export | “今天用了多少 Token，哪个模型消耗最多”“看一下 xx 服务近 7 日的 tpm 趋势”“导出最近 7 天按 Key 的用量到 CSV” |
| 模型监控 | 按语言、视觉、语音模型类型查看监控数据。支持按模型、接入点、API Key 维度查看 RPM、TTFT、TPOT、错误率等指标，支持按小时、天等粒度聚合。 | thcli monitor text / vision / audiothcli monitor text –model <name> | “查一下 hy3 模型近七日有无调用失败记录” |
| 诊断与排障 | 全链路体检（凭证、地域、权限）Key、服务、模型、套餐诊断，查看状态及是否可用。错误码翻译。 | thcli doctor allthcli doctor key / endpoint / model / planthcli doctor error | “为什么调用失败，检查一下什么环节出了问题”“这个错误码什么意思”“用 hy-image-v3.5-preview 生图前，帮我检查一下能不能调通”“Kling 视频生成返回 1201 是什么意思，怎么修” |
十一、7. Agent 集成与接入
| 能力 | 能力说明 | 核心命令 | Agent 自然语言描述（示例） |
| Skill 一键注入 | 将 TokenHub 的只读能力作为 Skill 注入本地 Agent，使 Agent 可用自然语言理解并调用 TokenHub。 | thcli +connectthcli +connect uninstallthcli +connect status | “请阅读 <安装文档链接> ，帮我把 TokenHub CLI 接入我的 Claude Code”“看看我本机已经装了哪些 TokenHub 相关的 Skill” |
十二、8. Skill 专属能力
| 能力 | 能力说明 | Agent 自然语言描述（示例） |
| 文档检索 | 基于 TokenHub 产品文档内容，快速理解并帮助用户检索所需信息。 | “hy3 的调用参数和步骤有哪些？”“我的费用账单要去哪里看？给个链接”“给我解释一下什么是推理服务”“根据产品文档要求，帮我把 hy3 模型接入 WorkBuddy” |
十三、查看命令的完整参数
每个命令或子命令实际支持的完整参数请通过 -h 或 –help 查看，任意层级均适用，例如 thcli –help、thcli plan –help、thcli plan key create –help。
下表列出各核心命令组对应的完整参数查看方式：
| 命令组 | 说明 | 查看完整参数 |
| auth | 登录、登出、手填密钥、查看状态 | thcli auth –help |
| key | API 密钥列表、详情、增删改、启停、明文 | thcli key –help |
| models | 模型列表、详情、比价、搜索推荐 | thcli models –help |
| endpoint / deploy | 接入点列表、详情、改配、删除；创建接入点 | thcli endpoint –helpthcli deploy –help |
| +chat | 推理调用 | thcli +chat –help |
| +gen | 生成图片、视频、3D 与语音；查询异步任务 | thcli +gen –help |
| chat-config | 本地维护 +chat 对话与 +gen 生成时用的 API Key | thcli chat-config –help |
| plan | 企业套餐列表、详情、购买、续费、升配、用量明细 | thcli plan –help |
| plan personal | 个人套餐列表、详情、购买、续费、升配、用量明细 | thcli plan personal –help |
| usage | 用量排行、导出 CSV | thcli usage –help |
| monitor | RPM、TTFT、TPOT、错误率等 | thcli monitor –help |
| doctor | 全链路体检、输出修复动作 | thcli doctor –help |
| profile | 多账号 Profile 管理 | thcli profile –help |
| site | 站点（cn / intl）切换 | thcli site –help |
| lang | 界面语言（zh / en）切换 | thcli lang –help |
| +connect | Agent Skills 一键注入 | thcli +connect –help |
十四、参考信息
关于站点与地域的资源隔离规则、本地文件结构（~/.thcli/）、调用日志等进阶说明，请参见 开源仓库。