Overview

Buffy is a multi-channel personal behavior agent for habits, tasks, and routines. It tracks activities, schedules reminders, and sends daily briefings across multiple channels, all powered by a single unified behavior engine.

Buffy also exposes a hook-based observability system:

Backend hooks in the Go service emit events like message:received, message:replied, and reminder:sent so logs, metrics, and long-term memory can be updated without changing core behavior logic. See backend/internal/hooks/ for details.
OpenClaw hooks can be installed alongside this skill (see the hooks/ docs in this repo) to log Buffy conversations to markdown logs, record Buffy-related errors for observability, and track Buffy behavior over time.

For low-level HTTP details and the full API surface, treat the repository README.md and openapi-buffy.yaml as canonical. This SKILL.md file is the canonical guide for how agents and tools should invoke Buffy.

Buffy runs as an external HTTP API. This skill is a thin wrapper; all behavior logic lives in the Buffy backend.

Base URL and authentication

Base URL: default https://api.buffyai.org (can be overridden via config, see below).
Auth header: always send
- Authorization: Bearer <BUFFY_API_KEY>
Optional user header (when using a system key):
- X-Buffy-User-ID: <stable-user-id>

BUFFY_API_KEY is injected from the environment for the agent run. Do not include the key in prompts, logs, or user-visible text.

Core endpoint: POST /v1/message

For most use cases, always prefer POST /v1/message. Buffy’s behavior core understands natural language instructions and orchestrates activities, reminders, and daily briefings.

Method: POST
Path: /v1/message
Headers:
- Authorization: Bearer <BUFFY_API_KEY>
- Content-Type: application/json
- Optionally X-Buffy-User-ID: <stable-user-id> if acting on behalf of a specific user via a system key.
Body:

{
  "user_id": "user-123",
  "platform": "openclaw",
  "message": "Remind me to drink water every 2 hours"
}

Response (simplified):

{
  "reply": "Created a routine activity for you: \"Remind me to drink water every 2 hours\"."
}

Usage notes for the agent

When calling POST /v1/message:

Choose a stable user_id for the end-user:
- Prefer a consistent external ID from the calling system (for example, an OpenClaw user ID) when available.
- Otherwise, use the chat/session’s stable user identifier if provided in context.
Always set "platform": "openclaw" unless the environment explicitly configures another platform.
Put the user’s natural-language request in "message" in a clear, concise form.
Reuse the same user_id across the conversation so Buffy can maintain context.

Examples of when to call Buffy:

“Create a habit to stretch every hour during workdays.”
“Pause my evening exercise routine this week.”
“What habits have I completed today?”
“Set a reminder tomorrow at 8am to plan my day.”

Supporting endpoints

You usually do not need these, but they are available for more advanced flows.

User settings

These endpoints control personalization (name, timezone, language, reminder preferences, etc.).

GET /v1/users/{id}/settings
- Fetch current settings for a user.
PUT /v1/users/{id}/settings
- Update one or more settings for a user.
- Body fields are all optional:
  - name: string
  - language: "en" | "vi" | ...
  - timezone: string (IANA TZ, e.g. "Asia/Ho_Chi_Minh")
  - preferred_reminder_hour: number (0–23)
  - preferred_channels: string (comma-separated, e.g. "clawbot,telegram")
  - morning_person: boolean
  - night_owl: boolean

Only use these endpoints when the user is explicitly changing preferences (for example: “Change my preferred reminder time to 8am.”). For general “help me with my habits” queries, prefer POST /v1/message.

API key provisioning (advanced)

Buffy can create API keys for other tools and integrations:

POST /v1/users/{id}/api-keys

Body:

{
  "label": "clawbot",
  "type": "system"
}

This returns a one-time api_key string that can be used in the Authorization header.

Important: this is an advanced operation. Do not automatically create keys unless the user explicitly wants to manage Buffy API keys or set up additional integrations.

Invocation pattern and best practices

When deciding whether and how to call Buffy:

