llm-router

LLM 路由器

概述

使用 SwiftOpenAI-CLI 的 Agent 模式，将 AI 请求路由到不同的 LLM 提供商。此技能会自动配置 CLI 以使用指定的提供商（OpenAI、Grok、Groq、DeepSeek 或 OpenRouter），确保工具已安装且为最新版本，并执行一次性 Agent 任务。

核心工作流

当用户请求使用特定的 LLM 提供商时（例如，“使用 grok 解释量子计算”），请遵循以下工作流：

步骤 1：确保 SwiftOpenAI-CLI 已就绪

检查是否已安装 SwiftOpenAI-CLI，且为最新版本：

scripts/check_install_cli.sh

此脚本将：

• 检查是否已安装 swiftopenai
• 验证版本（最低为 1.4.4）
• 如有必要，进行安装或更新
• 报告当前安装状态

步骤 2：配置提供商

根据用户的请求，确定目标提供商并配置 SwiftOpenAI-CLI：

scripts/configure_provider.sh <provider> [model]

支持的提供商：

• openai - OpenAI（GPT-4、GPT-5 等）
• grok - xAI Grok 模型
• groq - Groq（Llama、Mixtral 等）
• deepseek - DeepSeek 模型
• openrouter - OpenRouter（300+ 种模型）

示例：

# Configure for Grok
scripts/configure_provider.sh grok grok-4-0709

# Configure for Groq with Llama
scripts/configure_provider.sh groq llama-3.3-70b-versatile

# Configure for DeepSeek Reasoner
scripts/configure_provider.sh deepseek deepseek-reasoner

# Configure for OpenAI GPT-5
scripts/configure_provider.sh openai gpt-5

该脚本会自动：

• 设置提供商配置
• 设置相应的基础 URL
• 设置默认模型
• 提供 API 密钥配置说明

步骤 3：验证 API 密钥

配置脚本会自动检查是否已设置 API 密钥；如果未找到 API 密钥，则会停止并显示明确的说明。

如果缺少 API 密钥：

脚本会以错误代码 1 退出，并显示：

• ⚠️ 警告，提示尚未设置 API 密钥
• 通过环境变量设置的说明
• 通过配置文件设置的说明（持久生效）

如果配置脚本因缺少 API 密钥而失败，请勿继续执行步骤 4。

请改为告知用户，他们需要先设置 API 密钥：

选项 1 - 环境变量（仅当前会话有效）：

export XAI_API_KEY=xai-...           # for Grok
export GROQ_API_KEY=gsk_...          # for Groq
export DEEPSEEK_API_KEY=sk-...       # for DeepSeek
export OPENROUTER_API_KEY=sk-or-...  # for OpenRouter
export OPENAI_API_KEY=sk-...         # for OpenAI

选项 2 - 配置文件（持久生效）：

swiftopenai config set api-key <api-key-value>

用户设置 API 密钥后，重新运行配置脚本进行验证。

步骤 4：执行 Agent 任务

使用 Agent 模式执行用户的请求：

swiftopenai agent "<user's question or task>"

Agent 模式功能：

• 一次性任务执行
• 内置工具调用
• 支持 MCP（Model Context Protocol）集成
• 使用会话 ID 保存对话记忆
• 多种输出格式

示例：

# Simple question
swiftopenai agent "What is quantum entanglement?"

# With specific model override
swiftopenai agent "Write a Python function" --model grok-3

# With session for conversation continuity
swiftopenai agent "Remember my name is Alice" --session-id chat-123
swiftopenai agent "What's my name?" --session-id chat-123

# With MCP tools (filesystem example)
swiftopenai agent "Read the README.md file" \
  --mcp-servers filesystem \
  --allowed-tools "mcp__filesystem__*"

使用模式

模式 1：简单的提供商路由

用户请求：“使用 grok 解释量子计算”

执行：

# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for Grok
scripts/configure_provider.sh grok grok-4-0709

# 3. Execute the task
swiftopenai agent "Explain quantum computing"

模式 2：选择特定模型

用户请求：“请让 DeepSeek Reasoner 逐步解决这道数学题”

执行：

# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for DeepSeek with Reasoner model
scripts/configure_provider.sh deepseek deepseek-reasoner

