☰ 章节目录
3. 十分钟上手
从零安装到完成第一次模型切换，十分钟搞定。
3.1 安装并启动
桌面版（推荐）： 从 GitHub Release 下载 dmg，拖入「应用程序」并打开——控制台窗口会自动出现。首次打开如被 macOS 拦截，按第 2 章的步骤放行一次。
CLI：
npm install -g modelswap
modelswap web # 打开 http://localhost:3780
更多安装方式（源码构建等）见第 2 章。
3.2 存入一个密钥
- 手动：密钥管理 → 添加——起个名字（如
anthropic-api）、粘贴 Key、保存 - 自动：密钥管理 → 自动创建——浏览器扩展会替你填官方控制台的表单并把 Key 回填到密钥库（第 5 章）
- 命令行：
modelswap vault set anthropic-api（交互式；--stdin可避免密钥进入 shell 历史）
3.3 注册并连通一个平台
- 模型管控页 → 点击平台卡片（如 Anthropic）
- 密钥选择刚才存入的密钥库条目
- 点击连接——ModelSwap 验证端点并拉取该平台的模型列表
3.4 把 Agent 切换过去
- 快速启动页 → 顶部选择 Agent（如 Claude Code）
- 打开该 Provider 的启用开关
- 点击模型 chip 即完成。配置文件（
config.toml、auth.json等）由 ModelSwap 自动写对
命令行等价操作：
modelswap provider use <provider> --agent <agent-id> --model <model-id>
Agent / 模型 ID 可从 modelswap provider current --json 获取（完整流程见第 9 章）。
3.5 验证
modelswap provider auth --json # 各平台认证状态
modelswap provider current # 各 Agent 当前解析到哪个模型
然后找 Agent 问个小问题。如果它还在用旧模型，说明正在运行的 CLI 会话缓存了旧配置——重启该 Agent（见 常见问题）。
到这里你已经跑通了核心流程。接下来可以按需深入：