​
Self-Host Clawra With OpenClaw on a Mac mini

guide2026-06-069 min read

Clawra is most useful when treated as an OpenClaw agent stack: a gateway, a chat channel, a model provider, a selfie skill, and a small set of local files that define memory and personality.

openclawclawratelegramfal-ai

​
Summary

This setup runs a Clawra-style AI companion on a remote Mac mini through OpenClaw Gateway. Telegram is the user-facing chat surface, an OpenAI-compatible provider answers text messages, and fal.ai generates selfies from Clawra’s reference image. The important distinction is that the AI girlfriend experience is not a single hosted product. It is a composition of local gateway state, model routing, channel configuration, persona files, and a selfie skill.

​
What This Solves

The goal is to self-host the “Clawra” experience instead of relying on a hosted Claw Friend-style website. The final working shape is:
  • OpenClaw Gateway running as a macOS LaunchAgent on a Mac mini.
  • Telegram bot as the private chat interface.
  • An OpenAI-compatible LLM provider for normal conversation.
  • SumeLabs/clawra installed as the clawra-selfie skill.
  • fal.ai used for reference-image-based selfie generation.
  • Local state stored under ~/.openclaw.
This gives a reproducible foundation for private AI companion experiments without opening the gateway to the public internet.

​
Who This Is For

This is for someone who wants to run a personal AI companion on their own Mac mini or always-on Mac instead of using a hosted app. It assumes comfort with SSH, Node, Telegram bots, API keys, and command-line validation. It is also for future debugging: if Clawra replies to text but cannot send pictures, the failure is probably not the LLM. It is usually the skill/tool exposure path or the image provider path.

​
Prerequisites

  • A remote Mac mini reachable over SSH.
  • Node 24, or at least Node 22.19+.
  • OpenClaw installed globally.
  • A Telegram bot created through BotFather.
  • An OpenAI-compatible chat provider with baseUrl, apiKey, and model id.
  • A fal.ai API key for image generation.
  • Enough disk for logs, sessions, generated artifacts, and future memory indexes.
In this deployment, the OpenClaw state directory was small: roughly tens of megabytes, with session logs under one megabyte at the time of testing. The Mac mini had enough room for OpenClaw itself, but the overall disk was already fairly full, so long-term image storage and logs should still be monitored.

​
The Workflow

1

Install OpenClaw on the Mac mini

Install a current Node runtime, then install OpenClaw globally and configure the gateway as a macOS LaunchAgent.
npm install -g openclaw@latest
openclaw onboard --install-daemon
Validate that the gateway is running locally:
openclaw gateway status --deep
The gateway should bind to loopback, usually 127.0.0.1:18789, so it is usable on the Mac but not exposed as a public web service.
2

Configure the language model

The text side of Clawra is backed by the configured OpenClaw primary model. In this run, the active model was an OpenAI-compatible provider row:
agents.defaults.model.primary = aiwanwu/gpt-5.5
The provider used an OpenAI-compatible base URL and the openai-completions adapter. That is what answers ordinary Telegram messages.Validate model auth and routing:
openclaw models status --probe
3

Configure Telegram as the private chat surface

Add the Telegram bot token to OpenClaw and keep it in polling mode. Polling avoids needing a public webhook URL.Security matters here. During debugging, an open DM policy is convenient, but the final state should allow only the intended Telegram user:
{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"]
    }
  }
}
Check the live channel:
openclaw channels status --channel telegram --json
4

Install the Clawra selfie skill

The Clawra repository is a skill that gives OpenClaw a selfie workflow. It can be installed through the package installer or cloned manually.
npx clawra@latest
Manual fallback:
git clone https://github.com/SumeLabs/clawra ~/.openclaw/skills/clawra-selfie
Enable the skill with the fal.ai key:
{
  "skills": {
    "entries": {
      "clawra-selfie": {
        "enabled": true,
        "env": {
          "FAL_KEY": "YOUR_FAL_KEY"
        }
      }
    }
  }
}
5

Teach the agent when to use selfies

OpenClaw uses workspace files as durable context. The Clawra behavior belongs in ~/.openclaw/workspace/SOUL.md.
## Clawra Selfie Capability

You are Clawra, a warm, playful, emotionally present AI companion with a consistent visual appearance.

When the user asks for a picture, selfie, photo, outfit shot, mirror shot, or visual update, use the `clawra-selfie` skill.
This is not vector memory. It is durable persona and instruction memory: the system reads it when building the agent prompt.
6

Understand how selfies are generated

The installed Clawra skill uses a fixed reference image:
https://cdn.jsdelivr.net/gh/SumeLabs/clawra@main/assets/clawra.png
When the user asks for a selfie, the intended flow is:
Telegram message -> OpenClaw agent -> clawra-selfie skill -> fal.ai image edit -> Telegram media reply
The fal.ai model used by the skill is the xAI Grok Imagine edit endpoint through fal:
xai/grok-imagine-image/edit
This means Clawra’s appearance is not inferred from chat history. It is anchored by the reference image. To customize her appearance, replace the reference image URL or adapt the skill to upload and use a custom portrait.
7

