Octo

All About Octo…

A personal AI assistant built on OpenClaw — connecting language models to real-world services through agents, channels, and plugins.

This is the documentation for Octo 🐙, Jeff Steinbok’s personal AI assistant. Octo is one self-hosted instance of OpenClaw, an open-source framework for running AI agents. It runs on a Mac mini, I talk to it mostly over iMessage, and it handles mail, calendars, packages, the house and more through a set of plugins, background services, webhooks and scheduled jobs.

These pages describe how it is put together, so you can borrow the parts you like for your own OpenClaw setup. Most of the site is generated from Octo’s source repo (About These Docs explains how), so the inventories stay current.

Much of this setup is inspired by Omar Shahine’s work on 🦞 Lobster — his docs inspired me to publish my own. Selected plugins, services and shared libraries documented here are published as open source in openclaw-hub.

🤖
Agents & Channels
Octo's agents, what each may do, and the messaging apps they talk through
🧠
Memory
How agents remember — memory files, daily notes, and dreaming
🧮
Models
The language, decision and voice models behind each agent
🌐
External Integrations
How outside apps, other agents and webhooks reach Octo
🧩
Plugins
The tools agents call — email, calendars, cameras, restaurants…
🎯
Skills
Markdown instructions that tell agents how to do a job
⌨️
CLI Tools
Vetted scripts agents can run with exec
⚙️
Services
Background services that watch for events, such as new mail
⏰
Scheduled Tasks
Jobs that sync data, send reminders, and keep Octo healthy
🔧
Engineering Harness
How Octo finds its own problems and turns them into reviewed fixes

🦞 How Octo is put together

Octo is built from the standard OpenClaw pieces. At the center is the Gateway, OpenClaw’s always-on process that runs the agents and connects them to everything else.

🤖 Agents are personas powered by language models. Each agent has its own identity, personality and set of permitted tools. Agents talk to people through channels: messaging apps such as iMessage, Discord and Telegram. The Models page lists which model each agent uses.

🧩 Plugins are self-contained tools that agents can call: sending email, checking restaurant availability, taking a snapshot from a security camera, and more. Each plugin declares its own dependencies and is versioned on its own.

🎯 Skills are Markdown instructions. Unlike plugins, a skill is not code; it tells an agent how to approach a task and which tools to use. Think of plugins as tools and skills as know-how.

⌨️ CLI Tools are vetted scripts that agents allowed to use exec can run from ~/safebin/. They do deterministic jobs — file transforms, data exports, system queries — without a plugin and without spending model tokens.

⚙️ Services are long-running background processes that watch for events (like incoming email) and pass them on to agents or notifications.

🪝 Hooks are webhook entry points. A webhook from GitHub, Home Assistant or Microsoft 365 starts an agent the moment something happens. External Integrations covers how hooks and outside apps reach Octo through Tailscale Funnel.

⏰ Scheduled Tasks are OpenClaw cron jobs. Some start an agent; many just run a command and never touch a model.

🧠 Memory is how agents build up long-term knowledge: MEMORY.md files and daily notes committed to Git, plus dreaming, a background process that distills session transcripts during idle time.

💬 Channels

I talk to Octo mostly over iMessage, plus Discord and Telegram. iMessage was always the channel I wanted, but it needs a Mac, and I wasn’t buying one until I’d decided this was useful. It was: in October 2026 Octo moved to its own Mac mini, and it now sends and receives iMessages there through OpenClaw’s iMessage channel.

Family can text Octo too. Their direct messages and our family group chat go to a separate family agent (see Security below). In other group chats Octo only answers when someone mentions it.

🔒 Security

Security is the most important aspect of this experiment — even above just having fun.
  • Unprivileged account — OpenClaw runs under its own standard (non-admin) macOS user with no sudo rights. It can configure new plugins for itself, but it can’t install software on its own.
  • Owner-first access — Octo’s main agent only responds to me. Family members message a separate family agent over iMessage, which has a much narrower set of tools.
  • Per-person calendar rules — The family agent can read and update the shared family calendar for anyone, but personal calendars are limited to their owners: mine and TripIt only to me, my work calendar to me and one other family member. The calendar plugins enforce this using the sender the channel reports, not what the message claims.
  • No secrets in Git — Tokens and credentials live in local files that are never committed to version control.
  • No exec on the main agent — Octo’s main agent can’t run shell commands. If something truly needs elevated access, I have to ask the root agent explicitly; it is the only agent with elevated privileges. This is also why Octo leans on purpose-built plugins rather than skills: a skill can’t run code without exec, so every real-world action needs a plugin behind it.

📬 Mail and calendar

  • Mail read access — Octo reads my personal Outlook inbox through the Microsoft Graph API (OAuth2). Mail is never fed to the model wholesale; Octo queries it on demand with structured API calls.
  • Calendar access — Octo reads my personal and family calendars through the Graph API, another family member’s calendar through an ICS feed, and my work calendar through Exchange and the Graph API. The calendars are synced to Markdown files in memory every hour from 7 AM to 5 PM, and at midnight.
  • Its own mailbox — Octo has its own Fastmail mailbox, which it uses to send mail on my behalf. The Fastmail SSE service watches that mailbox for incoming mail.

💰 Cost

  • Self-hosted — Octo runs on a Mac mini (Apple silicon, 16 GB of RAM) running macOS. It moved there in October 2026 from an old Lenovo X1 Yoga Gen 3 running Ubuntu; the setup still works on Linux.
  • Token-conscious — As much work as possible is pushed into plugins and scripts so it doesn’t cost model tokens. The default model is Anthropic Claude Sonnet 4.6, with Claude Haiku 4.5 and an OpenAI model as fallbacks (see Models for the full lineup and per-agent overrides). The general rule is: push work into scripts, and let agents interpret the results.
    • Command jobs over agent jobs — Recurring tasks that don’t need reasoning run as OpenClaw command jobs, which run a script without starting an agent session. Fetching calendars, for example, went from about 75 seconds and 5 tool calls to about 6 seconds and no tokens. If a script fails, it can send a message to OpenClaw to report the error.
    • Light context for agent jobs — Scheduled jobs that do need an agent use lightContext: true, which leaves session history out of the context window and cuts input tokens on every run.
    • Narrow tool lists — Scheduled jobs set toolsAllow to just the tools they need, so an agent can’t reach for an expensive one by accident.
    • Small models for yes/no calls — Yes/no judgment calls go to a small decision model (TypeSafe AI’s Jev) instead of a full chat model.
  • Weekly cost report — Every Monday at 5 AM Pacific, the root agent runs the usage report skill. It parses OpenClaw’s usage logs and posts a PDF report to Discord, broken down by agent, model and token type (input, output, cache read, cache write), with the split between scheduled and interactive runs, a daily trend, and a per-model table — enough to see where costs are climbing and why.
  • Development with Claude Code — All plugin and config development happens in Claude Code. At first I had Octo debug itself, but a separate Claude Code session turned out to be far better for development, reading logs and troubleshooting.

🔧 Self-improvement

Octo has a small but growing set of checks that look for its own drift and quality problems. They run weekly and file GitHub issues for what they find. When I approve an issue, Octo writes a plan; when I approve the plan, Claude Code implements it and Octo opens a pull request for me to review and merge. Nothing merges without my approval, and a separate Health Check catches regressions while changes are rolled out.

Engineering Harness →

For how this site is built and published, see About These Docs. For what changed recently, see the Release Notes.