OpenClaw

Overview

OpenClaw is an open-source AI agent gateway that bridges messaging apps with tools and services. In this homelab it connects a private Telegram bot to Home Assistant via the Model Context Protocol (MCP), allowing natural language control of the smart home from any device.

The LLM inference is handled by Mistral Small via Mistral AI. The bot is private — only the homelab owner’s Telegram account can interact with it.

Ports

Port	Protocol	Purpose
18789	TCP/HTTP	API Gateway & Dashboard (Multiplexed)

The service exposes an OpenAI-compatible HTTP surface on this port, allowing other local applications (like Home Assistant) to use OpenClaw’s tools and routing.

External Access

This service is only accessible on the local network (no Nginx virtual host). The Telegram bot itself is the external interface — messages are sent via the Telegram Bot API.

Access Method	Details
Telegram	`@JavierSCHomelabBot` (private, allowlist-restricted)
API Gateway	`http://<homelab.ip>:18789/v1` (protected by Bearer token)

Secrets

Credentials are managed via 1Password and injected at runtime by systemd. No secrets are stored in the Nix store.

Secret	1Password Item	Description
Telegram bot token	`op://Homelab/OpenClaw - Telegram Token/credential`	Bot API token from @BotFather
Telegram user ID	`op://Homelab/Telegram - JaviSC ID/credential`	Numeric ID used as the allowlist
Home Assistant token	`op://Homelab/Home Assistant - OpenClaw Token/credential`	Long-lived access token for MCP
Gateway auth token	`op://Homelab/OpenClaw - Gateway Token/credential`	Internal gateway authentication
Mistral API key	`op://Homelab/PicoClaw - Mistral AI Token/credential`	Key for LLM inference via Mistral AI
OpenCode Zen Token	`op://Homelab/OpenCode - Zen Token/credential`	Key for Big Pickle model via OpenCode

LLM Provider

Setting	Value
Models	Mistral Small (Primary), Big Pickle
Provider	Mistral AI, OpenCode
API Type	`openai-completions`
Cost	Pay-as-you-go
Caching	Enabled (Mistral Prompt Caching)

Tool Optimization

To minimize token usage and cost, OpenClaw is configured with a restricted toolset:

Profile: minimal (removes heavy tools like cron, browser, and exec).
Allowlist: group:messaging (Telegram interaction) and home-assistant__* (Smart home control).

This reduces the base context per request from ~15K tokens to ~4.5K tokens.

Prompt Caching

The service leverages Prompt Caching (hit rate ~97%). After the initial message in a session, only the new tokens (usually <200 tokens per reply) are billed at full input price, while the system prompt and tool schemas are reused for free or at a significant discount.

API Gateway Integration

OpenClaw can be used as an OpenAI-compatible backend. This is particularly useful for Home Assistant’s “Extended OpenAI Conversation” integration.

Field	Value
Base URL	`http://<homelab.ip>:18789/v1`
API Key	`OPENCLAW_GATEWAY_TOKEN` (from 1Password)
Model	`openclaw/default`

To force a specific model on the provider (Mistral), you can send the x-openclaw-model: mistral/mistral-small-latest header.

MCP Integration

OpenClaw connects to Home Assistant’s MCP endpoint using streamable-http transport over the local network:

http://127.0.0.1:8123/api/mcp

This allows the bot to call any Home Assistant tool (lights, switches, shopping lists, automations, etc.) in response to natural language messages.

Backup

State is backed up daily to Backblaze B2 via Restic. The backup path is:

/var/lib/openclaw

This includes the runtime config file (with secrets already stripped — they are re-injected on each start).

Troubleshooting

Bot does not respond

Symptom: Telegram messages are sent but receive no reply.

Solution:

journalctl -fu openclaw
journalctl -fu openclaw-secrets
systemctl status openclaw

Rate limit errors (429)

Symptom: Log shows ⚠️ API rate limit reached with provider: "google" or another provider.

Cause: Old log entries from a previous provider config. If current logs show the same error with provider: "nvidia", the Nemotron free tier is temporarily overloaded.

Solution: Wait a few minutes and retry. The free tier has no personal quota — rate limits are due to global demand on the shared endpoint.

MCP returns 401 Unauthorized

Symptom: Log shows 401 errors when calling Home Assistant tools.

Cause: The Home Assistant token has expired or is invalid.

Solution: Generate a new Long-Lived Access Token in Home Assistant (Profile → Security → Long-Lived Access Tokens), update the 1Password item, and restart the service:

sudo systemctl restart openclaw-secrets openclaw