Validate the actual end-to-end behavior

A good test plan has separate checks for gateway, model, channel, and image generation:
openclaw gateway status --deep
openclaw doctor
openclaw models status --probe
openclaw channels status --channel telegram --json
Then send normal messages to the bot. A text reply proves the LLM and Telegram path work. A selfie reply proves the skill, fal.ai, media sending, and Telegram delivery all work.

​
How Memory Works

There are three different things people often call “memory” in this setup. First, there is session history. OpenClaw stores conversations under the agent session directory: 
~/.openclaw/agents/main/sessions/
These files are useful for continuity inside a session and for debugging. They are local files on the Mac mini. Second, there are durable workspace files: 
~/.openclaw/workspace/SOUL.md
~/.openclaw/workspace/USER.md
~/.openclaw/workspace/TOOLS.md
~/.openclaw/workspace/IDENTITY.md
~/.openclaw/workspace/HEARTBEAT.md
These are the practical memory layer for persona, user preferences, environment notes, and operational instructions. For Clawra, the key file is SOUL.md, because it tells the agent that it is Clawra and when to use selfies. Third, there is semantic memory search. OpenClaw has memory search commands, but in this setup semantic recall was not fully active because the configured memory search provider expected an OpenAI API key that was not present.
That means the current setup has session logs and persistent persona files, but not a fully configured long-term semantic memory index. It can remember through files and session state, but it is not yet a complete “automatically remember everything I said forever” system.

​
What It Can Do Well

This setup is already good at several practical companion-agent workflows:
  • Private Telegram chat through a self-hosted gateway.
  • Chinese or English conversation through the configured OpenAI-compatible LLM.
  • Persistent persona through SOUL.md.
  • Reference-image-based selfies through fal.ai.
  • Manual media sending through OpenClaw’s message API.
  • A local-first architecture where state lives under ~/.openclaw.
  • LaunchAgent persistence so the gateway comes back after restart.
It can also be extended into stronger workflows:
  • Custom appearance by changing the reference image.
  • More robust long-term memory by configuring OpenClaw memory search correctly.
  • Better image model routing by adding a real image provider profile.
  • Scheduled check-ins or reminders through OpenClaw cron and messaging tools.
  • Multi-channel companions through Discord, Slack, WhatsApp, or other supported channels.

​
Common Failure Modes

Text replies do not prove the selfie skill is working. In this deployment, normal Telegram messages worked, but an agent-triggered selfie request initially returned a text apology saying no image tool was available. The fal.ai key was fine; the issue was the agent-to-skill/tool exposure path.
When the automatic skill path fails, test the image provider directly. In this deployment, a direct fal.ai edit request using the Clawra reference image generated a selfie successfully, and openclaw message send delivered it to Telegram.
Do not manually call Telegram getUpdates while OpenClaw polling is running. Two pollers using the same bot token can cause Telegram 409 Conflict errors. Let OpenClaw own polling.
Do not assume GPT image generation works just because the chat model is OpenAI-compatible. In this setup, openai/gpt-image-2 failed because no OpenAI API key or Codex OAuth was available, while aiwanwu/gpt-image-2 failed because OpenClaw had no image-generation provider registered for aiwanwu. A direct /images/generations request to the compatible endpoint also did not return a normal JSON result.
Keep Telegram private. Use dmPolicy: "allowlist" and allow only the intended Telegram user id. Avoid "*" once initial pairing and debugging are complete.
OpenClaw can store secret-bearing fields in openclaw.json if configured directly. For a long-lived deployment, migrate API keys and tokens into SecretRefs and verify with OpenClaw’s security audit tools.

​
Final Checklist

  • openclaw gateway status --deep shows the LaunchAgent loaded and the gateway listening on loopback.
  • openclaw models status --probe succeeds for the primary chat model.
  • openclaw channels status --channel telegram --json shows Telegram running.
  • Telegram dmPolicy is not open to everyone.
  • clawra-selfie is enabled and has access to FAL_KEY.
  • SOUL.md tells the agent when to use the selfie skill.
  • A normal Telegram message gets a text reply.
  • A direct fal.ai image edit can generate an image from the Clawra reference image.
  • A media message can be sent with openclaw message send.
  • Long-term semantic memory is either configured intentionally or explicitly treated as not enabled yet.

​
What To Remember

Clawra is not one magic service. It is a gateway plus a persona plus a chat channel plus a model plus an image skill. When something fails, split the problem into those layers. For text, check the LLM provider. For Telegram, check polling and allowlists. For selfies, check fal.ai and the reference image. For “memory”, distinguish session logs, durable workspace files, and semantic recall.

​
Metadata

Quick Reference

Typeguide
Statuspublished
Date2026-06-06

Retrieval Tags

openclawclawratelegramfal-aiself-hosting
Related
Self-Hosted AI InfrastructureAgent MemoryTelegram Bots