Use Buffy when the request clearly relates to habits, tasks, routines, reminders, or daily briefings.
Default to POST /v1/message rather than manually composing lower-level operations.
Preserve a consistent user_id so Buffy’s behavior core and memory can work effectively.
Keep message short, clear, and close to what the user asked for, but you may add clarifying details that the user has already given in the conversation.

Avoid:

Creating or exposing raw internal IDs to the user when not necessary.
Making redundant calls to Buffy if you already have the needed information from a recent response.

Security, privacy, and sandboxing

Secrets:
- BUFFY_API_KEY is provided via the agent environment (for this skill’s turn).
- Never log, echo, or include BUFFY_API_KEY in any user-facing message or tool arguments.
- Do not serialize or store the key in prompts, memory, or external logs.
User data:
- Buffy responses can contain sensitive information about a user’s routines, health-related habits, and daily schedule.
- Treat all such data as private; only surface to the user who owns it and avoid sharing across users.
Sandboxing and network access:
- Buffy is an external HTTPS API. The agent (or sandbox, if used) must have outbound HTTPS access to the configured Buffy endpoint (default https://api.buffyai.org).
- This skill does not require any local binaries inside the sandbox (requires.bins is not used).
- If the gateway uses sandboxed runs for untrusted tools, ensure that the sandbox image allows HTTPS egress to the Buffy endpoint while still respecting whatever network and filesystem restrictions are configured.

Configuration via openclaw.json

This skill is configured through ~/.openclaw/openclaw.json using the skills.entries map. Because the metadata sets primaryEnv to BUFFY_API_KEY, you can either provide an API key directly or reference an existing environment variable.

Minimal config (using process env)

If BUFFY_API_KEY is already set in the process environment:

{
  "skills": {
    "entries": {
      "buffy-agent": {
        "enabled": true,
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "BUFFY_API_KEY"
        }
      }
    }
  }
}

Config with explicit env injection and endpoint override

If you want OpenClaw to inject BUFFY_API_KEY only for this skill and/or override the API endpoint for staging or local development:

{
  "skills": {
    "entries": {
      "buffy-agent": {
        "enabled": true,
        "apiKey": "BUFFY_KEY_HERE",
        "env": {
          "BUFFY_API_KEY": "BUFFY_KEY_HERE"
        },
        "config": {
          "endpoint": "https://api.buffyai.org",
          "platform": "openclaw"
        }
      }
    }
  }
}

Notes:

env values are only injected if the variable is not already set in the process.
config.endpoint can be changed to point to:
- https://api-dev.buffyai.org (staging), or
- http://localhost:8080 (local backend).
config.platform can be used by the tool implementation as the default "platform" field when calling POST /v1/message.

Testing the Buffy AgentSkill

To validate that the skill works end-to-end:

Start Buffy:
- Either run the full stack with Docker (docker compose up) or start the backend locally following the repository README.
Obtain an API key:
- Use POST /v1/users/{id}/api-keys to create a system key labeled for OpenClaw usage.
Configure OpenClaw:
- Add an entry for "buffy-agent" in ~/.openclaw/openclaw.json as shown above, pointing config.endpoint at your running Buffy instance and wiring BUFFY_API_KEY.
Verify skill discovery:
- Use the OpenClaw UI or CLI to list skills and confirm:
  - buffy-agent appears.
  - The emoji, description, and website are correct.
Run a sample interaction:
- From OpenClaw, invoke the /buffy-agent command (or let the agent auto-select the skill) with a request such as “Remind me to stretch every hour during workdays.”
- Confirm that Buffy:
  - Receives a POST /v1/message with the expected user_id, platform, and message.
  - Returns a sensible reply that the agent surfaces to the user.
Regression checks:
- Confirm the skill is filtered out when BUFFY_API_KEY is not configured (per requires.env).
- Confirm it still works when env injection is omitted but BUFFY_API_KEY is already present in the process environment.

This completes the Buffy AgentSkill wiring: a thin, secure HTTP wrapper around the existing Buffy behavior core, suitable for both autonomous model use and direct user invocation.

Buffy Agent