OpenClaw Supabase Skill: Database Integration for AI Agents

OpenClaw agents are stateless by default. Each run starts fresh. Supabase solves this by giving your agent a persistent PostgreSQL database — conversation history, task states, and accumulated knowledge all stored and queryable across every session. Here's the complete integration.

What Supabase Adds to OpenClaw

Supabase is a hosted PostgreSQL database with a REST API, real-time subscriptions, and built-in authentication. For OpenClaw agents, it serves two primary roles:

• Persistent memory — store conversation history, task logs, and agent state that persist across sessions
• Data pipeline — read from and write to application databases as part of business workflows

The real-time subscription feature is particularly powerful. When a row changes in Supabase, OpenClaw receives an event and can trigger an action automatically — creating event-driven workflows without polling.

Supabase Project Setup

Create a Supabase project at supabase.com. Once the project is provisioned, go to Settings → API to find your project URL and API keys. You need the service role key for OpenClaw (full database access, bypasses RLS).

Create a table for agent memory. A simple conversation log table:

CREATE TABLE agent_memory (
  id BIGSERIAL PRIMARY KEY,
  session_id TEXT NOT NULL,
  role TEXT NOT NULL,  -- 'user' | 'agent'
  content TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX ON agent_memory(session_id, created_at DESC);

OpenClaw Configuration

skills:
  supabase:
    enabled: true
    url: ${SUPABASE_URL}
    service_role_key: ${SUPABASE_SERVICE_KEY}
    default_table: agent_memory
    realtime:
      enabled: false  # set true to subscribe to table changes
      tables: ["tasks", "events"]

Integration Patterns

The most valuable pattern is persistent conversation memory. Before responding, the agent queries recent history; after responding, it logs the exchange:

skills:
  answer_with_memory:
    trigger: event(message.received)
    actions:
      - skill: supabase
        action: query
        table: agent_memory
        filter:
          session_id: "{{event.session_id}}"
        order: created_at.desc
        limit: 20
      - skill: llm_respond
        context: "{{supabase.results}}"
        message: "{{event.content}}"
      - skill: supabase
        action: insert
        table: agent_memory
        data:
          session_id: "{{event.session_id}}"
          role: "agent"
          content: "{{llm_respond.output}}"

For event-driven workflows, enable real-time subscriptions. When a new task is inserted into Supabase by another system, OpenClaw picks it up and processes it automatically:

realtime:
  enabled: true
  tables: ["tasks"]
  on_insert:
    skill: process_task
    filter:
      status: "pending"

Common Mistakes

Fetching too many rows without a limit is the most common performance mistake. Always set a limit on memory queries — loading 1,000 rows of conversation history into context wastes tokens and slows responses.

• Using anon key for write operations — the anon key is subject to RLS policies. If your tables have restrictive policies, inserts will silently fail. Use the service role key for agent operations.
• Not indexing session_id and created_at — without indexes, memory queries get slow as the table grows. Always index the columns you filter and sort by.
• Enabling realtime without understanding costs — Supabase's free tier includes realtime connections, but each subscription counts against concurrent connection limits. Start without realtime and add it only when needed.
• Missing error handling for database failures — build fallback actions for when Supabase is unavailable. An agent that hard-fails on a DB timeout provides a poor experience.

Frequently Asked Questions

Do I need a paid Supabase account?
No. Supabase's free tier includes a PostgreSQL database, 500MB storage, and 2GB bandwidth per month — sufficient for most OpenClaw workflows.

Can OpenClaw query Supabase in real time?
Yes. The skill supports real-time subscriptions via Supabase's Realtime feature. Subscribe to table changes and trigger OpenClaw actions automatically.

What authentication method does OpenClaw use?
OpenClaw uses the Supabase service role key for full database access, or the anon key for public operations. Store credentials in OpenClaw's secrets manager.

Can OpenClaw write to Supabase tables?
Yes. The skill supports INSERT, UPDATE, UPSERT, and DELETE operations on any table the service role key has access to.

Does the Supabase skill support Row Level Security?
Yes. The anon key respects RLS policies normally. The service role key bypasses RLS — use with appropriate caution.

Can I use Supabase as persistent memory for OpenClaw agents?
Yes — this is one of the most popular patterns. Store conversation history, agent state, and task logs in Supabase tables for context that persists across sessions.