feat(openclaw,infra): optimize token usage with GLM-5.3-Flash and add Garmin MCP integration
- Migrate OpenClaw primary model to z-ai/glm-5.3-flash across conductor, heartbeat, subagents, and vision - Configure deepseek-v4.1-flash and qwen3.8-flash as fallback models; retire claude-3.7-sonnet and deepseek-v4-pro - Decouple heartbeat target to prevent active session context amplification and token bleed - Add Garmin Connect MCP integration, secret unpacking, and Elite Strength Coach SOUL protocol - Add ADR 0001 documenting hybrid tool search and subagent architecture - Update Authentik configuration, theme styles, and Terraform state - Add Grafana dashboard for Taupi fan monitoring and update Velero secrets - Bump knowledge-wiki submodule pointer
This commit is contained in:
Moritz Graf
@@ -0,0 +1,125 @@
|
||||
---
|
||||
status: "accepted"
|
||||
date: 2026-09-12
|
||||
decision-makers: ["Moritz Graf", "Antigravity"]
|
||||
consulted: []
|
||||
informed: []
|
||||
---
|
||||
|
||||
# ADR 0001: Hybrid MCP Tool Search and Subagent Delegation for AI Agents
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
OpenClaw operates as the personal AI concierge for the Graf family, communicating primarily via Telegram and web interfaces. It integrates external systems via the Model Context Protocol (MCP) (e.g., Home Assistant, Prometheus, Spotify, weather, shopping).
|
||||
|
||||
When integrating comprehensive domain services like **Garmin Connect** via [`Taxuspt/garmin_mcp`](https://github.com/Taxuspt/garmin_mcp), the server exposes **148 distinct tools** spanning activity analysis, workout builders, physiological trends, sleep, stress, HRV, and gear tracking.
|
||||
|
||||
In standard MCP implementations, all tool schemas are transmitted in the LLM's `tools` array on *every single request turn*. For 148 tools, this imposes a **~25,000–30,000 token tax per turn** before a single word of user prompt is evaluated. This creates severe issues:
|
||||
1. **Severe Token & Cost Bloat**: Inflates inference costs on OpenRouter across thousands of daily family turns.
|
||||
2. **Turn Latency & Degradation**: Slows down response times on mobile Telegram and impairs the reasoning accuracy of fast conductor models (e.g. `deepseek-v4.1-flash`) due to tool schema noise.
|
||||
3. **Imbalance for Simple Checks**: A simple query like *"Wie war mein Schlaf?"* should not require dragging 148 tool definitions into context or, conversely, incurring the multi-second startup latency of a full subagent session.
|
||||
|
||||
How do we grant OpenClaw full access to large, complex MCP tool catalogs without polluting everyday conversational context?
|
||||
|
||||
---
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
* **Token Economics**: Minimize idle token overhead on routine conversational turns.
|
||||
* **Low Latency**: Provide instant answers for routine, single-step lookups.
|
||||
* **Complex Multi-Step Capabilities**: Enable autonomous, deep reasoning for tasks like workout generation, periodization, and multi-source research without cluttering the primary conversation transcript.
|
||||
* **Protocol Standards**: Adhere to upstream MCP standards rather than writing fragile, non-standard CLI wrappers for every API.
|
||||
* **Architectural Consistency**: Establish an extensible pattern that can later be applied to refactor other domains (e.g. Supermarket shopping, Jellyfin media, and Regensburg Stadtrat local news research).
|
||||
|
||||
---
|
||||
|
||||
## Considered Options
|
||||
|
||||
1. **Option 1: Global Eager MCP Registration**
|
||||
* Register all 148 tools directly under `mcp.servers`.
|
||||
* *Drawback*: Unacceptable ~30k token tax on every message; high cost and latency.
|
||||
|
||||
2. **Option 2: Pure CLI / Script Wrapper Skill**
|
||||
* Avoid MCP entirely; write custom Python CLI scripts in `mop-skills` executed via `bash`.
|
||||
* *Drawback*: Re-invents the wheel, ignores the 1,150-star community MCP server, requires maintaining hundreds of lines of bespoke CLI parsing code.
|
||||
|
||||
3. **Option 3: Subagent Delegation Only**
|
||||
* Hide all domain tools from the main agent and mandate that *every* query spawns a subagent via `sessions_spawn`.
|
||||
* *Drawback*: Adds unnecessary latency (2–4 seconds) and session overhead for trivial questions like *"Wie hoch ist meine Body Battery?"*.
|
||||
|
||||
4. **Option 4: Hybrid Tool Search + Subagent Delegation (Selected)**
|
||||
* Enable OpenClaw's native **Tool Search** (`tools.toolSearch.mode: "directory"`) for the main agent so large tool catalogs are deferred behind lightweight search/describe/call operations (~600 tokens).
|
||||
* Empower the main conductor to dynamically decide:
|
||||
* Execute directly via Tool Search for fast, single-step queries.
|
||||
* Delegate to an isolated subagent (`sessions_spawn`) for deep, multi-step, stateful reasoning.
|
||||
|
||||
---
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
Chosen Option: **Option 4: Hybrid Tool Search + Subagent Delegation**.
|
||||
|
||||
### 1. Dual-Path Architecture
|
||||
|
||||
```
|
||||
User Query (Telegram)
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────┐
|
||||
│ OpenClaw Main Conductor │
|
||||
│ (DeepSeek v4.1 Flash) │
|
||||
└───────────────────┬────────────────────┘
|
||||
│
|
||||
Is this a deep/multi-step task?
|
||||
┌────────────┴────────────┐
|
||||
│ NO │ YES
|
||||
▼ ▼
|
||||
┌───────────────┐ ┌─────────────────────────┐
|
||||
│ Direct Tool │ │ Subagent Delegation │
|
||||
│ Search │ │ (sessions_spawn) │
|
||||
├───────────────┤ ├─────────────────────────┤
|
||||
│ • tool_search │ │ • Dedicated Context │
|
||||
│ • tool_call │ │ • Full Tool Access │
|
||||
│ • Single Turn │ │ • Multi-Step Reasoning │
|
||||
└───────┬───────┘ └────────────┬────────────┘
|
||||
│ │
|
||||
└──────────────┬──────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ Taxuspt/garmin_mcp (148 Tools)│
|
||||
│ Garmin Connect Cloud API │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. Main Conductor Routing Heuristic
|
||||
|
||||
The main conductor is guided by explicit system prompt rules:
|
||||
|
||||
| Query Type | Routing Path | Examples |
|
||||
| :--- | :--- | :--- |
|
||||
| **Simple Vitals & Lookups** | **Direct Tool Search** | • *"Wie war mein Schlaf letzte Nacht?"*<br>• *"Wie ist meine Body Battery?"*<br>• *"Was habe ich gestern trainiert?"* |
|
||||
| **Deep Analysis & Creation** | **Subagent Delegation (`sessions_spawn`)** | • *"Erstelle mir ein 45-minütiges Oberkörper-Superset-Workout für heute auf meiner Uhr."*<br>• *"Analysiere mein Krafttraining der letzten 3 Wochen auf Progressive Overload und plane die nächste Woche."*<br>• *"Erstelle ein Periodisierungskonzept für den nächsten Monat."* |
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
* **98% Token Reduction on Idle Turns**: The tool catalog is deferred behind OpenClaw's native Tool Search, dropping tool schema overhead from ~30,000 tokens to ~600 tokens.
|
||||
* **Instant Answers for Vitals**: Quick checks are answered in a single turn without waiting for subagent spin-up.
|
||||
* **Isolated Deep Reasoning**: Heavy multi-turn planning and JSON compilation occur inside temporary subagents, keeping the main Telegram conversation transcript lightweight and readable.
|
||||
* **Standard-Compliant**: Uses standard upstream MCP (`Taxuspt/garmin_mcp`) and standard OpenClaw features (`tools.toolSearch`, `sessions_spawn`).
|
||||
|
||||
### Negative & Mitigations
|
||||
* **Two-Step Tool Search Latency**: For the first direct lookup of a tool, OpenClaw performs a search step before calling the tool.
|
||||
* *Mitigation*: OpenClaw's `directory` mode caches known tool descriptors and allows direct calls when the exact tool name is known.
|
||||
* **Model Prompt Instruction**: Requires clear guidelines in the system prompt so the conductor consistently knows when to delegate vs. query directly.
|
||||
|
||||
---
|
||||
|
||||
## Future Roadmap: Monorepo Refactoring Blueprint
|
||||
|
||||
This Hybrid MCP architecture serves as the official template for future refactorings in `infrapuzzle`:
|
||||
1. **Shopping & Supermarket Deals**: Migrate current static MCP tools behind Tool Search; delegate multi-store price comparisons and recipe cart generation to a shopping subagent.
|
||||
2. **Jellyfin & Media Management**: Keep playback/resume queries direct; delegate complex media recommendations and library reorganizations to a media subagent.
|
||||
3. **Local News & Stadtrat Research**: Provide direct search for council dates; delegate deep legislative research, PDF document extraction, and meeting summarization to an isolated Stadtrat research subagent.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Architecture Decision Records (ADRs)
|
||||
|
||||
This directory documents the key architectural decisions made within the **Infrapuzzle** monorepo and its associated workloads (Kubernetes, OpenClaw AI agent, networking, DNS, and smart home systems).
|
||||
|
||||
We follow the [Markdown Architectural Decision Records (MADR)](https://adr.github.io/madr/) format to capture intentional technical decisions, their context, considered options, trade-offs, and consequences.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Record Index
|
||||
|
||||
| ADR | Title | Status | Date | Area |
|
||||
| :--- | :--- | :---: | :---: | :--- |
|
||||
| [**0001**](0001-hybrid-mcp-tool-search-and-subagents.md) | **Hybrid MCP Tool Search and Subagent Delegation for AI Agents** | `accepted` | 2026-09-12 | OpenClaw / AI / MCP |
|
||||
|
||||
---
|
||||
|
||||
## ✍️ How to Create a New ADR
|
||||
|
||||
1. Copy the template structure into a new numbered markdown file:
|
||||
```bash
|
||||
docs/adr/000X-short-title-in-kebab-case.md
|
||||
```
|
||||
2. Include the YAML frontmatter:
|
||||
```yaml
|
||||
---
|
||||
status: "proposed | accepted | superseded | deprecated"
|
||||
date: YYYY-MM-DD
|
||||
decision-makers: ["Moritz Graf", "Antigravity"]
|
||||
consulted: []
|
||||
informed: []
|
||||
---
|
||||
```
|
||||
3. Clearly define:
|
||||
- **Context & Problem Statement** (Why was this decision needed?)
|
||||
- **Decision Drivers** (Constraints, costs, token limits, latency, maintainability)
|
||||
- **Considered Options** (Alternatives evaluated)
|
||||
- **Decision Outcome** (Chosen path with justification)
|
||||
- **Consequences** (Positive effects, negative trade-offs, follow-up actions)
|
||||
4. Add the new record to the table in this `README.md`.
|
||||
Reference in New Issue
Block a user