📦 FreeRide -Gateway — FreeRide 网关
v1.0.0当用户安装了FreeRide（二进制文件位于~/.local/bin/freeride，网关在http://localhost:11343）或询问如何路由他们的AI工作流时，请使用此技能。
by 运行时依赖
安装命令
点击复制技能文档
FreeRide FreeRide 是一个运行在 http://localhost:11343 的本地网关。它接受 OpenAI Chat Completions API 请求，并将其转发到用户具有密钥的任意免费层提供商，当一个提供商或密钥达到限速或出错时，会自动切换到其他提供商或密钥。这个技能教你（代理）如何检测 FreeRide，连接任何 OpenAI 形式的客户端，诊断故障，并使用其 CLI。
检测 FreeRide 是否运行
按顺序，从最便宜开始：
健康检查 — curl -s http://localhost:11343/health。当正常运行时，返回 {"ok": true, "version": "0.x.y", "providers": [...]}。
进程检查 — lsof -iTCP:11343 -sTCP:LISTEN -n -P 2>/dev/null 或 ss -tlnp | grep 11343 在 Linux 上。
配置存在 — ~/.freeride/config.json 存在（意味着 FreeRide 已经安装，即使当前没有运行）。
端口 11343 是硬编码的 — FreeRide 拒绝自动选择不同的端口，因为代理配置（Aider 的 OPENAI_API_BASE、Continue 的 apiBase 等）都是针对这个确切值编写的。
连接任何 OpenAI 形式的客户端
export OPENAI_API_BASE=http://localhost:11343/v1
export OPENAI_API_KEY=任意值
OPENROUTER_API_KEY 中读取）进行出站调用。设置任意值、未使用的值或任何字面字符串都可以。Python（openai SDK）
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11343/v1", api_key="任意值")
resp = client.chat.completions.create(
model="openrouter/free", # 或任意模型从 /v1/models
messages=[{"role": "user", "content": "hello"}],
)
curl http://localhost:11343/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model": "openrouter/free", "messages": [{"role": "user", "content": "hi"}]}'
curl http://localhost:11343/v1/chat/completions?stream=true \
-H 'Content-Type: application/json' \
-d '{"model": "openrouter/free", "messages": [{"role": "user", "content": "hello"}]}'
curl http://localhost:11343/v1/models
{"object": "list", "data": [...]} 形式。所有配置的提供商的模型都在一个平面列表中，以 id 删除重复项。添加 ?refresh=true 以绕过 6 小时缓存。识别哪个提供商服务了一个请求
非流式传输：响应 JSON 包括 _freeride_provider: ""。
流式传输：响应包括 X-FreeRide-Provider: 标头。有助于调试：如果完成似乎不符或不符合规范，请检查此字段以确定是否启用了回退。
CLI 参考
freeride serve # 启动网关在 localhost:11343
freeride bind # 将网关 URL 写入代理配置
freeride list # 列出可用的免费模型，按排名
freeride status # 显示 OpenClaw 配置 + 缓存年龄（v2）
freeride auto # 自动配置 OpenClaw（v2）
freeride rotate # 交换主要提供商如果它失败（v2）
freeride telemetry [on|off] # 管理遥测信标
freeride-watcher # 后台守护进程，旋转失败
freeride bind 支持：aider、continue、hermes、openclaw。它以原子方式写入代理配置并保留无关键。提供商环境变量设置
| 提供商 | 环境变量 | 备注 |
|---|---|---|
| OpenRouter | OPENROUTER_API_KEY | 最多测试的提供商 |
| Groq | GROQ_API_KEY | 硬编码免费层允许列表 |
| NVIDIA | NVIDIA_API_KEY | 策划允许列表 |
| Cloudflare Workers AI | CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID | 帐户 ID 是 URL 的一部分 |
| HuggingFace | HF_TOKEN（或 HUGGINGFACE_API_KEY） | $0.10/月免费，$2/月 PRO 预算 |
export OPENROUTER_API_KEY='["sk-or-v1-key1","sk-or-v1-key2"]'
~/.freeride/cooldown.json）。故障排除
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| 网关返回 503 | 所有（提供商，密钥）对都失败 | 检查 freeride list 以确定哪些提供商具有可用的密钥；检查上游提供商状态 |
| 命令未找到：freeride 后安装 | 控制台脚本不在 PATH 上 | 使用 python -m freeride 作为回退，或将 ~/.local/bin 添加到 PATH |
| 首次运行横幅垃圾邮件 | 遥测披露（一次性） | 运行 freeride telemetry off 以选择退出 |
| 没有配置提供商 | 没有设置环境变量 | 设置至少一个提供商密钥（见上表） |
| httpx.HTTPStatusError 导入错误 | 旧安装具有 httpx 1.0.dev3 | 升级 FreeRide；v0.3.0a3+ 固定 httpx>=0.27,<1 |
| 故障转移语义（用于诊断为什么请求转到哪里） | 每个请求，FreeRide 遍历（提供商，密钥）对的注册顺序。对于每个对：RATE_LIMIT 或 AUTH → 标记此密钥冷却 120 秒，推进同一提供商中的密钥。MODEL_NOT_FOUND → 跳过此提供商的其余密钥，推进到下一个提供商。 |