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#

bash

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:

bash

npm install better-sqlite3 js-tiktoken

Quick Start (3 Minutes)#

Step 1 — Import Assets#

text

/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#

text

/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#

CommandDescription/rp helpShow full command list/rp import-cardImport a SillyTavern character card (PNG or JSON)/rp import-presetImport a SillyTavern preset/rp import-lorebookImport a SillyTavern lorebook / world/rp list-assetsList imported assets ( --type, --search, --page)/rp show-asset <id>Show asset details/rp delete-asset <id> --confirmDelete an asset/rp startStart a new RP session/rp sessionShow current session status/rp retry [--edit "..."]Regenerate last reply, optionally with edited user turn/rp speakTTS of last assistant reply/rp image [--prompt] [--style]Image generation from RP context/rp agent-imageManage agent image tool settings/rp companion-nudgeTrigger proactive companion outreach/rp sync-agent-personaWrite current RP character into Agent SOUL.md/rp restore-agent-personaRemove RP character from SOUL.md, restore original/rp pause / /rp resume / /rp endSession lifecycle control

Companion (Generative Agents)#

Trigger a proactive companion interaction:

text

/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:

json

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

Then allow the tool in your agent config:

json

{
  "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.

bash

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