githubinferredactive
openclaw-model-bridge
provenance:github:bisdom-cell/openclaw-model-bridge
WHAT THIS AGENT DOES
The openclaw-model-bridge connects any large language model to the OpenClaw platform, enabling multimodal interactions like image understanding. It's designed for developers and researchers who want to integrate powerful AI models into applications, particularly on Mac Mini hardware. This middleware provides a production-ready environment with real-time conversation handling, multimodal support, and service level objective monitoring. It supports features like custom tool injection, knowledge base integration, and automated paper monitoring. The system also includes a robust architecture for managing data flow and ensuring reliable performance. Users can leverage this bridge to build sophisticated AI-powered applications with minimal setup and ongoing maintenance.
PROBLEM IT SOLVES
This agent solves the challenge of integrating complex large language models, especially those requiring multimodal capabilities, into production environments. Instead of manually configuring and managing these integrations, developers can use openclaw-model-bridge to quickly and reliably connect their models to OpenClaw, streamlining development and deployment.
CAPABILITIES & CONSTRAINTS
TECH & STACK
pythonllmopenclawmac-minimultimodalragembeddingsknowledge-base
README
# openclaw-model-bridge
> Connect any LLM to [OpenClaw](https://github.com/openclaw/openclaw) — production-tested middleware with multimodal support on Mac Mini.
> 将任意大模型接入 OpenClaw — 支持多模态（图片理解）的生产中间件，运行于 Mac Mini。
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[]()
[-blue.svg)]()
[]()
[]()
## Architecture / 系统架构
<details>
<summary>Text version / 文本版本</summary>
```
┌─────────────────────────────────────────────────────────────────┐
│ 用户层 (WhatsApp) │
│ 文本 / 图片 / 语音消息 │
└────────────────────────┬────────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────────┐
│ ① 核心数据通路（实时对话 + 多模态 + SLO 监控） │
│ │
│ WhatsApp ←→ Gateway (:18789) ←→ Proxy (:5002) ←→ Adapter (:5001) ←→ Remote GPU │
│ [launchd] [策略过滤+监控] [认证+Fallback] [Qwen3-235B] │
│ [媒体存储] [图片base64注入] [VL模型路由] [Qwen2.5-VL-72B] │
│ [自定义工具注入] [→Gemini降级] │
│ data_clean(清洗) │
│ search_kb(混合检索) │
│ [SLO指标采集] │
│ 延迟p95/错误分类 │
│ 工具成功率/降级率 │
│ │
│ search_kb流程：用户问论文 → PA调search_kb → Proxy拦截 │
│ → ①语义搜索(embedding cosine) + ②关键词补充 │
│ → 支持source过滤(arxiv/hf/hn等) + 时间过滤(recent_hours) │
│ → 结果注入对话 → followup LLM调用 → 自然语言回答 │
└──────────────────┬──────────────────┬───────────────────────────┘
│ │
┌──────────────────▼──────────────────▼───────────────────────────┐
│ ② 知识库 + 本地 AI（零 API 调用） │
│ │
│ KB Notes + Sources ──→ kb_embed.py ──→ 本地 Embedding (384维) │
│ (sentence-transformers, 每4h增量) │
│ ↓ │
│ ~/.kb/text_index/ ──→ kb_rag.py (RAG) │
│ │
│ 媒体文件 ──→ mm_index.py ──→ Gemini Embedding 2 (768维) │
│ ↓ │
│ ~/.kb/mm_index/ ──→ mm_search.py (语义搜索) │
└──────────────────────────────────────────────────────────────────┘
│
┌──────────────────▼──────────────────────────────────────────────┐
│ ③ 定时任务层（32 个 system cron jobs，28 active） │
│ │
│ 论文监控矩阵（5源）： │
│ ArXiv(每3h) + HF Papers(10:00) + S2(11:00) │
│ + DBLP(12:00) + ACL(09:30) ──→ KB + WhatsApp推送 │
│ 每3h HN热帖抓取 ──→ KB + WhatsApp推送 │
│ 每天×3 货代Watcher ──→ LLM分析 + KB + WhatsApp推送 │
│ 每天 OpenClaw Releases ──→ LLM摘要 + KB + WhatsApp推送 │
│ 每小时 Issues监控 ──→ KB + WhatsApp推送 │
│ 每天 KB每日摘要 / 晚间整理 / 智能去重 │
│ 每4h KB 向量索引（本地 embedding） │
│ 每2h 多媒体索引（Gemini Embedding 2） │
│ 每天 对话质量日报 / Token用量日报 │
│ 每周 KB深度回顾 / 健康周报 / AI趋势报告 │
│ 每天 Gateway state 备份（外挂 SSD） │
│ 每30m WhatsApp 保活 │
│ 每4h Job Watchdog（元监控告警） │
│ 每2m auto_deploy（Git→运行时自动同步） │
└──────────────────────────────────────────────────────────────────┘
│
┌──────────────────▼──────────────────────────────────────────────┐
│ ④ 控制平面（SLO + 阈值中心化 + 故障快照 + 19项体检 + CI） │
│ │
│ Claude Code → claude/分支 → PR → main → auto_deploy → Mac Mini │
│ config.yaml: 统一阈值配置（70+参数，9个分区） │
│ SLO 5指标: 延迟p95<30s / 工具成功>95% / 降级<5% │
│ 超时<3% / 自动恢复>90% │
│ auto_deploy: 文件同步(35个) + 漂移检测 + 按需restart │
│ preflight: 19项检查（单测+注册表+语法+部署+安全+E2E+SLO） │
│ 故障快照: 连续错误→自动采集日志+状态→~/.kb/incidents/ │
│ pre-commit: API key/手机号泄漏+语法检查 │
│ GitHub Actions CI: 9套单测+注册表+配置校验+安全扫描+bandit │
└──────────────────────────────────────────────────────────────────┘
│
┌──────────────────▼──────────────────────────────────────────────┐
│ ⑤ 三方共享状态（~/.kb/status.json 实时同步） │
│ │
│ 用户(WhatsApp) ←→ PA ←→ status.json ←→ Claude Code ←→ Cron │
│ 反馈+决策 写入 优先级/反馈 读/写 自动更新 │
│ 健康/SLO/焦点 │
│ │
│ 宪法：用户专业深度 + Claude Code设计部署 + OpenClaw数据复利 │
│ 三者合一 = 有生命的闭环系统 │
└──────────────────────────────────────────────────────────────────┘
```
</details>
| Component | Port | Files | Role |
|-----------|------|-------|------|
| OpenClaw Gateway | 18789 | npm global | WhatsApp integration, media storage, tool execution, session management |
| Tool Proxy | 5002 | `tool_proxy.py` + `proxy_filters.py` | Tool filtering (24→12), **custom tools** (data_clean + search_kb hybrid search), **image base64 injection**, SSE conversion, truncation, token monitoring, **SLO metrics collection**, **incident snapshots** |
| Adapter | 5001 | `adapter.py` | Multi-provider forwarding, auth, **multimodal routing** (text→Qwen3, image→Qwen2.5-VL), fallback degradation |
| Config Center | — | `config.yaml` + `config_loader.py` | **V32** Centralized thresholds (70+ params, 9 sections: SLO/proxy/tokens/alerts/routing/truncation/watchdog/incidents/jobs) |
| SLO Checker | — | `slo_checker.py` | **V32** SLO compliance — 5 metrics (latency p95, tool success rate, degradation rate, timeout rate, auto-recovery rate) |
| Local Embedding | — | `local_embed.py` | sentence-transformers (384-dim, 50+ languages), zero API calls |
| Remote GPU | — | hkagentx.hkopenlab.com | Qwen3-235B (text, 262K context) + **Qwen2.5-VL-72B** (vision) |
## Quick Start
```bash
# Core services — no third-party dependencies (stdlib only)
export REMOTE_API_KEY="your-key-here"
bash restart.sh
curl http://localhost:5002/health
# → {"ok":true,"proxy":true,"adapter":true}
# Optional: KB RAG semantic search
pip3 install -r requirements-rag.txt
python3 kb_embed.py && python3 kb_rag.py "AI papers"
# Optional: Multimodal memory (images/audio/video)
export GEMINI_API_KEY="your-gemini-key"
pip3 install -r requirements-mm.txt
python3 mm_index.py && python3 mm_search.py "cat photos"
```
## Project Structure
### Core Services
| File | Description |
|------|-------------|
| `tool_proxy.py` | HTTP layer — request/response routing, **custom tool execution** (data_clean + search_kb), **media injection**, followup
[truncated…]PUBLIC HISTORY
First discoveredMar 29, 2026
IDENTITY
inferred
Identity inferred from code signals. No PROVENANCE.yml found.
Is this yours? Claim it →METADATA
platformgithub
first seenFeb 26, 2026
last updatedMar 28, 2026
last crawled1 months ago
version—
README BADGE
Add to your README:
