MT Switch CLI 使用文档

适用场景

• 希望 Claude Code、Codex、Gemini CLI 统一使用 Matpool Token。
• 希望一键接入 Matpool 支持的全部模型。
• 不想手动维护 ~/.claude/settings.json、~/.codex/auth.json、~/.codex/config.toml、~/.gemini/.env 等配置文件。
• 需要在 Matpool 可用模型之间快速切换，例如切换 Claude Code 的默认、Sonnet、Opus、Haiku 模型槽位。

支持工具

工具	接管配置	说明
Claude Code	~/.claude/settings.json	支持默认模型、Sonnet、Opus、Haiku、custom 等槽位配置。
Codex	~/.codex/auth.json、~/.codex/config.toml	支持默认模型配置。
Gemini CLI	~/.gemini/.env	支持默认模型配置。

安装

环境要求

• Node.js 18 或更高版本。
• npm 可用。
• 已安装至少一个需要接管的 CLI 工具，例如 Claude Code、Codex 或 Gemini CLI。

常见工具安装命令：

bash
复制代码
npm i -g @anthropic-ai/claude-code
npm i -g @openai/codex
npm i -g @google/gemini-cli

安装 MT Switch CLI

bash
复制代码
npm i -g @mtswitch/switch

安装后会提供 matpool 命令。可用以下命令确认：

bash
复制代码
matpool --version
matpool help

快速开始

推荐使用 setup 完成首次初始化：

bash
复制代码
matpool setup

setup 会按提示完成以下操作：

1. 保存 Matpool Token 到系统密钥链。
2. 初始化本地配置和内置 Matpool 供应商。
3. 安装并启动后台 daemon。
4. 检查本地代理健康状态。
5. 为支持的本地 CLI 工具启用接管。

如果需要非交互式执行，可直接传入 Token：

bash
复制代码
matpool setup --token <your_matpool_token>

也可以指定接管范围：

bash
复制代码
matpool setup --token <your_matpool_token> --apps claude
matpool setup --token <your_matpool_token> --apps claude,codex,gemini

分步配置

如果不使用 setup，可以按以下步骤手动执行。

1. 保存 Token

bash
复制代码
matpool login --token <your_matpool_token>

也可以不带参数，按提示输入：

bash
复制代码
matpool login

移除 Token：

bash
复制代码
matpool logout

2. 安装并启动 daemon

bash
复制代码
matpool daemon install
matpool daemon start
matpool daemon status

daemon status 应显示本地代理正在运行。接管启用期间，需要保持 daemon 运行。

3. 初始化内置供应商

通常 setup 或首次运行会自动初始化。如果遇到内置 Matpool 供应商缺失，可手动执行：

bash
复制代码
matpool provider seed

4. 启用工具接管

接管全部支持工具：

bash
复制代码
matpool takeover all

只接管 Claude Code：

bash
复制代码
matpool takeover claude

只接管 Codex：

bash
复制代码
matpool takeover codex

只接管 Gemini CLI：

bash
复制代码
matpool takeover gemini

取消全部接管：

bash
复制代码
matpool takeover all --disable

取消某个工具接管：

bash
复制代码
matpool takeover claude --disable
matpool takeover codex --disable
matpool takeover gemini --disable

Claude Code 模型配置

执行 Claude 接管后，CLI 会展示 Claude Code /model 菜单对应的 Matpool 模型 ID：

text
复制代码
Current Claude model configuration:
  Claude default   GLM-5.2
  Claude Sonnet    MiMo-V2.5
  Claude Opus      Claude-Opus-4.7
  Claude Haiku     GPT-5.4-Nano
  Claude custom    GPT-5.5

Use current Claude model configuration? [Y/n]:

直接回车会保留当前配置。输入 n 后可依次编辑：

• Claude default
• Claude Sonnet
• Claude Opus
• Claude Haiku
• Claude custom

每项输入 Matpool 模型 ID 后立即保存；留空回车保留当前值；输入 ? 可查看可用模型。

后续可用以下命令查看当前槽位：

bash
复制代码
matpool models claude

查看可用 Claude 模型：

bash
复制代码
matpool models claude list

修改指定槽位：

bash
复制代码
matpool models claude set --sonnet <matpool_model_id> --custom <matpool_model_id>
matpool models claude set --default <matpool_model_id> --opus <matpool_model_id> --haiku <matpool_model_id>

如需使用 Fable 模型，可配置到 Claude custom，例如：

bash
复制代码
matpool models claude set --custom Claude-Fable-5

修改后，如果 Claude Code 已经打开，请重启或重新加载 Claude Code，再执行 /model 查看菜单。

模型同步

列出 Matpool 可用模型：

bash
复制代码
matpool models list

同步全部工具模型：

bash
复制代码
matpool models sync all

只同步 Claude：

bash
复制代码
matpool models sync claude

如果 matpool models claude list 提示模型目录为空，先执行：

bash
复制代码
matpool models sync claude

状态检查

查看本地状态：

bash
复制代码
matpool status

该命令会展示版本、配置目录、数据库可读性、Token 是否已配置、本地代理状态，以及各工具当前供应商和接管状态。

进行诊断：

bash
复制代码
matpool doctor

该命令会检查关键配置文件和 daemon 状态，包括：

• ~/.claude/settings.json
• ~/.codex/auth.json
• ~/.codex/config.toml
• ~/.gemini/.env
• 本地代理运行状态

常用命令

命令	用途
matpool setup	交互式初始化 Token、daemon 和接管。
matpool setup --token <token>	非交互式初始化并保存 Token。
matpool setup --apps claude,codex	只初始化并接管指定工具。
matpool login --token <token>	保存 Matpool Token 到系统密钥链。
matpool logout	从系统密钥链移除 Matpool Token。
matpool status	查看版本、配置目录、Token、代理和各工具接管状态。
matpool doctor	检查关键配置文件和 daemon 状态。
matpool daemon install	安装用户级后台 daemon。
matpool daemon start	启动后台 daemon。
matpool daemon stop	停止后台 daemon。
matpool daemon uninstall	卸载后台 daemon。
matpool daemon run	在前台运行本地代理 daemon。
matpool daemon status	检查本地代理健康状态。
matpool takeover all	接管全部支持的工具。
matpool takeover claude	只接管 Claude Code。
matpool takeover all --disable	取消全部接管。
matpool models list	拉取并列出 Matpool 可用模型。
matpool models sync all	同步 Matpool 模型到本地供应商配置。
matpool models claude	查看 Claude Code 模型槽位。
matpool models claude list	查看已同步的 Claude 模型目录。
matpool models claude set ...	修改 Claude Code 模型槽位。
matpool provider list all	查看本地已配置供应商。
matpool provider seed	初始化或修复内置 Matpool/官方供应商。
matpool provider switch claude default	将 Claude Code 恢复到原始配置。
matpool update	更新 npm CLI 包到最新版。

数据与安全

• 配置目录：~/.matpool-switch/
• 数据库：~/.matpool-switch/matpool-switch.db
• 设置文件：~/.matpool-switch/settings.json
• Token 存储：系统 OS Keychain / Credential Manager / Secret Service
• Keychain 服务名：Matpool Switch
• Keychain 账号：matpool-token

MT Switch CLI 会把 Token 保存到系统密钥链。被接管工具的配置文件只写入路由、模型等必要配置，不直接保存 Matpool Token。

故障排查

接管失败并提示本地代理未运行

先启动 daemon：

bash
复制代码
matpool daemon start
matpool daemon status

确认状态正常后再次执行接管：

bash
复制代码
matpool takeover all

工具无法连接 Matpool

检查 Token、代理和接管状态：

bash
复制代码
matpool status
matpool doctor

如果 Token 缺失，重新登录：

bash
复制代码
matpool login --token <your_matpool_token>

如果 daemon 未运行，启动 daemon：

bash
复制代码
matpool daemon start

Claude Code 的 /model 菜单未更新

先查看当前模型槽位：

bash
复制代码
matpool models claude

如模型列表为空，先同步：

bash
复制代码
matpool models sync claude
matpool models claude list

修改后重启或重新加载 Claude Code。

想恢复原始配置

取消接管：

bash
复制代码
matpool takeover all --disable

如只恢复 Claude Code，也可以切回默认供应商：

bash
复制代码
matpool provider switch claude default

内置 Matpool 供应商缺失

执行：

bash
复制代码
matpool provider seed

然后重新接管：

bash
复制代码
matpool takeover all

需要更新 CLI

bash
复制代码
matpool update