SillyTavern-compatible roleplay plugin with character cards, long memory, multimodal output (TTS/image), and Generative-Agents-style companion.
---
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
```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
```
/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:
```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
don't have the plugin yet? install it then click "run inline in claude" again.