Cora 🪸

Primer

The pieces, in plain English.

Here's every tool this guide mentions, what it is, and how I use it. Each one has a tag for anyone building their own: get it, build your own or optional.

MCP shows up everywhere below. It's a standard plug that lets an agent use another service's tools. Cotrugli and my heat pumps each expose an MCP server, and Cora plugs into both.

The wiring

One gateway, one bot, everything local.

OpenClaw runs a single gateway process under launchd. Telegram is the only front door. Because the gateway sits on a real Mac instead of a cloud VM, Cora can read the things that only exist on Apple hardware: Messages, Photos, Voice Memos, Reminders and Contacts.

A day in Cora's life

What she does while I'm not looking.

Times Pacific. Plus weekly: skill-collection review, and a Tuesday 6 AM job where Cora upgrades her own fantasy-sports CLI and verifies it with doctor --live. Almost every run ends in NO_REPLY, so I only hear about it when something changed.

The fun part

Things I didn't expect an agent to be good at.

The data lake underneath

What Cotrugli does so Cora doesn't have to.

Cotrugli runs on its own all day: collectors on the Mac push my messages, photos, voice memos, contacts and files to it, and my phone streams location. It processes everything the moment it lands, so when Cora asks “where was I Tuesday?” or “what did that pharmacy label say?” the answer is already sitting there. If you don't have a data lake, this is the list of jobs you'd hand your agent instead, one scheduled script at a time.

Still in progress: a daily narrative of our life and a small AI newsroom that writes articles from all this data. Cora handles the judgment calls Cotrugli leaves for a human, like confirming a medication or merging two contacts, and the triage jobs on the Mac still decide what's worth writing down.

Key decisions

What I chose, and why.

Build your own

Build your own in an evening.

You need a Mac that can stay on (an old laptop is perfect), a Telegram account, and a ChatGPT plan or an API key.

Set up OpenClaw on this Mac as an always-on personal agent I talk to on Telegram.
Follow John Wulff's Cora Field Guide (I'll paste the setup steps below) and:
- run every step yourself; stop only for things I must do (BotFather, ChatGPT
  sign-in, macOS permission prompts, pairing from my phone)
- keep every secret in a chmod 600 file under ~/.secrets, referenced from config
- bind the gateway to loopback, DMs allowlisted to me, groups mention-only
- back up ~/.openclaw/openclaw.json before every config change
- verify with openclaw doctor, openclaw security audit, and a real Telegram reply
- then interview me to write IDENTITY.md, SOUL.md, USER.md and a small HEARTBEAT.md,
  and commit the workspace to git
Ask before installing anything not in the guide.

What the session will run

1. Make the Mac an always-on server

   Copy

   sudo pmset -a sleep 0 disksleep 0 autorestart 1

   Keep FileVault and the login password on. After a power cut, log in once so the agent's background service starts again. If you want to manage the Mac from another computer, turn on Remote Login under System Settings → General → Sharing and use SSH keys only.

2. Install Homebrew, Node and OpenClaw

   Copy

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   brew install node git gh
   npm install -g openclaw@latest --allow-scripts=openclaw
   openclaw --version

   Check npm --version first. On npm 11.15 or earlier, drop --allow-scripts=openclaw. Newer npm blocks OpenClaw's install scripts without it.

