USER_GUIDE.md

AI Agent Model Switcher 用户指南

目录

1. 快速开始
2. 安装方法
3. 使用方法
4. 支持的 Agent Tools
5. 支持的模型提供商
6. 常见问题
7. 高级用法

快速开始

# 1. 下载工具
git clone https://github.com/yourusername/model-switcher.git
cd model-switcher

# 2. 运行（交互式模式）
./model-switcher

# 或快速切换
./model-switcher -a claude -p glm -m glm-4 -k YOUR_API_KEY

安装方法

方法一：直接使用（推荐）

# 下载代码
git clone <repository-url>
cd model-switcher

# 运行
./model-switcher --help

方法二：安装为 Python 包

# 安装
pip install -e .

# 使用
model-switcher
# 或
ams

使用方法

交互式模式

运行不加任何参数，进入交互式向导：

./model-switcher

交互式模式会引导您：

1. 选择要配置的 Agent Tool
2. 选择模型提供商
3. 选择具体模型
4. 输入 API Key
5. 确认并应用配置

快速切换模式

使用命令行参数直接切换：

./model-switcher -a <agent> -p <provider> -m <model> -k <api-key>

参数说明：

• -a, --agent: Agent Tool 名称 (claude, kimi)
• -p, --provider: 模型提供商 (glm, qwen, kimi, openai)
• -m, --model: 模型 ID（可选，使用提供商默认模型）
• -k, --api-key: API Key

示例

# 切换 Claude 使用 GLM
./model-switcher -a claude -p glm -m glm-4 -k YOUR_GLM_API_KEY

# 切换 Claude 使用 Qwen
./model-switcher -a claude -p qwen -m qwen-max -k YOUR_QWEN_API_KEY

# 切换 Claude 使用 Kimi
./model-switcher -a claude -p kimi -m kimi-k2 -k YOUR_KIMI_API_KEY

# 使用默认模型
./model-switcher -a claude -p glm -k YOUR_API_KEY

查看配置

# 列出所有配置和可用选项
./model-switcher --list

支持的 Agent Tools

Claude Code

• 描述: Anthropic Claude Code CLI 工具
• 官网: https://claude.ai/code
• 配置文件:
  • Windows: %USERPROFILE%\.claude\settings.json
  • Linux/macOS: ~/.claude/settings.json

Kimi CLI

• 描述: Moonshot Kimi CLI 工具
• 官网: https://www.moonshot.cn/
• 配置文件:
  • Windows: %USERPROFILE%\.kimi\config.json
  • Linux/macOS: ~/.kimi/config.json

支持的模型提供商

GLM (智谱 AI)

• 官网: https://open.bigmodel.cn/
• API 地址: https://open.bigmodel.cn/api/paas/v4/
• 可用模型:
  • glm-4: 旗舰大模型
  • glm-4-plus: 增强版旗舰模型
  • glm-4-flash: 轻量级高速模型
  • glm-4v: 视觉理解模型
  • glm-4.5: 4.5 版本
  • glm-4.7: 4.7 版本

Qwen (通义千问)

• 官网: https://dashscope.aliyun.com/
• API 地址: https://dashscope.aliyuncs.com/compatible-mode/v1
• 可用模型:
  • qwen-max: 最强模型
  • qwen-plus: 增强版
  • qwen-turbo: 极速版
  • qwen-coder-plus: 编程增强版
  • qwen-coder-turbo: 编程极速版
  • qwen2.5-coder-32b-instruct: 2.5编程版32B

Kimi (Moonshot)

• 官网: https://www.moonshot.cn/
• API 地址: https://api.moonshot.cn/v1
• 可用模型:
  • kimi-k2: 旗舰大模型
  • kimi2.5: 2.5 版本
  • kimi2.5-think: 推理版
  • kimi2: 2 版本

OpenAI

• 官网: https://platform.openai.com/
• API 地址: https://api.openai.com/v1
• 可用模型:
  • gpt-4o: 旗舰多模态模型
  • gpt-4o-mini: 轻量级多模态模型
  • o1: 推理模型
  • o3-mini: 轻量推理模型
  • gpt-4-turbo: GPT-4 Turbo

常见问题

Q: 如何获取 API Key？

GLM: 访问 https://open.bigmodel.cn/ 注册并创建 API Key

Qwen: 访问 https://dashscope.aliyun.com/ 注册并创建 API Key

Kimi: 访问 https://www.moonshot.cn/ 注册并创建 API Key

OpenAI: 访问 https://platform.openai.com/ 注册并创建 API Key

Q: 切换后配置没有生效？

A: 请尝试以下步骤：

1. 确认配置文件路径正确
2. 重启终端或命令行窗口
3. 重启 Claude Code 或 Kimi CLI
4. 检查 API Key 是否正确

Q: 配置文件在哪里？

A: 根据您的平台和工具不同：

Claude Code:

• Windows: C:\Users\<用户名>\.claude\settings.json
• Linux/macOS: ~/.claude/settings.json

Kimi CLI:

• Windows: C:\Users\<用户名>\.kimi\config.json
• Linux/macOS: ~/.kimi/config.json

Q: 如何恢复到原来的配置？

A: 每次修改前工具会自动创建备份文件（.backup 后缀）。您可以：

1. 手动复制备份文件覆盖当前配置
2. 重新运行工具切换回原来的提供商

Q: 支持哪些操作系统？

A: 支持 Windows、Linux、macOS 三大主流平台。

高级用法

自定义配置文件路径

目前工具使用默认路径，如需自定义路径，请手动编辑配置文件。

批量切换

您可以编写脚本批量切换多个 Agent：

#!/bin/bash
API_KEY="your-api-key"

# 切换 Claude 使用 GLM
./model-switcher -a claude -p glm -m glm-4 -k "$API_KEY"

# 切换 Kimi CLI 使用 GLM
./model-switcher -a kimi -p glm -m glm-4 -k "$API_KEY"

集成到 CI/CD

在自动化流程中使用快速切换模式：

# .github/workflows/switch-model.yml
- name: Switch to GLM
  run: |
    ./model-switcher -a claude -p glm -m glm-4 -k ${{ secrets.GLM_API_KEY }}

故障排除

问题：提示 "未检测到已安装的 Agent Tools"

解决方案:

1. 确保 Agent Tool 已正确安装
2. 确保运行过至少一次 Agent Tool 以生成配置文件
3. 检查配置文件路径是否正确

问题：提示 "配置文件读取失败"

解决方案:

1. 检查文件权限
2. 检查 JSON 格式是否正确
3. 尝试手动编辑配置文件

问题：API 调用失败

解决方案:

1. 检查 API Key 是否正确
2. 检查网络连接
3. 检查 API Key 是否有足够的配额
4. 查看 Agent Tool 的官方文档

获取帮助

• 查看帮助: ./model-switcher --help
• 查看版本: ./model-switcher --version
• 提交 Issue: https://github.com/yourusername/model-switcher/issues

许可证

MIT License