ai-companion-setup_skill

Overview

This skill documents a complete, battle-tested guide to build an AI companion agent on OpenClaw that remembers, sends text, voice, and selfies, and proactively messages on Feishu. It consolidates architecture, required files, cron patterns, scripts, and practical workarounds for platform quirks. The content focuses on concrete steps, pitfalls, and repeatable scripts to get a reliable companion running.

How this skill works

The agent runs in a workspace directory with clear files for persona (SOUL.md), heartbeat behavior (HEARTBEAT.md), tool docs (TOOLS.md), and per-day memories. A cron-triggered heartbeat reads memory, decides an action, writes memory, then invokes shell scripts (send.sh, voice.sh, selfie.sh) to push content to Feishu. All outputs must be sent via explicit scripts because isolated sessions do not forward direct agent text to Feishu.

When to use it

• Deploying a proactive companion bot that needs persistent memory and scheduled touchpoints.
• Sending TTS voice messages and selfie images to Feishu with correct media formats.
• Needing robust orchestration that avoids isolated-session delivery issues.
• Building a reproducible agent workflow with clear tools and cron heartbeats.
• Testing multi-modal outputs (text, voice, image) with per-day memory logging.

Best practices

• Put the highest-priority anti-AI identity rules at the top of SOUL.md so the model never drifts.
• Always write memory before sending any message; output ends the session and prevents later writes.
• Require scripts to print their full execution output in cron prompts to prevent false-positive tool execution.
• Use opus audio (not mp3) and send with msg_type="audio" via Feishu API; bypass broken OpenClaw media handling.
• Whitelist media paths under ~/.openclaw/media or allowed workspaces; avoid workspace-* as it may be blocked.

Example use cases

• A daily friendly check-in that alternates between chat, voice notes, music links, and selfies.
• A personalized companion that remembers user preferences and follows up on past topics.
• Automated hourly selfie cron that generates and sends a context-aware image with caption.
• Scheduled voice encouragements using MiniMax Speech via fal.ai and converted to opus for Feishu.
• A testing harness to validate that scripts truly executed by requiring their output in the cron message.