Flyfree: 优雅管理 LLM Provider 配置的 CLI 工具

什么是 Flyfree？

在 AI 编程工具日益普及的今天，开发者经常需要在不同的 LLM Provider 之间切换 - 有时为了成本考虑，有时为了性能对比，有时为了适应不同的项目需求。手动修改配置文件不仅繁琐，还容易出错。

Flyfree（自由飞翔）就是为了解决这个痛点而生的 CLI 工具。它让您可以轻松管理和切换 Claude Code、Codex 等 AI 编程工具的 LLM Provider 配置。Flyfree 不仅简化了用户接入 LLM API 供应商的步骤，同时也简化了 LLM 供应商描向用户描述的接入文档。

使用 Flyfree 前后对比

不使用 Flyfree（传统方式）

以 MiniMax 集成 Codex CLI 为例，用户需要：

1. 了解 Codex CLI 的配置存储路径，掌握 Codex CLI 的配置格式。

2. 手动创建并配置配置文件 ~/.codex/config.toml：

   [model_providers.minimax]
   name = "MiniMax Chat Completions API"
   base_url = "https://api.minimax.io/v1"
   env_key = "MINIMAX_API_KEY"
   wire_api = "chat"
   requires_openai_auth = false
   request_max_retries = 4
   stream_max_retries = 10
   stream_idle_timeout_ms = 300000
   
   [profiles.m2]
   model = "codex-MiniMax-M2"
   model_provider = "minimax"

3. 认真阅读文档才发现需要手动设置环境变量

   export MINIMAX_API_KEY="<YOUR_API_KEY>"

4. 使用 profile 启动 Codex

   codex --profile m2

痛点：

• 需要了解代理特定的配置格式（TOML、JSON 等）
• 必须手动定位和管理配置文件路径
• 为每个代理重复此过程（Codex、Claude Code 等）
• 缺乏多提供商的集中管理

使用 Flyfree ✨

只需 2 条简单命令：

# 1. 安装 Flyfree
npm i -g @llmapis/flyfree

# 2. 订阅并自动应用
ff sub 'ff://minimax?key={YOUR_MINIMAX_API_KEY}' --auto

# 3. 启动 codex
codex

优势：

• ✅ 无需了解代理配置格式
• ✅ 无需知道配置文件路径
• ✅ 自动注入环境变量
• ✅ 对所有代理（Codex、Claude Code 等）使用相同方式
• ✅ 集中管理提供商
• ✅ 轻松切换不同提供商

这种简单性同样适用于 Claude Code 和任何其他支持的代理！

核心特性

🔄 一键切换

# 快速切换 Claude Code 的 Provider
ff set claude-code zhipu
ff set claude-code minimax

🔌 内置 Provider 支持

内部集成 ff:// 协议，无需外部配置服务器：

# 智谱AI
ff sub 'ff://z.ai?key=YOUR_API_KEY' --auto

# OpenRouter
ff sub 'ff://minimax?key=YOUR_API_KEY' --auto

查看已经集成的供应商列表

🛡️ 安全备份机制

• 自动备份原始配置
• 最多保留 10 个历史版本
• 一键恢复到任意备份点

🎨 优雅的 CLI 体验

• 彩色输出和进度指示
• 交互式选择器
• 详细的操作反馈

安装和快速开始

安装 Flyfree

# 全局安装（推荐）
npm install -g flyfree

# 验证安装
ff --version

或者使用 npx 直接运行：

npx flyfree --help

第一次使用

1. 订阅智谱AI Provider

首先，在 智谱AI开放平台 注册账号并获取 API Key，然后：

ff sub 'ff://z.ai?key=YOUR_API_KEY' -a zhipu --auto

💡 注意：URL 必须用引号包裹，避免 shell 解析特殊字符

2. 查看订阅状态

ff list

输出示例：

📦 Subscribed Providers:

🟢 zhipu (Z.AI)
   └── claude-code ✅ Active
   └── Last updated: 2024-11-12 10:30:45

💡 Use 'ff switch' to change configurations

3. 交互式切换

ff switch

这会启动交互式界面，让您选择 Provider 和要配置的 Agent。

详细命令说明