# 3. Execute with explicit model
swiftopenai agent "Solve x^2 + 5x + 6 = 0 step by step" --model deepseek-reasoner

模式 3：使用 Groq 进行快速推理

用户请求：“使用 groq 快速生成代码”

执行：

# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for Groq (known for fast inference)
scripts/configure_provider.sh groq llama-3.3-70b-versatile

# 3. Execute the task
swiftopenai agent "Write a function to calculate fibonacci numbers"

模式 4：通过 OpenRouter 访问多个模型

用户请求：“使用 OpenRouter 访问 Claude”

执行：

# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for OpenRouter
scripts/configure_provider.sh openrouter anthropic/claude-3.5-sonnet

# 3. Execute with Claude via OpenRouter
swiftopenai agent "Explain the benefits of functional programming"

提供商特定说明

OpenAI（GPT-5 模型）

GPT-5 模型支持高级参数：

# Minimal reasoning for fast coding tasks
swiftopenai agent "Write a sort function" \
  --model gpt-5 \
  --reasoning minimal \
  --verbose low

# High reasoning for complex problems
swiftopenai agent "Explain quantum mechanics" \
  --model gpt-5 \
  --reasoning high \
  --verbose high

详细程度： low、medium、high 推理力度： minimal、low、medium、high

Grok（xAI）

Grok 模型针对实时信息处理和编码进行了优化：

• grok-4-0709 - 最新版本，推理能力增强
• grok-3 - 通用模型
• grok-code-fast-1 - 针对代码生成进行了优化

Groq

以使用开源模型进行超快速推理而著称：

• llama-3.3-70b-versatile - 最佳通用模型
• mixtral-8x7b-32768 - 专家混合模型

DeepSeek

专注于推理和编码：

• deepseek-reasoner - 高级逐步推理
• deepseek-coder - 编码专用模型
• deepseek-chat - 通用聊天模型

OpenRouter

提供对 300+ 种模型的访问：

• Anthropic Claude 模型
• OpenAI 模型
• Google Gemini 模型
• Meta Llama 模型
• 以及更多模型

API 密钥管理

推荐：使用环境变量配置多个提供商

使用多个提供商的最佳实践是将所有 API 密钥设为环境变量。这样无需重新配置密钥，即可在提供商之间无缝切换。

添加到 shell 配置文件（~/.zshrc 或 ~/.bashrc）：

# API Keys for LLM Providers
export OPENAI_API_KEY=sk-...
export XAI_API_KEY=xai-...
export GROQ_API_KEY=gsk_...
export DEEPSEEK_API_KEY=sk-...
export OPENROUTER_API_KEY=sk-or-v1-...

添加后，重新加载 shell：

source ~/.zshrc  # or source ~/.bashrc

工作原理：

• SwiftOpenAI-CLI 会根据配置的提供商自动使用对应的提供商专属密钥
• 切换到 Grok 时，它会使用 XAI_API_KEY
• 切换到 OpenAI 时，它会使用 OPENAI_API_KEY
• 无需每次都重新配置密钥

替代方案：通过配置文件设置单个 API 密钥（不推荐用于多个提供商）

如果你只使用一个提供商，可以将密钥存储在配置文件中：

swiftopenai config set api-key <your-key>

限制： 配置文件只能存储一个 api-key。如果切换提供商，就需要每次都重新配置密钥。

检查当前 API 密钥

# View current configuration (API key is masked)
swiftopenai config list

# Get specific API key setting
swiftopenai config get api-key

优先级： 提供商专属环境变量的优先级高于配置文件设置。

高级功能

交互式配置

对于复杂的配置，请使用交互式向导：

swiftopenai config setup

此向导会引导你完成以下设置：

• 选择提供商
• 输入 API 密钥
• 选择模型
• 配置调试模式
• 设置基础 URL（如有需要）

会话管理

在多个请求之间保留对话上下文：

# Start a session
swiftopenai agent "My project is a React app" --session-id project-123

# Continue the session
swiftopenai agent "What framework did I mention?" --session-id project-123

MCP 工具集成

通过 Model Context Protocol 连接外部服务：

