功能描述

多平台API Key分层轮询与智能故障转移；当用户需要绕过单一API Key速率限制、实现高可用大模型调用或管理多厂商API密钥池时使用

使用说明 (SKILL.md)

LLM Key Pool - 分层轮询多平台API Key管理

Name: llm-key-pool
Author: chatgpt34993

任务目标

本Skill用于：多平台API Key智能管理，实现分层轮询、跨层切换和自动故障转移
能力包含：分层配置管理、自动轮询、跨层切换、429错误智能处理、统一OpenAI兼容接口
触发条件：当Agent需要稳定调用大模型API且面临速率限制或单点故障风险时

前置准备

依赖安装

SKILL依赖以下Python包：

pyyaml>=6.0.0

配置文件准备

在使用前需要创建配置文件 llm_config.yaml，支持分层配置：

主力层（primary）：高额度平台（阿里云百炼、智谱AI）
每日回血层（daily）：每日刷新平台（火山引擎、Google AI Studio）
兜底层（fallback）：开源/聚合平台（硅基流动、OpenRouter等）

配置文件格式见 references/config_format.md

支持的AI平台及配置方法见 references/supported_providers.md

操作步骤

标准流程

准备配置文件
- 在当前目录创建 llm_config.yaml
- 按分层策略配置各平台的API Key
- 优先配置主力层，然后是每日回血层，最后是兜底层
调用LLM服务
- 执行脚本：python -m llm_key_pool.llm_client
- 参数说明：
  - --config: 配置文件路径（默认：./llm_config.yaml）
  - --prompt: 用户提示词
  - --system-prompt: 系统提示词（可选）
  - --temperature: 温度参数（可选，默认：0.7）
  - --max-tokens: 最大Token数（可选，默认：2000）
自动分层轮询
- 优先使用主力层API Key
- 主力层所有Key不可用时，自动切换到每日回血层
- 每日回血层也不可用时，切换到兜底层
- 跨层切换对上层应用透明
智能故障转移
- 监听429 Too Many Requests错误
- 立即标记当前Key为冷却中
- 无缝切换到下一个Key或下一层
- 冷却结束后自动恢复

可选分支

当需要测试配置是否正确：使用 --test 参数进行配置验证
当需要查看Key池状态：使用 --status 参数查看各层级Key的使用情况

资源索引

核心脚本

llm_key_pool/config_loader.py - 配置文件加载和验证
llm_key_pool/key_pool.py - 分层API Key池管理和轮询逻辑
llm_key_pool/llm_client.py - 统一LLM调用接口（OpenAI兼容）

参考文档

references/config_format.md - 配置文件格式说明（分层版）
references/supported_providers.md - 支持的AI平台列表

注意事项

API Key信息敏感，请勿将配置文件提交到版本控制系统
建议按分层策略配置至少3个平台（主力层、每日回血层、兜底层各1个）
429错误会触发立即冷却，冷却时间可通过配置调整
故障转移和跨层切换对上层应用透明，但会略微增加延迟
优先选择支持OpenAI兼容接口的平台，简化配置

使用示例

示例1：基本调用

python -m llm_key_pool.llm_client \
  --config ./llm_config.yaml \
  --prompt "解释什么是量子计算" \
  --temperature 0.7 \
  --max-tokens 500

示例2：带系统提示词

python -m llm_key_pool.llm_client \
  --config ./llm_config.yaml \
  --prompt "写一个关于AI的短故事" \
  --system-prompt "你是一个创意写作专家"

示例3：查看Key池状态

python -m llm_key_pool.llm_client \
  --config ./llm_config.yaml \
  --status

示例4：验证配置

python -m llm_key_pool.llm_client \
  --config ./llm_config.yaml \
  --test

分层轮询策略

主力层（primary）

特点：初始赠送额度极大
推荐平台：阿里云百炼、智谱AI
用途：处理大部分日常任务

每日回血层（daily）

特点：额度每日刷新
推荐平台：火山引擎、Google AI Studio
用途：主力层耗尽后保证基本可用性

兜底层（fallback）

特点：开源模型/聚合平台
推荐平台：硅基流动、OpenRouter、GitHub Models、Groq
用途：大厂API都限流时保证服务不中断

安全使用建议

This package appears to implement an API-key rotation and failover client and will behave as expected for that purpose, but before installing or providing real keys you should: - Verify provider support: inspect llm_key_pool/llm_client.py to confirm it implements any provider-specific authentication your providers require (the code only special-cases Anthropic; Google/other providers mentioned in docs may need different handling). - Fix documentation/file mismatches: SKILL.md/README refer to assets/llm_config.yaml.example which isn't in the package (there's assets/llm_config.quickstart.yaml). Ensure you have the correct template before populating it with real keys. - Installation method: decide whether to pip install the package (so the 'llm-key-pool' CLI exists) or run with python -m llm_key_pool.llm_client; the bundled run.sh assumes the CLI name. - Protect keys: do not commit llm_config.yaml to VCS; use non-critical/test keys first to validate behavior. - Terms-of-service risk: the tool is explicitly designed to rotate keys to work around single-key rate limits; using it to circumvent provider rate limits or quotas may violate provider terms — consider the legal/ethical implications. If you want higher confidence, request the missing/omitted code sections for a thorough line-by-line review (to confirm there are no hidden network endpoints, telemetry, or exfiltration paths) and run the client with test keys in a controlled environment first.

功能分析

Type: OpenClaw Skill Name: llm-key-pool Version: 1.0.0 The llm-key-pool skill bundle is a utility designed to manage a tiered pool of LLM API keys to handle rate limits and provide failover capabilities. The code includes a configuration loader (config_loader.py), a stateful key pool manager (key_pool.py), and a client (llm_client.py) that supports both OpenAI-compatible and Anthropic API formats. While the bundle includes a setup helper (setup_helper.py) that prompts users for sensitive API keys and recommends some niche providers (e.g., XiaoLongXia, OpenCode), the keys are stored locally in a YAML file that is explicitly ignored by version control (.gitignore). The logic is transparent, lacks any evidence of data exfiltration or unauthorized execution, and follows the stated purpose of providing a high-availability LLM calling interface.

能力评估

⚠ Purpose & Capability

The skill's name/description and code (key_pool, llm_client, config_loader) are consistent with a multi-tier API-key rotation/failover tool. However the README/SKILL.md claim broad support for many providers and some provider-specific quirks (e.g., Google requiring URL-parameter keys) while the visible client code only special-cases Anthropic and otherwise uses a generic OpenAI-compatible Authorization header. That suggests the implementation may not actually support all the provider-specific authentication/formatting notes in the docs. Also the repository includes unrelated example files (binary_tree) which are not needed for the stated purpose.

⚠ Instruction Scope

Runtime instructions ask the user to create an llm_config.yaml and run the client; that's appropriate. But there are inconsistencies: README/SKILL.md instruct to copy assets/llm_config.yaml.example which is not present in the manifest (there is assets/llm_config.quickstart.yaml instead). The declared entrypoint in skill.yaml is scripts/run.sh which calls the CLI name 'llm-key-pool' (installed via pip), yet SKILL.md also shows running python -m llm_key_pool.llm_client — the two entry methods assume different installation steps. These mismatches could cause runtime confusion. The instructions do not request unrelated system files or environment variables — they expect the user to place API keys in a YAML file.

ℹ Install Mechanism

There is no remote download or install hook in the skill registry metadata (instruction-only), which minimizes supply-chain risk. The package includes Python code and a pyproject/requirements, meaning realistic usage generally requires pip install (or running with python -m). The skill.yaml entrypoint references scripts/run.sh and a CLI 'llm-key-pool' script (defined in pyproject), so some install step is expected but not described consistently in SKILL.md — minor coherence issue but not an obvious security hazard.

✓ Credentials

The skill does not request platform environment variables or credentials from the runtime environment; instead it expects API keys provided by the user in a local YAML config (llm_config.yaml). That is proportionate to the declared purpose. Note: storing many provider keys in one local file is sensitive; the project .gitignore excludes llm_config.yaml which is appropriate but users must still avoid committing it or sharing it.

✓ Persistence & Privilege

The skill does not request always:true or other elevated persistent privileges and does not modify other skills' configs. It runs as a normal Python package/script and will only act when invoked (or if the platform installs it as a skill and triggers it).

版本历史

v1.0.0

### v1.0.0 - 首发版本，支持多平台API Key分层管理、轮询与智能故障转移 - 提供主力层、每日回血层、兜底层分层配置策略 - 自动监听429错误，冷却当前Key并无缝切换下一个Key或层 - 支持OpenAI兼容调用接口，统一多平台操作 - 内置配置验证、Key池状态查询等实用命令行功能

元数据

Slug llm-key-pool

版本 1.0.0

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 1

常见问题

llm-key-pool 是什么？

多平台API Key分层轮询与智能故障转移；当用户需要绕过单一API Key速率限制、实现高可用大模型调用或管理多厂商API密钥池时使用. 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 89 次。

如何安装 llm-key-pool？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install llm-key-pool」即可一键安装，无需额外配置。

llm-key-pool 是免费的吗？

是的，llm-key-pool 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

llm-key-pool 支持哪些平台？

llm-key-pool 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 llm-key-pool？

由 River（@chatgpt34993）开发并维护，当前版本 v1.0.0。

llm-key-pool