subscribe (sub) - 订阅 Provider

订阅并管理 LLM Provider 配置。

ff sub <url> [options]

常用选项：

• -a, --alias <name>: 设置 Provider 别名
• --auto: 自动应用配置，跳过确认
• --select: 选择要应用的 Agent

示例：

# 基础订阅
ff sub https://api.example.com/config

# 使用别名和自动应用
ff sub 'ff://z.ai?key=KEY' -a zhipu --auto

# 交互式选择 Agent
ff sub https://api.example.com/config --select

list (ls) - 查看订阅

显示所有已订阅的 Provider 和状态信息。

ff list

switch (s) - 交互式切换

通过美观的交互界面切换 Provider 配置。

ff switch

set - 快速切换

直接指定 Agent 和 Provider 进行快速切换。

ff set <agent> <provider>

# 示例
ff set claude-code zhipu
ff set codex openrouter

reset - 重置配置

将 Agent 配置重置为空状态。

ff reset [agent] [options]

# 交互式重置
ff reset

# 重置指定 Agent
ff reset claude-code

# 强制重置
ff reset claude-code --force

restore - 恢复配置

从备份恢复 Agent 配置。

# 列出所有备份
ff restore --list

# 交互式恢复
ff restore

# 恢复指定 Agent
ff restore claude-code

unsubscribe (unsub) - 取消订阅

取消订阅指定的 Provider。

ff unsub <provider> [--force]

# 示例
ff unsub zhipu
ff unsub zhipu --force  # 跳过确认

内置 Provider 详解

Flyfree 的一大创新是内置 Provider 系统，使用 ff:// 协议可以快速配置常用的 LLM 服务。

智谱AI (Z.AI)

智谱AI 是国内领先的 LLM 服务提供商，提供 Claude 和 GPT 兼容的 API。

# 订阅智谱AI
ff sub 'ff://z.ai?key=YOUR_API_KEY' -a zhipu --auto

支持的 Agent：

• claude-code: Claude 3.5 Sonnet（通过智谱AI的 Anthropic 兼容端点）
• codex: GPT-4（通过智谱AI的 OpenAI 兼容端点）

获取 API Key：

1. 访问 智谱AI开放平台
2. 注册账号并完成实名认证
3. 创建应用并获取 API Key

OpenRouter

OpenRouter 是一个多模型聚合平台，提供对多种 LLM 模型的统一访问。

# 订阅 OpenRouter
ff sub 'ff://openrouter?key=YOUR_API_KEY' -a openrouter --auto

支持的 Agent：

• claude-code: Anthropic Claude 3.5 Sonnet

获取 API Key：

1. 访问 OpenRouter
2. 注册账号并验证邮箱
3. 在设置页面生成 API Key

自定义 Provider

除了内置 Provider，您也可以订阅任何兼容 OpenAI/Anthropic API 的服务：

# 订阅自定义服务
ff sub https://your-api-server.com/config -a custom

自定义 Provider 需要返回标准的配置 JSON（v1.1 新格式）：

{
  "meta": {
    "request_id": "req-123456789-abcde",
    "code": 200,
    "message": ""
  },
  "data": {
    "name": "Custom Provider",
    "description": "My custom LLM provider",
    "payload": {
      "providers": [
        {
          "name": "claude-code",
          "hash": "config-hash",
          "setting": {
            "anthropic": {
              "apiKey": "your-api-key",
              "baseURL": "https://your-api-server.com/v1"
            },
            "modelName": "claude-3-5-sonnet-20241022"
          }
        }
      ],
      "functions": ["balance", "usage"]
    }
  }
}

错误响应示例：

{
  "meta": {
    "request_id": "req-error-401",
    "code": 401,
    "message": "API key is invalid or expired"
  },
  "data": {
    "name": "",
    "description": "",
    "payload": {
      "providers": [],
      "functions": []
    }
  }
}

💡 注意：从 v1.1 开始，响应格式改为双层结构，包含 meta 和 data 两部分。meta 包含请求ID、错误码和错误信息，支持更好的错误处理和请求追踪。详细的协议规范请参考 Flyfree 协议文档。

实际使用场景

场景1：开发环境管理

