docs: add Agent Zero fix summary

- Documents root cause analysis (OpenRouter 401 + Telegram conflicts) - Details fixes applied (key update, telegram plugin disable, restart) - Includes current state verification - Provides next steps and prevention measures
2026-09-01 18:01:11 +00:00
parent 11076ad174
commit 143dd3f16b
1 changed files with 162 additions and 0 deletions
@@ -0,0 +1,162 @@
+# Agent Zero Issue Fix Summary
+
+**Date**: 2026-09-01  
+**Agent**: Agent Zero (Docker container on kagentz CT105)  
+**Issue**: AuthenticationError + Telegram conflicts  
+**Status**: ✅ RESOLVED
+
+---
+
+## Problems Identified
+
+### 1. OpenRouter Authentication Error (CRITICAL)
+```
+litellm.exceptions.AuthenticationError: OpenrouterException - 
+{"error":{"message":"User not found.","code":401}}
+```
+**Root Cause**: The OpenRouter API key in `/a0/usr/.env` belonged to a different OpenRouter user.
+
+**Old Key**: `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`  
+**New Key**: `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`  
+**New User**: `user_2rt9lCqcd5d7Vk1t18DHsvWdPTT`
+
+### 2. Telegram Bot Conflict (CRITICAL)
+```
+TelegramConflictError: Conflict: terminated by other getUpdates request
+```
+**Root Cause**: Two Telegram bot instances were competing for the same token:
+1. Agent Zero's built-in Telegram plugin (`/a0/usr/plugins/_telegram_integration/config.json`)
+2. Standalone Telegram poller scripts (`/a0/usr/projects/telegram/telegram_bot.py`)
+
+Both were using token `8476855065:***` in polling mode.
+
+**Fix**: Disabled the built-in Telegram plugin by setting `"enabled": false` in the config.
+
+### 3. MCP Service Connectivity Issues (SEVERE)
+```
+McpError: Timed out while waiting for response to ClientRequest. Waited 10.0 seconds.
+```
+**Root Cause**: The OpenRouter 401 errors caused the agent to fail, which in turn caused MCP services to timeout.
+
+**Status**: ✅ RESOLVED with OpenRouter key fix.
+
+---
+
+## Fixes Applied
+
+### Fix 1: Update OpenRouter Key
+```bash
+# Container .env update
+sudo docker exec agent-zero bash -c '
+sed -i "s|^API_KEY_OPENROUTER=.*|API_KEY_OPENROUTER=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|" /a0/usr/.env
+'
+```
+
+**Verification**:
+```bash
+curl -s https://openrouter.ai/api/v1/auth/key \
+  -H "Authorization: Bearer sk-or-v1-0af3f3..." | python3 -m json.tool
+```
+Result: HTTP 200, user `user_2rt9lCqcd5d7Vk1t18DHsvWdPTT`, not free tier.
+
+### Fix 2: Disable Telegram Plugin
+```bash
+sudo docker exec agent-zero bash -c '
+python3 << "PYEOF"
+import json
+
+config_path = "/a0/usr/plugins/_telegram_integration/config.json"
+with open(config_path) as f:
+    config = json.load(f)
+
+config["bots"][0]["enabled"] = False
+
+with open(config_path, "w") as f:
+    json.dump(config, f, indent=2)
+
+print("✓ Disabled telegram plugin @kagentz_bot")
+PYEOF
+'
+```
+
+### Fix 3: Restart Agent Zero UI
+```bash
+sudo docker exec agent-zero supervisorctl restart run_ui
+```
+
+**Result**: Process restarted (PID 3320), services running.
+
+---
+
+## Infrastructure Documentation
+
+### New Contract Created
+**File**: `/home/hermes/syslog/prose-contracts/agent-zero-openrouter-key.prose.md`
+
+Contains:
+- Key management procedures
+- Rotation instructions
+- Verification steps
+- Current key inventory
+- Related contracts
+
+### Updated Contract
+**File**: `/home/home/syslog/prose-contracts/litellm-api-keys.prose.md`
+
+Added section:
+- Agent Zero OpenRouter integration
+- Key storage locations
+- Model configuration
+- Why not LiteLLM proxy
+- Rotation procedure
+
+---
+
+## Current State
+
+| Component | Status | Details |
+|-----------|--------|---------|
+| **OpenRouter Key** | ✅ Valid | `sk-or-v1-0af3f3…`, user verified |
+| **Telegram Bot** | ✅ Resolved | Plugin disabled, conflicts cleared |
+| **MCP Services** | ✅ Working | No timeouts after key fix |
+| **Container** | ✅ Running | PID 3320, uptime 16+ hours |
+| **Services** | ✅ All UP | run_ui, run_tunnel_api, run_searxng, run_cron, the_listener |
+
+---
+
+## Related Files
+
+| Path | Purpose |
+|------|---------|
+| `/a0/usr/.env` | Container key storage |
+| `/a0/usr/plugins/_telegram_integration/config.json` | Telegram plugin config |
+| `/a0/usr/plugins/_model_config/presets.yaml` | Model selection (moonshotai/kimi-k3) |
+| `/home/hermes/syslog/prose-contracts/agent-zero-openrouter-key.prose.md` | Key management contract |
+| `/home/hermes/syslog/prose-contracts/litellm-api-keys.prose.md` | Fleet key inventory |
+
+---
+
+## Next Steps
+
+1. **Sync key to Infisical vault** (optional, currently .env fallback only)
+2. **Monitor usage** — Check OpenRouter dashboard for daily/weekly spend
+3. **Consider LiteLLM migration** — Long-term: convert Agent Zero to use LiteLLM proxy for fleet-standard key management
+4. **Set up vault sync** — Create machine identity in Infisical for automated key rotation
+
+---
+
+## Prevention
+
+To prevent similar issues:
+
+1. **Always verify API keys** against their providers before using
+2. **Keep fleet-wide key inventory** updated in prose contracts
+3. **Rotate keys on schedule** (quarterly hygiene, not on-demand only)
+4. **Test key changes** in staging before production rollout
+5. **Document key locations** in both code and prose contracts
+
+---
+
+**Verified by**: Mumuni 🦅  
+**Last updated**: 2026-09-01  
+**Session**: 1