Skip to content

Deprecated — Migrated to LLMOPS-0001 on 2026-05-02 per ADR-0047. This source file is retained as a reference; the canonical content is in LLMOPS-0001.

ADR-0029 — OpenClaw Adoption as Self-Hosted AI Gateway

Field Value
Status Accepted
Date 2026-04-12
Author Ben Peries
Phases Phase 3 (deployment), Phase 6 (multi-tenant persona queries)
ADO WI #150

Context

Archon Phase 3 requires a self-hosted AI gateway to serve conversational AI capabilities via Telegram without routing queries through external cloud APIs directly from the host. The platform has an existing Ollama deployment on the CanEast AI Node node (caneast-site1-node1 equivalent; REDACTED) and access to cloud inference APIs (DashScope/Bailian, Groq).

Three options were evaluated:

Option 1 — Direct API calls from Telegram bot code

A custom Python/Node.js bot that calls inference APIs directly. No gateway layer; secrets embedded in bot process or environment.

  • Fit: Maximum control but requires maintaining provider-switching logic, retry handling, and model fallback in custom code.
  • Security: Prompt injection risk is entirely in application code — no framework-level mitigations.
  • Maintenance: High — provider API changes require code changes.

Option 2 — OpenClaw (self-hosted AI gateway)

OpenClaw is an open-source, self-hosted AI gateway providing: - Telegram bot front-end with multi-provider model routing - Provider fallback chains (primary → fallback[0] → fallback[1] → ...) - openclaw.json configuration for model, gateway, and agent settings - Docker-based deployment with bind-mount config and secrets via env vars - No persistent state in the container — config lives on the host

  • Fit: Purpose-built for Telegram + multi-provider AI; aligns with homelab's Docker-first deployment model.
  • Security: Input/output handled by the container; prompt injection risk managed at the gateway layer via sandboxed tool execution.
  • Maintenance: Moderate — config-driven; provider changes require only openclaw.json updates, not code changes.

Option 3 — Managed AI gateway (e.g., LiteLLM, PortKey)

Cloud-managed or self-hosted LiteLLM proxy. Provides OpenAI-compatible API across many providers.

  • Fit: Heavy infrastructure for a homelab Telegram bot; not Telegram-native.
  • Security: Adds another service boundary; no advantage over OpenClaw for this use case.

Decision

Adopt OpenClaw as the self-hosted AI gateway for Archon conversational agents. Initial deployment: openclaw-archonagent1 (@cae_archonagent_bot) on the CanEast AI Node node.

Rationale:

  1. OpenClaw is the only purpose-built Telegram + multi-provider AI gateway evaluated — purpose fit reduces custom code surface area.
  2. Config-driven model routing (openclaw.json) decouples provider changes from code changes — updating primary model requires a config file swap, not a redeployment.
  3. Secrets are never written to disk — all API keys injected via ${VAR_NAME} at runtime via Infisical; container runs with user: 1000:1000.
  4. Image digest pinning (WI #151) and Grype scan before upgrades mitigate supply chain risk consistent with ADR-0003.
  5. Multi-bot architecture is supported: openclaw-archonagent1 (conversational) and openclaw-sentinel (alerting) run as independent containers with separate Telegram bot tokens.

Prompt Injection Risk Assessment

OpenClaw exposes a Telegram interface that accepts free-text user input and passes it to an LLM. This creates a prompt injection attack surface.

Threat model

Threat Likelihood Impact Mitigation
Telegram user attempts jailbreak via crafted message Low (allowlist enforced) Medium TELEGRAM_ALLOWED_USERS restricts to known numeric user IDs; no public bot
Malicious content in external documents loaded by agent Low (no external fetch configured) High Default config has no web-fetch or file-upload tools enabled
Model exfiltrates secrets via crafted tool call Low (no secrets in model context) High API keys injected as env vars, never passed to model context
Adversarial model provider (compromised bailian endpoint) Very low High Provider URL pinned in config; digest-pinned container limits supply chain exposure

Mitigations in place

  • TELEGRAM_ALLOWED_USERS allowlist — only authorized numeric Telegram user IDs can interact with the bot. Not a public endpoint.
  • API keys are runtime env vars (${VAR_NAME}) — never appear in openclaw.json, never in model context, never in logs.
  • Container runs as user: 1000:1000 — no root process.
  • Image pinned to digest (ADR-0003 / WI #151) — supply chain integrity.
  • No external tool access configured in initial deployment.

Residual risk

Accepted. The bot is private (allowlist-only), has no web-fetch tools, and secrets never enter the model context. A future ADR is required before adding web-fetch, code execution, or any tool that exposes the host filesystem or internal network to model-directed calls.

Constraints

  • Secrets via Infisical only (ADR-0002). No API keys in openclaw.json. All keys via ${VAR_NAME} env var syntax resolved at runtime.
  • Image digest pinned before production deployment. Grype scan required before upgrading to a new digest. Image: ghcr.io/openclaw/openclaw.
  • openclaw.json on Windows host only — C:\homelab\openclaw-archonagent1\data\openclaw.json. Never committed to git. openclaw.json.example is the committed template.
  • Tool access: No external web-fetch, file-upload, or code-execution tools without a superseding ADR documenting the expanded threat model.
  • Two-bot architecture: openclaw-archonagent1 (conversational, @cae_archonagent_bot) and openclaw-sentinel (alerting, @caneast-alertbot) are separate containers. openclaw-sentinel deployment blocked pending this ADR merge (WI #150).

Consequences

Positive

  • Conversational AI available via Telegram without custom bot code.
  • Provider fallback chain means model outages are transparent to users.
  • Config-driven model upgrades — qwen3.6-plus-2026-04-02 upgrade (WI #148) required only a config change, not a code change.
  • Foundation for Phase 6 multi-persona scenario queries via separate bot tokens.

Negative

  • OpenClaw is a relatively new project — upstream API stability not guaranteed.
  • Windows host bind mounts (C:\homelab\...) create a platform dependency: config must be managed manually on the Windows host, not via Ansible.
  • Image digest pinning requires manual update procedure before each upgrade.

Neutral

  • WI #150 (this ADR) unblocks openclaw-sentinel deployment.
  • ccagnt-purpleteam remains separately gated by ADR-0027 (not related).

References

  • OpenClaw GitHub
  • ADR-0002 — Infisical as secrets manager
  • ADR-0003 — Grype over Trivy; image digest pinning
  • WI #142 — OpenClaw initial deployment (archon-archonagent1 multi-provider config)
  • WI #148 — Bailian/qwen3.6-plus upgrade
  • WI #149 — OpenClaw configuration reference page
  • WI #150 — This ADR
  • WI #151 — Image digest pinning + Grype scan
  • docs/reference/openclaw-config.md — OpenClaw configuration reference