# With GitHub MCP
swiftopenai agent "List my repos" \
  --mcp-servers github \
  --allowed-tools "mcp__github__*"

# With filesystem MCP
swiftopenai agent "Read package.json and explain dependencies" \
  --mcp-servers filesystem \
  --allowed-tools "mcp__filesystem__*"

# Multiple MCP servers
swiftopenai agent "Complex task" \
  --mcp-servers github,filesystem,postgres \
  --allowed-tools "mcp__*"

输出格式

控制结果的呈现方式：

# Plain text (default)
swiftopenai agent "Calculate 5 + 3" --output-format plain

# Structured JSON
swiftopenai agent "List 3 colors" --output-format json

# Streaming JSON events (Claude SDK style)
swiftopenai agent "Analyze data" --output-format stream-json

故障排除

常见问题

问题：“swiftopenai: command not found”

解决方案：运行 check_install_cli.sh 脚本，它会自动安装 CLI。

问题：身份验证错误

解决方案：确认已为提供商设置正确的 API 密钥：

# Check current config
swiftopenai config list

# Set the appropriate API key
swiftopenai config set api-key <your-key>

# Or use environment variable
export XAI_API_KEY=xai-...  # for Grok

问题：模型不可用

解决方案：确认模型名称与提供商支持的模型一致。查看 references/providers.md 获取正确的模型名称，或运行：

swiftopenai models

问题：请求频率受限或配额错误

解决方案：这些限制因提供商而异。可以考虑：

• 使用其他模型等级
• 临时切换到其他提供商
• 查看 API 使用情况仪表板

调试模式

启用调试模式以查看详细的 HTTP 信息：

swiftopenai config set debug true

其中会显示：

• HTTP 状态代码和标头
• API 请求详情
• 响应元数据

资源

此技能包含用于支持大模型路由的捆绑资源：

scripts/

• check_install_cli.sh - 确保已安装 SwiftOpenAI-CLI，且版本为最新
• configure_provider.sh - 为特定提供商配置 CLI

references/

• providers.md - 所有受支持的提供商、模型、配置和功能的综合参考资料

最佳实践

1. 务必先检查安装情况 - 路由请求前运行 check_install_cli.sh
2. 明确配置提供商 - 使用 configure_provider.sh 确保配置正确
3. 验证 API 密钥 - 检查是否已为目标提供商设置相应的 API 密钥
4. 选择合适的模型 - 根据任务（编码、推理、一般聊天）选择模型
5. 使用会话保持上下文连贯 - 利用 --session-id 进行多轮对话
6. 启用调试模式以排查问题 - 出现问题时，调试模式可提供有价值的信息
7. 参考提供商文档 - 查阅 references/providers.md 获取提供商的详细信息

示例

示例 1：将请求路由到 Grok 以获取实时信息

# User: "Use grok to tell me about recent AI developments"

scripts/check_install_cli.sh
scripts/configure_provider.sh grok grok-4-0709
swiftopenai agent "Tell me about recent AI developments"

示例 2：使用 DeepSeek 进行逐步推理

# User: "Ask deepseek to explain how to solve this algorithm problem"

scripts/check_install_cli.sh
scripts/configure_provider.sh deepseek deepseek-reasoner
swiftopenai agent "Explain step by step how to implement quicksort"

示例 3：使用 Groq 快速生成代码

# User: "Use groq to quickly generate a REST API"

scripts/check_install_cli.sh
scripts/configure_provider.sh groq llama-3.3-70b-versatile
swiftopenai agent "Generate a REST API with authentication in Python"

示例 4：通过 OpenRouter 使用 Claude

# User: "Use openrouter to access claude and write documentation"

scripts/check_install_cli.sh
scripts/configure_provider.sh openrouter anthropic/claude-3.5-sonnet
swiftopenai agent "Write comprehensive documentation for a todo app API"

示例 5：使用自定义参数调用 GPT-5

# User: "Use gpt-5 with high reasoning to solve this complex problem"

scripts/check_install_cli.sh
scripts/configure_provider.sh openai gpt-5
swiftopenai agent "Design a distributed caching system" \
  --model gpt-5 \
  --reasoning high \
  --verbose high