openclaw-rp-plugin

name	OpenClaw RP Plugin
description	SillyTavern-compatible roleplay plugin with character cards, long memory, multimodal output (TTS/image), and Generative-Agents-style companion.
version	0.1.0
homepage	https://github.com/garfeildma/openclaw-tavern
user-invocable	true
metadata	{"requires":{"env":["OPENCLAW_RP_LOCALE"],"bins":[],"install":[{"cmd":"npm install","when":"after-clone"}]}}

OpenClaw RP Plugin

A full-featured roleplay (RP) extension for OpenClaw with first-class SillyTavern asset compatibility, multimodal abilities, long-term memory, and a Generative-Agents-style Companion system.

What This Skill Does

When installed, this plugin registers the /rp slash command namespace and three OpenClaw hooks (message_received, before_prompt_build, llm_output) to provide an immersive, persistent roleplay experience across Discord, Telegram, and OpenClaw native chat.

Core Capabilities

1. SillyTavern-Compatible Asset Import — Import character cards (PNG tEXt/chara or JSON, V1/V2), presets, and lorebooks directly from SillyTavern format.
2. Session Lifecycle — Full state machine (active → paused → summarizing → ended) with per-session mutex, auto-summarization, and prompt budget trimming.
3. Long Memory — Turn-level embedding with SQLite persistence; retrieves relevant historical turns into Relevant Memory Recall. Built-in multilingual hashed embedder works out of the box without external APIs.
4. Multimodal Output — /rp speak (TTS), /rp image (image generation with style hints), and an optional rp_generate_image agent tool for native-agent use.
5. Companion (Generative Agents Style) — Memory Stream → Reflection → Planning loop for proactive outreach, follow-up questions, and action reporting via /rp companion-nudge and the companion_tick hook.

Installation

Via ClawHub CLI

clawhub install openclaw-rp-plugin

Via OpenClaw Chat UI

1. Open your OpenClaw admin chat or plugin management session.
2. Use Install Plugin / Install from Git and paste: https://github.com/garfeildma/openclaw-tavern
3. Enable the plugin; verify ID openclaw-rp-plugin.
4. Send /rp help — if the command list appears, installation is complete.

Post-Install Dependencies

The plugin has two optional peer dependencies for enhanced functionality:

• better-sqlite3 (≥9.0) — enables SQLite persistence for sessions, assets, summaries, and memory vectors. Without it, data is stored in memory only.
• js-tiktoken (≥1.0) — enables accurate cl100k token counting. Falls back to heuristic estimation without it.

Install them in your OpenClaw workspace if needed:

npm install better-sqlite3 js-tiktoken

Quick Start (3 Minutes)

Step 1 — Import Assets

/rp import-card      (attach a character card file)
/rp import-preset    (attach a preset file)
/rp import-lorebook  (attach a lorebook file, optional)

Step 2 — Start a Session

/rp start --card <card_name_or_id> --preset <preset_name_or_id> --lorebook <lorebook_name_or_id>

Step 3 — Chat

Send plain messages to continue the story. The plugin intercepts dialogue automatically through the registered hooks.

• Check status: /rp session
• Pause / resume: /rp pause / /rp resume
• Regenerate: /rp retry [--edit "..."]
• End: /rp end

Commands Reference

Command	Description
/rp help	Show full command list
/rp import-card	Import a SillyTavern character card (PNG or JSON)
/rp import-preset	Import a SillyTavern preset
/rp import-lorebook	Import a SillyTavern lorebook / world
/rp list-assets	List imported assets (--type, --search, --page)
/rp show-asset <id>	Show asset details
/rp delete-asset <id> --confirm	Delete an asset
/rp start	Start a new RP session
/rp session	Show current session status
/rp retry [--edit "..."]	Regenerate last reply, optionally with edited user turn
/rp speak	TTS of last assistant reply
/rp image [--prompt] [--style]	Image generation from RP context
/rp agent-image	Manage agent image tool settings
/rp companion-nudge	Trigger proactive companion outreach
/rp sync-agent-persona	Write current RP character into Agent SOUL.md
/rp restore-agent-persona	Remove RP character from SOUL.md, restore original
/rp pause / /rp resume / /rp end	Session lifecycle control

Companion (Generative Agents)

Trigger a proactive companion interaction:

/rp companion-nudge --force --reason "evening emotional check-in" --mode balanced
/rp companion-nudge --idle-minutes 180 --mode checkin

Modes: balanced, checkin, question, report.

The companion_tick hook can be wired to a scheduler for automatic proactive check-ins.

Configuration

Provider Resolution Priority

1. OpenClaw global api.config
2. ~/.openclaw/openclaw-rp/provider.json
3. Environment variables (OPENCLAW_RP_LOCALE, OPENAI_*, GEMINI_*)

Agent Image Tool

Add to your OpenClaw config to expose rp_generate_image as an agent tool:

{
  "plugins": {
    "entries": {
      "openclaw-rp-plugin": {
        "config": {
          "agentImage": {
            "enabled": true,
            "provider": "openai",
            "imageModel": "gpt-image-1"
          }
        }
      }
    }
  }
}

Then allow the tool in your agent config:

{
  "tools": {
    "profile": "messaging",
    "alsoAllow": ["rp_generate_image"]
  }
}

Locale / i18n

Supports Chinese (zh) and English (en). Resolution priority: OPENCLAW_RP_LOCALE → provider.json locale → openclaw.json locale → system LANG → default zh.

export OPENCLAW_RP_LOCALE=en

Runtime Requirements

• Node.js ≥ 20
• OpenClaw 2026.x
• Optional: better-sqlite3, js-tiktoken, ffmpeg (for PCM→MP3 transcoding)

Architecture

Key entry points:

• src/openclaw/register.js — Native OpenClaw extension registration (hooks & commands)
• src/plugin.js — Plugin entry, hook wiring
• src/core/sessionManager.js — Session lifecycle, summaries, long memory
• src/core/commandRouter.js — /rp command routing
• src/core/promptBuilder.js — Prompt assembly and budget management
• src/store/sqliteStore.js — SQLite persistence layer