#!/bin/bash
# dev-setup.sh

# 开发环境使用经济型 Provider
ff set claude-code zhipu

# 生产环境使用高质量 Provider
ff set claude-code openrouter

echo "Environment configured!"

场景2：成本优化

根据任务类型选择不同成本的 Provider：

# 日常开发使用智谱AI（成本较低）
ff set claude-code zhipu

# 重要代码审查使用 OpenRouter（质量更高）
ff set claude-code openrouter

场景3：团队协作

# 团队配置标准化
ff sub https://team-config.company.com/llm -a team-standard --auto

# 所有团队成员使用相同配置
ff set claude-code team-standard

场景4：性能测试

# 快速切换测试不同 Provider 性能
providers=("zhipu" "openrouter" "custom")

for provider in "${providers[@]}"; do
  echo "Testing $provider..."
  ff set claude-code $provider
  # 运行测试
  time claude-code "Generate a simple function"
done

配置文件结构

Flyfree 将所有配置存储在 ~/.ff/ 目录下：

~/.ff/
├── sub.json                    # 订阅信息
├── backups/                    # 配置备份
│   └── claude-code/
│       └── 1699856845123.json
└── {provider-name}/           # Provider 配置
    ├── config.json
    ├── claude-code/
    │   └── config.json
    └── codex/
        └── config.json

订阅配置 (sub.json)

{
  "subscribes": {
    "zhipu": {
      "sub_url": "ff://z.ai?key=***",
      "providers": ["claude-code", "codex"],
      "status": "success",
      "updated_at": 1699856845123,
      "hash": "abc123..."
    }
  },
  "setting": {
    "claude-code": {
      "provider": "zhipu"
    }
  }
}

故障排除

常见问题

1. 订阅失败

# 启用调试模式查看详细错误
DEBUG=1 ff sub https://example.com/config

2. API Key 无效

# 检查 API Key 格式
ff sub 'ff://z.ai?key=YOUR_ACTUAL_KEY' -a test

3. 配置文件权限问题

# 修复权限
chmod 755 ~/.ff/
chmod 644 ~/.ff/sub.json

4. 完全重置

# 删除所有配置重新开始
rm -rf ~/.ff/
ff sub 'ff://z.ai?key=KEY' -a zhipu --auto

调试技巧

# 查看详细日志
DEBUG=1 ff <command>

# 检查配置文件
cat ~/.ff/sub.json | jq

# 验证网络连接
curl -I https://open.bigmodel.cn/api/paas/v4/anthropic

配置备份

# 定期备份配置
cp ~/.ff/sub.json ~/.ff/sub.json.backup.$(date +%Y%m%d)

# 健康检查
ff list | grep -E "(Active|Failed)"

技术架构

Flyfree 采用模块化的 TypeScript 架构：

核心组件

1. CLI Interface: 使用 Commander.js 构建用户友好的命令行界面
2. Configuration Management: JSON Schema 验证和文件系统存储
3. Provider System: 可扩展的 Provider 注册和管理机制
4. Backup System: 自动备份和恢复机制

技术栈

• Language: TypeScript
• Runtime: Node.js 18+
• CLI Framework: Commander.js
• Validation: Ajv (JSON Schema)
• HTTP Client: Axios
• UI Components: Inquirer, Ora, Chalk

设计原则

• 类型安全: 完整的 TypeScript 类型定义
• 模块化: 清晰的职责分离
• 可扩展: 易于添加新的 Provider 和 Agent
• 用户友好: 优雅的错误处理和用户反馈

总结

Flyfree 解决了 AI 编程工具配置管理的一个重要痛点。通过提供统一的命令行界面、安全的备份机制和内置的 Provider 支持，它让开发者可以更加灵活地使用不同的 LLM 服务。

无论您是需要在开发和生产环境之间切换，还是想要优化 API 调用成本，或者只是想要体验不同的 LLM 模型，Flyfree 都能为您提供简单而强大的解决方案。

相关链接

• GitHub: github.com/llmapis/flyfree
• NPM: npmjs.com/package/flyfree

立即安装 Flyfree，开始您的 LLM Provider 管理之旅！

npm i -g @llmapis/flyfree
ff --help