owl-agent-free-ai-proxy-gateway

<div align="center"> # 🦉 OWL-AGENT ## 免费 AI 代理网关 — 统一协同安装器 ### 一个网关 · 所有 AI 模型 · 零成本 [](./install_owl_unified.sh) [](https://ubuntu.com/) [](./LICENSE) [](./Containerfile) [](./owl_resilient_mcp.py) **免费层代理访问 Antigravity、Claude、OpenCode、Copilot、Kiro 和 Hermes — 为 Linux Ubuntu 8GB RAM 优化** [快速开始](#-快速开始) · [架构](#-架构) · [安装](#-安装) · [配置](#-配置) · [API 参考](#-cli-标志参考) · [贡献](#-贡献) <img src="./docs/images/hero.png" alt="OWL-AGENT Hero" width="720" /> </div> --- ## 🔍 什么是 OWL-AGENT？ OWL-AGENT 是一个 **免费、开源的 AI 代理网关**，它通过单个本地端点统一访问六大 AI 提供商。适用于需要可靠、零成本访问前沿 AI 模型的开发者、研究人员和 AI 爱好者，无需管理多个 API 密钥、计费账户或特定于提供商的 SDK。 网关完全在您的机器上运行 — 无云依赖、无遥测、无供应商锁定。它使用智能负载均衡、预测性电路中断和社区网格同步，自动发现、验证和路由请求通过免费层端点。 ### 为什么选择 OWL-AGENT？ | 问题 | OWL-AGENT 解决方案 | |---------|-------------------| | 多个 AI 提供商，多个 API 密钥 | 单个本地端点 `localhost:8333` | | 免费层速率限制中断工作流 | Auto-Tuner 动态优化请求节奏 | | 手动代理列表管理 | Mesh Sync 共享验证的代理对等 | | 代理故障导致无声停机 | 预测性电路中断器预路由在故障前 | | Docker 需要根守护进程 | Podman 无根、无守护进程、安全运行 | | 内存受限的 VPS 环境 | 调整为 8GB RAM，自动交换管理 | ### 支持的 AI 提供商 | 提供商 | 类型 | 免费层 | 协议 | |----------|------|-----------|----------| | 🌀 **Antigravity** | 多模型代理 | 是 | HTTP/REST | | 🧠 **Claude** | Anthropic API | 免费层 | HTTP/REST | | 🔓 **OpenCode** | 开源模型 | 是 | HTTP/REST | | 💡 **Copilot** | GitHub Copilot | 免费层 | HTTP/REST | | 🔑 **Kiro** | Kiro 网关 | CLI 免费 | HTTP/gRPC | | 📨 **Hermes** | 社区代理 | 是 | HTTP/REST | --- ## ⚡ 快速开始 ### 一行安装（裸金属） ```bash curl -fsSL https://raw.githubusercontent.com/marktantongco/owl-agent-free-ai-proxy-gateway/main/install_owl_unified.sh | bash ``` ### Podman 容器 ```bash podman build -t owl-agent:7.0 -f Containerfile . podman run -d --name owl -p 60000:60000 -p 8333:8333 owl-agent:7.0 ``` ### Podman Compose ```bash podman-compose up -d ``` ### 验证 ```bash curl -s http://localhost:8333/health | jq . ``` --- ## 📦 安装 ### 方法 1：裸金属（推荐） 最佳适用于：专用服务器、VPS、本地开发机器，具有完全控制权。 ```bash # 克隆仓库 git clone https://github.com/marktantongco/owl-agent-free-ai-proxy-gateway.git cd owl-agent-free-ai-proxy-gateway # 运行统一安装器 chmod +x install_owl_unified.sh ./install_owl_unified.sh # 使用选项 ./install_owl_unified.sh --enable-mesh --enable-enrich --verbose ``` 安装程序自动： - 检测系统资源并配置交换空间，如果 RAM < 4GB - 在 `~/.owl-agent/venv` 处创建 Python 虚拟环境 - 安装所有 Python 依赖项 - 配置 systemd 用户服务以自动启动 - 在 60000 端口设置转发代理，在 8333 端口设置网关 - 可选地克隆和构建 Kiro 网关 ### 方法 2：Podman 容器 最佳适用于：隔离部署、CI/CD 管道、可复制环境。 ```bash # 构建容器镜像 podman build -t owl-agent:7.0 -f Containerfile . # 运行并限制资源（优化为 8GB RAM） podman run -d \ --name owl-agent \ --memory=6g \ --cpus=2 \ -p 60000:60000 \ -p 8333:8333 \ -p 42100:42100/udp \ -v owl-data:/home/owl/data \ owl-agent:7.0 ``` ### 方法 3：Podman Compose 最佳适用于：多服务部署，持久存储。 ```bash # 启动所有服务 podman-compose up -d # 查看日志 podman-compose logs -f owl-agent # 停止 podman-compose down ``` ### 方法 4：Systemd Quadlet 最佳适用于：具有自动重启和日志管理的生产服务器。 ```bash # 安装 quadlet 文件 cp owl-quadlet.container ~/.config/containers/systemd/ # 重新加载 systemd 并启动 systemctl --user daemon-reload systemctl --user start owl-quadlet # 启用开机启动 loginctl enable-linger $(whoami) systemctl --user enable owl-quadlet ``` --- ## 🏗️ 架构 <img src="./docs/images/v7-architecture.png" alt="OWL-AGENT v7.0 Architecture" width="720" /> ### 核心组件 | 组件 | 文件 | 版本 | 描述 | |-----------|------|---------|-------------| | **统一安装器** | [`install_owl_unified.sh`](./install_owl_unified.sh) | v7.0 | 所有组件的一键安装 | | **转发代理** | [`forward_proxy.py`](./forward_proxy.py) | v3.0 | AutoTuner + MeshSync + 预测性电路中断器 | | **防御层** | [`proxy_defense_fixed_v3.py`](./proxy_defense_fixed_v3.py) | v3.3 | 有界 LRU 缓存 + 弹性客户端重试 | | **MCP 服务器** | [`owl_resilient_mcp.py`](./owl_resilient_mcp.py) | v1.1 | 5 工具 MCP 服务器（stdin/stdout JSON-RPC） | | **网格替代方案** | [`mesh_alternatives.py`](./mesh_alternatives.py) | v1.0 | TCP gossip + Redis pub/sub 网格替代方案 | | **诊断** | [`diagnose.sh`](./diagnose.sh) | v2.0 | 系统健康检查和故障排除 | | **容器** | [`Containerfile`](./Containerfile) | v1.0 | Podman/OCI 兼容构建配方 | | **Compose** | [`podman-compose.yml`](./podman-compose.yml) | v1.0 | 多服务编排 | | **Quadlet** | [`owl-quadlet.container`](./owl-quadlet.container) | v1.0 | Systemd 集成 Podman | ### 数据流 ``` ┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ 客户端 │────▶│ 网关 :8333 │────▶│ Auto-Tuner │ │ (任意 SDK) │ │ (入口点) │ │ (速率控制) │ └─────────────┘ └──────────────────┘ └────────┬────────┘ │ ┌──────────────────────────┤ ▼ ▼ ┌─────────────────┐ ┌──────────────────┐ │ 电路中断器 │ │ 网格同步 │ │ (预测) │ │ (代理共享) │ └────────┬────────┘ └────────┬─────────┘ │ │ ▼ ▼ ┌─────────────────────────────────────────┐ │ 防御层 (LRU + 弹性) │ └────────────────────┬────────────────────┘ │ ┌───────┬───────┬────┴────┬────────┬────────┐ ▼ ▼ ▼ ▼ ▼ ▼ Antigravity Claude OpenCode Copilot Kiro Hermes ``` --- ## 🧠 3 个新颖的想法（核心创新） ### 1. Auto-Tuner 守护进程（核心） Auto-Tuner 是 OWL-AGENT 的核心 — 一个后台守护进程，持续监控代理响应时间、错误率和吞吐量，以动态调整请求路由和并发级别。与使用固定阈值的静态速率限制器不同，Auto-Tuner 实时学习每个提供商免费层的实际容量，并在拥塞发生前重新分配负载。 **工作原理：** - 每 5 秒采样一次每个提供商端点的延迟 - 计算具有 α=0.3 的指数移动平均值（EMA） - 当 EMA 延迟超过基准值的 2 倍时，触发渐进式降级 - 在条件改善时自动将并发度扩大 - 在 `~/.owl-agent/cache/tuner_state.json` 中持久化调谐状态 **配置：** ```json { "auto_tuner": { "sample_interval_sec": 5, "ema_alpha": 0.3, "degradation_factor": 2.0, "recovery_factor": 1.5, "min_concurrency": 1, "max_concurrency": 10 } } ``` ### 2. 代理网格同步（社区） 网格同步将每个 OWL-AGENT 实例变成健康数据的使用者和贡献者。当一个节点发现一个可用的免费层端点时，它会将该发现广播到网格中，使所有节点受益。这样就创建了一个社区驱动的、自愈的代理网络，随着每个参与者的加入而变得更加智能。 **默认：** 在 42100 端口使用 UDP 多播（在局域网上工作）。 **云/互联网：** TCP gossip + Redis pub/sub（参见 [`mesh_alternatives.py`](./mesh_alternatives.py)）。 **启用网格同步：** ```bash ./install_owl_unified.sh --enable-mesh ``` **网格替代方案：** | 传输方式 | 最适合 | 延迟 | 设置 | |-----------|----------|---------|-------| | UDP 多播 | LAN / 局域网 | <1ms | 零配置 | | TCP gossip | 云 / 跨区域 | 10-50ms | 需要对等列表 | | Redis Pub/Sub | 缩放部署 | 1-5ms | 需要 Redis 实例 | ### 3. 预测性电路中断器（优化） 传统的电路中断器在故障发生后才做出反应。OWL-AGENT 的预测性电路中断器使用最近的请求模式统计分析来预测故障发生前的情况。它监控错误率趋势、延迟百分位和提供商特定的降级信号，主动将流量转移到即将失败的端点。 **预测模型：** - 跟踪 P50、P95 和 P99 延迟百分位，每个提供商 - 计算错误率速度（每分钟错误趋势） - 在预测的错误率 > 30 秒内 > 15% 时触发预emptive 重新路由 - 冷却期防止振荡在提供商之间 --- ## 🔄 网格同步替代方案 <img src="./docs/images/mesh-comparison.png" alt="Mesh Sync Comparison" width="600" /> UDP 多播在本地网络上效果很好，但不能在云提供商或公共互联网上运行。 [`mesh_alternatives.py`](./mesh_alternatives.py) 模块提供了两个生产就绪的替代方案： ### TCP gossip 协议 每个节点维护一个对等列表，并定期与随机对等节点交换健康摘要。这种最终一致的方法不需要中央协调器，并可以很好地处理节点流失。 ```bash python3 mesh_alternatives.py --mode gossip --peers 10.0.1.2:42100,10.0.1.3:42100 ``` ### Redis Pub/Sub 对于具有共享 Redis 实例的部署，这提供了最低延迟的网格和最强的 consistency 保证。每个节点发布健康更新到一个通道，并订阅其他节点的所有更新。 ```bash python3 mesh_alternatives.py --mode redis --redis-url redis://10.0.1.50:6379/0 ``` --- ## 🐋 Podman vs Docker | 特性 | Podman | Docker | |---------|--------|--------| | 需要 root | ❌ 否 | ✅ 是（守护进程） | | 守护进程 | ❌ 无 | ✅ 有 | | Systemd 集成 | ✅ 原生 quadlet | ⚠️ 需要包装器 | | Kubernetes YAML | ✅ 兼容 | ✅ 兼容 | | Docker Compose | ✅ 通过 podman-compose | ✅ 原生 | | 安全配置文件 | ✅ 无 root + SELinux | ⚠️ Root 守护进程 | | 内存占用 | ~20MB | ~80MB | | 启动时间 | <1s | 2-5s | OWL-AGENT v7.0 独家使用 Podman，以其安全优势（无 root、无守护进程）和更低的资源占用量 — 对 8GB RAM 环境至关重要。所有容器工件都是 OCI 兼容的，如果需要，也适用于 Docker。 --- ## 🛠️ CLI 标志参考 ### install_owl_unified.sh | 标志 | 描述 | 默认值 | |------|-------------|---------| | `--skip-kiro` | 跳过 Kiro 网关安装 | `false` | | `--skip-gateway` | 跳过网关设置 | `false` | | `--enable-enrich` | 启用响应丰富管道 | `false` | | `--enable-mesh` | 启用网格同步（UDP 多播） | `false` | | `--dry-run` | 模拟安装而不更改 | `false` | | `--uninstall` | 删除所有 OWL-AGENT 组件 | `false` | | `--verbose` | 启用调试日志记录 | `false` | | `--help` | 显示帮助信息 | — | ### forward_proxy.py | 标志 | 描述 | 默认值 | |------|-------------|---------| | `--port` | 代理监听端口 | `60000` | | `--gateway-port` | 网关监听端口 | `8333` | | `--config` | 配置目录路径 | `~/.owl-agent/config` | | `--log-level` | 日志记录级别 | `INFO` | | `--tuner-interval` | Auto-Tuner 采样间隔（秒） | `5` | | `--mesh-port` | 网格同步 UDP 端口 | `42100` | | `--no-mesh` | 禁用网格同步 | `false` | | `--circuit-breaker` | 启用预测性电路中断器 | `true` | ### diagnose.sh | 标志 | 描述 | 默认值 | |------|-------------|---------| | `--full` | 全面的诊断报告 | `false` | | `--json` | 输出 JSON 格式 | `false` | | `--fix` | 尝试自动修复 | `false` | --- ## ⚙️ 配置 ### 目录结构 ``` ~/.owl-agent/ ├── config/ │ ├── proxy_pool.json # 提供商端点 │ ├── proxy_sources.json # 自动发现源 │ └── tuner_state.json # Auto-Tuner 持久状态 ├── logs/ │ ├── proxy.log # 前向代理日志 │ ├── gateway.log # 网关访问日志 │ └── mesh.log # 网格同步日志 ├── cache/ │ └── data/| └── http/ # 响应缓存（LRU，有界） ├── venv/ # Python 虚拟环境 └── data/ # 持久化代理数据 ``` ### 代理池配置 编辑 `~/.owl-agent/config/proxy_pool.json` 添加自定义代理端点： ```json { "tier_1_managed_free": { "providers": [ { "url": "http://127.0.0.1:60000", "type": "http", "protocol": "http", "note": "本地 OWL 前向代理" } ] }, "tier_2_public": { "providers": [ { "url": "http://your-custom-proxy:8080", "type": "http", "protocol": "http", "note": "自定义代理端点" } ] } } ``` ### MCP 服务器工具 OWL-AGENT MCP 服务器 (`owl_resilient_mcp.py`) 通过 stdin/stdout JSON-RPC 提供 5 种工具： | 工具 | 描述 | |------|-------------| | `health_check` | 返回系统健康状态和提供商可用性 | | `proxy_list` | 列出所有配置的代理端点及其健康分数 | | `proxy_route` | 通过可用的最佳代理路由请求 | | `mesh_status` | 返回网格同步连接性和对等节点健康状况 | | `tune_config` | 读取或修改 Auto-Tuner 参数 | **MCP 集成示例（Claude Desktop）：** ```json { "mcpServers": { "owl-agent": { "command": "python3", "args": ["/path/to/owl_resilient_mcp.py"], "env": { "OWL_HOME": "/home/user/.owl-agent" } } } } ``` --- ## 💾 内存调优（8GB RAM） OWL-AGENT v7.0 专门针对 8GB RAM Linux 环境进行了调优。安装程序会自动应用这些优化： | 组件 | 内存限制 | 配置 | |-----------|-------------|---------------| | 前向代理 | 512MB | Python 进程 ulimit | | 防御缓存 | 128MB | LRU 缓存 max_size | | Auto-Tuner | 64MB | 历史窗口 | | 网格同步 | 64MB | 对等健康表 | | MCP 服务器 | 32MB | 连接池 | | 系统保留 | ~7GB | 操作系统 + 其他服务 | **交换内存管理：** 如果安装时 RAM < 4GB，安装程序会自动创建一个 2GB 的交换文件，位于 `/swapfile`，并在 `/etc/fstab` 中配置。 ```bash # 检查当前内存使用情况 diagnose.sh --full | grep -A5 "Memory" # 手动调优：减少缓存大小 export OWL_CACHE_MAX_MB=64 ``` --- ## 📜 版本历史与升级路径 ### v7.0（当前） — 2025-06 - **新增**：支持 Kiro 提供商与 CLI 集成 - **新增**：Hermes 社区代理提供商 - **新增**：预测性电路中断器（OPTIMAL 层） - **新增**：Podman Containerfile + Compose + Quadlet - **新增**：网格替代方案（TCP gossip，Redis pub/sub） - **更改**：从 Docker 迁移到 Podman（无 root，无守护进程） - **更改**：移除了 Gemini 和 DeepSeek（免费层已停止） - **更改**：Auto-Tuner 现在使用 EMA，α 可配置 - **修复**：防御层有界 LRU 缓存防止无边界增长 - **修复**：具有指数退避 + 抖动的弹性客户端重试 ### v6.0 — 2025-04 - 添加了网格同步（UDP 多播） - 添加了 Auto-Tuner 守护进程 - 添加了 v1.0 MCP 服务器 - 添加了诊断脚本 ### v5.1 — 2025-03 - 修复了代理防御缓存溢出 - 添加了响应丰富管道 - 改进了前向代理中的错误处理 ### v5.0 — 2025-02 - 初始统一安装器 - 支持 Antigravity、Claude、OpenCode、Copilot - 基本的轮询代理路由 ### 升级指南 ```bash # 从 v6.x 到 v7.0 ./install_owl_unified.sh # 安装原地，保留配置 # 从 v5.x 到 v7.0 ./install_owl_unified.sh --enable-mesh # 新网格功能 # 注意：v6.0 中配置文件格式已更改 — 备份 ~/.owl-agent/config ``` ### 降级指南 ```bash # 回滚到 v6.0 git clone -b v6.0 https://github.com/marktantongco/owl-agent-free-ai-proxy-gateway.git cd owl-agent-free-ai-proxy-gateway ./install_owl_unified.sh ``` --- ## 🔧 诊断 运行内置诊断工具来排查问题： ```bash # 快速健康检查 ./diagnose.sh # 完整诊断报告 ./diagnose.sh --full # JSON 输出，用于编程使用 ./diagnose.sh --full --json ``` # 自动修复常见问题 ./diagnose.sh --fix ``` 诊断工具检查： - Python 版本和虚拟环境 - 代理和网关端口可用性 - 提供者端点可达性 - 内存和交换状态 - 网格同步连接性 - 自动调节器状态和健康状况 - 常见错误日志文件分析 --- ## 🐛 故障排除 ### 端口已被占用 ```bash # 查找占用端口 60000 的进程 ss -tlnp | grep 60000 # 杀死该进程 kill $(lsof -t -i:60000) # 或使用其他端口 ./install_owl_unified.sh --port 60001 ``` ### 网格同步不工作（云环境） 云环境中 UDP 多播无法工作。请改用 TCP gossip： ```bash python3 mesh_alternatives.py --mode gossip --peers peer1:42100,peer2:42100 ``` ### 高内存使用率 ```bash # 检查组件内存 ps aux | grep -E 'forward_proxy|defense|mcp' # 减少缓存大小 export OWL_CACHE_MAX_MB=32 # 禁用网格同步 export OWL_MESH_ENABLED=false ``` ### 自动调节器信号问题 自动调节器使用带有信号量的线程。在高并发情况下，您可能会看到信号竞争。这是非关键的并且可以自我解决： ```bash # 在配置文件中减少最大并发数 # 编辑 ~/.owl-agent/config/tuner_state.json # 将 "max_concurrency" 设置为较低的值（例如 5） ``` --- ## 🤝 贡献 我们欢迎社区的贡献！以下是开始贡献的方法： 1. **Fork** 仓库 2. **创建** 功能分支：`git checkout -b feature/my-feature` 3. **提交** 您的更改：`git commit -m 'Add my feature'` 4. **推送** 到您的分支：`git push origin feature/my-feature` 5. **打开** 拉取请求 ### 开发环境设置 ```bash git clone https://github.com/marktantongco/owl-agent-free-ai-proxy-gateway.git cd owl-agent-free-ai-proxy-gateway python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 由安装程序生成 # 以开发模式运行 ./install_owl_unified.sh --dry-run --verbose ``` ### 代码风格 - **Shell**: ShellCheck 兼容，`set -euo pipefail` - **Python**: PEP 8，类型提示优先，最大行长度 120 - **提交消息**: 传统提交格式 --- ## 🌍 社区和支持 - **GitHub 问题**: [报告错误或请求功能](https://github.com/marktantongco/owl-agent-free-ai-proxy-gateway/issues) - **讨论**: [提问，分享想法](https://github.com/marktantongco/owl-agent-free-ai-proxy-gateway/discussions) - **Wiki**: [扩展文档](https://github.com/marktantongco/owl-agent-free-ai-proxy-gateway/wiki) --- ## 🗺️ 路线图 - [ ] **v7.1**: Redis 发布/订阅网格同步，自动故障转移 - [ ] **v7.2**: 用于实时代理监控的 Web 仪表板 - [ ] **v7.3**: 自定义提供者适配器的插件系统 - [ ] **v8.0**: 用于降低延迟的 gRPC 传输层 - [ ] **v8.0**: 基于 ML 的请求路由优化 - [ ] **未来**: Kubernetes Helm 图表部署 --- ## 📄 许可证 该项目在 MIT 许可证下许可 - 有关详细信息，请参见 [LICENSE](./LICENSE) 文件。 --- <div align="center"> **由 [Mark Tantongco](https://github.com/marktantongco) 使用 🦉 构建** [⬆ 返回顶部](#-owl-agent) </div>