3. Create the Telegram bot

   In Telegram, message @BotFather: /newbot, pick a name and a username ending in _bot, and copy the token. Then under /mybots → Bot Settings set Group Privacy: off (so it can read groups) and Allow Groups: off (so strangers can't add it). Flip Allow Groups on only while you add it to a group.

4. Put secrets in files

   Copy the bot token to your clipboard, then:

   Copy

   mkdir -p ~/.secrets && chmod 700 ~/.secrets
   pbpaste > ~/.secrets/telegram-bot-token && chmod 600 ~/.secrets/telegram-bot-token
   pbcopy < /dev/null

   Do the same for any API keys later (openai-api-key, anthropic-api-key, brave-api-key).

5. Run onboarding with ChatGPT sign-in

   Copy

   openclaw onboard --auth-choice openai --agent-name <your-agent-name>

   It walks you through the model, gateway, workspace and Telegram. When it asks for the bot token, paste it once. The next step moves it into the secrets file.

6. Point the token at the file and lock things down

   Copy

   openclaw config set secrets.providers.telegramtoken --provider-source file \
     --provider-path ~/.secrets/telegram-bot-token --provider-mode singleValue
   openclaw config set channels.telegram.botToken --ref-provider telegramtoken \
     --ref-source file --ref-id value
   openclaw config set gateway.bind loopback
   openclaw config set channels.telegram.groups '{"*":{"requireMention":true}}' --strict-json

7. Install the service and pair yourself

   Copy

   openclaw daemon install
   openclaw doctor --fix
   openclaw security audit

   DM your bot. It replies with a pairing code and your Telegram user ID, so write the ID down. Approve the code, then close the door so nobody else can ask:

   Copy

   openclaw pairing list
   openclaw pairing approve <code>
   openclaw config set channels.telegram.allowFrom '["<your-telegram-user-id>"]' --strict-json
   openclaw config set channels.telegram.dmPolicy allowlist

8. Give it a personality and version it

   The workspace files are the agent. IDENTITY.md is its name and vibe, SOUL.md its values, USER.md is about you, AGENTS.md holds the rules, and HEARTBEAT.md is the checklist it runs every 30 minutes.

   Copy

   cd ~/.openclaw/workspace
   git init && git add -A && git commit -m "Birth"
   gh auth login
   gh repo create <your-agent-name>-workspace --private --source . --push
   open -e IDENTITY.md SOUL.md USER.md HEARTBEAT.md

   If this is the Mac's first commit, git will ask who you are. Set it once with git config --global user.name "Your Name" and git config --global user.email you@example.com.

   That private GitHub repo is your off-machine backup. Run git status before each push so nothing you didn't mean to share goes up. Your secrets live in ~/.secrets, outside the workspace, so they never get committed.

   Start HEARTBEAT.md small. Mine began as “check email, tell me if anything is urgent.”

9. Add a fallback model chain

   Optional, and it needs pay-as-you-go API keys from OpenAI and Anthropic saved as files in step 4. Merge this into ~/.openclaw/openclaw.json. It defines the two metered providers, points them at your key files, and puts them behind your ChatGPT plan:

   Copy

   "secrets": { "providers": {
     "oaikey":       { "source": "file", "path": "~/.secrets/openai-api-key",    "mode": "singleValue" },
     "anthropickey": { "source": "file", "path": "~/.secrets/anthropic-api-key", "mode": "singleValue" }
   } },
   "models": { "providers": {
     "openai-metered": {
       "baseUrl": "https://api.openai.com/v1", "api": "openai-responses",
       "apiKey": { "source": "file", "provider": "oaikey", "id": "value" },
       "models": [{ "id": "gpt-5.6-luna", "name": "GPT-5.6 luna (metered)", "input": ["text", "image"] }]
     },
     "anthropic-metered": {
       "baseUrl": "https://api.anthropic.com", "api": "anthropic-messages",
       "apiKey": { "source": "file", "provider": "anthropickey", "id": "value" },
       "models": [{ "id": "claude-haiku-4-5", "name": "Claude Haiku 4.5 (metered)", "input": ["text", "image"] }]
     }
   } },
   "agents": { "defaults": { "model": {
     "primary": "openai/gpt-6-sol",
     "fallbacks": ["openai-metered/gpt-5.6-luna", "anthropic-metered/claude-haiku-4-5"]
   } } }

   Use the full path (/Users/you/.secrets/…) if ~ doesn't resolve. Then run openclaw models status to confirm every link authenticates.

10. Schedule your first job

    Copy

    openclaw cron add --name "Morning brief" --cron "30 7 * * *" --tz America/Los_Angeles \
      --session isolated --announce --channel telegram --to <your-telegram-user-id> \
      --tools "web_search" \
      --message "Look up today's weather for <your city>. Send a 2-line brief. If it's an ordinary day, reply NO_REPLY."

    Your Telegram user ID is the one from the pairing reply. Use --model to put busy jobs on a cheaper model.

11. Turn on dreaming and a nightly restart

    Copy

    openclaw config set plugins.entries.memory-core.config.dreaming.enabled true
    cat > ~/Library/LaunchAgents/local.openclaw-nightly-restart.plist <<'EOF'
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0"><dict>
      <key>Label</key><string>local.openclaw-nightly-restart</string>
      <key>ProgramArguments</key><array>
        <string>/bin/launchctl</string><string>kickstart</string><string>-k</string>
        <string>gui/501/ai.openclaw.gateway</string>
      </array>
      <key>StartCalendarInterval</key><dict>
        <key>Hour</key><integer>3</integer><key>Minute</key><integer>40</integer>
      </dict>
    </dict></plist>
    EOF
    sed -i '' "s#gui/501/#gui/$(id -u)/#" ~/Library/LaunchAgents/local.openclaw-nightly-restart.plist
    launchctl load ~/Library/LaunchAgents/local.openclaw-nightly-restart.plist

    The sed line swaps in your own user ID, in case it isn't the usual 501.

12. Then grow it one job at a time

    Add an MCP server (openclaw mcp add), give a group chat its own prompt, or wrap a data source in a small script that only prints what's new. Run openclaw cron list to see everything at a glance.

Scar tissue

Gotchas I paid for so you don't have to.