集成

@hypershub/cli

使用 hy 命令一键导入 Codex、Claude Code、OpenCode 配置，自动查询可用模型，支持全局配置、切换默认模型，并提供本地检查与联网测试能力。

安装

需要 Node.js 18 或更高版本。推荐安装最新版本，以获得 hy config 等全局配置能力。

npm install -g @hypershub/cli@latest
hy --help

快速开始

选择要配置的工具

支持单独初始化一个工具，也可以使用 all 一次配置全部支持项。

Terminal

hy init codex
hy init claude-code
hy init opencode
hy init all

输入平台地址与 API Key

CLI 会逐步提示输入 Base URL、API Key 和默认模型。推荐输入平台根地址；如输入带 /v1 的地址，CLI 也会自动兼容。初始化成功后，CLI 会把确认过的 URL、API Key 和默认模型写入全局配置，后续 hy models、hy init 等命令可自动复用。

交互示例

hy init claude-code
HypersHub Base URL (https://apiclaw.cc):
API Key: hy-...
Default model (claude-sonnet-4-6): claude-deepseek-v4-pro
✓ Global config updated for future hy commands
Run connectivity test now (y/N): Y

URL 自动兼容

不同工具对 URL 的要求不同：Codex / OpenCode 需要 OpenAI-compatible 的 /v1 地址，而 Claude Code 的 ANTHROPIC_BASE_URL 通常不带 /v1。hy 会自动转换，用户只需要输入推荐地址。

URL 规则

推荐输入: https://apiclaw.cc
也可输入: https://apiclaw.cc/v1

自动写入:
Codex / OpenCode: https://apiclaw.cc/v1
Claude Code: https://apiclaw.cc

检查配置并测试

初始化后建议先运行 hy check all --live，确认本地配置、API Key 与默认模型都可用。

Terminal

hy check all --live
hy use gpt-5.5
hy use claude-deepseek-v4-pro claude-code --live
hy test codex
hy test claude-code
hy test opencode

全局配置：hy config

如果你不希望每次运行 hy models 都重新输入 API Key，可以先用 hy config 保存常用参数。hy init 也会在初始化成功后自动写入这份全局配置。

Terminal

hy config set baseUrl https://apiclaw.cc
hy config set apiKey hy-xxx
hy config set defaultModel gpt-5.5
hy config list
hy config get apiKey
hy config path
hy models

配置项	说明
baseUrl	平台根地址，例如 https://apiclaw.cc。也可以输入 https://apiclaw.cc/v1，CLI 会自动规范化。
apiBaseUrl	OpenAI-compatible API 地址，设置后会同步更新 baseUrl。
apiKey	HypersHub API Key。默认输出会脱敏，避免误泄露。
defaultModel	未通过 --model 指定时使用的默认模型。

优先级：命令参数 > 环境变量 > hy config > 交互输入 / 默认值。配置文件位置可通过 hy config path 查看；macOS/Linux 默认是 ~/.hypershub/config.json，Windows 默认是 %APPDATA%\HypersHub\config.json。

日常工作流

hy init 通常只需要执行一次。配置完成后，最常用的是 hy use：它会复用已有 URL / API Key，只切换默认模型。

推荐流程

hy init all
hy config list
hy models
hy check all --live
hy use gpt-5.5
hy use gpt-5.5 codex
hy use claude-deepseek-v4-pro claude-code --live

为什么单独使用 hy use？ 切模型不应该要求用户重新输入 API Key，也不应该重写全部配置。hy use 只更新默认模型，并可通过 --live 先验证模型是否对当前账号可用。

常用命令

命令	说明
hy init <codex\|claude-code\|opencode\|all>	写入对应工具的本地配置，并可立即执行连通性测试；成功后会同步写入 hy 全局配置。
hy config list\|get\|set\|unset\|path	管理全局 Base URL、API Key、默认模型与配置文件路径。
hy models	调用 /v1/models 查询当前 API Key 可用的模型列表；会自动读取 hy config。
hy check [target\|all]	读取本地配置，检查 URL、API Key、默认模型与模型目录是否存在。
hy check [target\|all] --live	额外联网验证 API Key，并确认默认模型在可用模型列表中。
hy use <model> [target\|all]	在已有配置中切换默认模型，无需重新输入 URL / API Key；可加 --live 先验证模型可用性。
hy test <target>	发送一次最小请求到 /v1/responses 或 /v1/messages，验证真实调用链路。
hy doctor	快速检查常见配置文件和当前环境变量。

切换默认模型

完成 hy init 后，日常切换模型不需要重新输入 URL / API Key，直接使用 hy use 即可。

Terminal

hy use gpt-5.5
hy use gpt-5.5 codex
hy use claude-deepseek-v4-pro claude-code
hy use deepseek-v4-pro opencode
hy use gpt-5.5 all --live
hy use gpt-5.5 codex --live --json

目标	更新内容
Codex	~/.codex/config.toml，并确保模型存在于 all-models.json
Claude Code	Shell 配置与 ~/.claude/settings.json，同步 cc-switch 兼容的模型变量
OpenCode	~/.config/opencode/opencode.json 的 model 与 provider.models

建议：使用 --live 时，CLI 会先调用 /v1/models，确认当前 API Key 支持该模型后再写入。切换后请重启对应工具；Claude Code 如有需要可执行 source ~/.zshrc。

非交互使用

在脚本、CI 或批量配置场景中，可以直接通过参数传入 URL、API Key 和模型。URL 推荐统一传平台根地址，CLI 会按工具自动补充或移除 /v1。

Terminal

hy init codex --url https://apiclaw.cc --key hy-xxx --model gpt-5.4 --yes
hy init claude-code --url https://apiclaw.cc --key hy-xxx --model claude-sonnet-4-6 --yes
hy init opencode --url https://apiclaw.cc --key hy-xxx --model gpt-5.4 --yes

安全提示：默认会备份已有配置；使用 --dry-run 可预览写入内容，输出中的 API Key 会自动脱敏。

查询、检查与测试

Terminal

hy config set baseUrl https://apiclaw.cc
hy config set apiKey hy-xxx
hy models
hy models --json
hy check codex
hy check all --live
hy check all --live --json
hy use gpt-5.5
hy use gpt-5.5 codex --live
hy use claude-deepseek-v4-pro claude-code --live
hy test claude-code --model claude-deepseek-v4-pro

如果工具启动后模型显示不符合预期，先用 hy use <model> claude-code 同步默认模型，再运行 hy check claude-code --live。 CLI 会同时检查 Claude Code 的 shell 配置和 ~/.claude/settings.json，兼容 cc-switch 写入的模型覆盖。

写入哪些文件？

集成	文件
Codex	~/.codex/config.toml、~/.codex/model-catalogs/all-models.json
Claude Code	~/.zshrc / ~/.bashrc / fish / PowerShell profile、~/.claude/settings.json
OpenCode	~/.config/opencode/opencode.json
hy 全局配置	macOS/Linux: ~/.hypershub/config.json；Linux XDG: $XDG_CONFIG_HOME/hypershub/config.json；Windows: %APPDATA%\HypersHub\config.json