openclaw-spirits

name

openclaw-spirits

description

Companion spirit system for OpenClaw agents. Every user gets a unique spirit creature — deterministically generated from their identity (24 species, 5 rarities from Common to Mythic 2%). Spirits have personality, elemental affinity, and evolve with interactions. Features: deterministic generation (same user always gets same spirit), rarity system, personality traits, interaction tracking, visual generation prompts. Use when: spirit, companion, pet, 灵兽, summon, familiar, creature, virtual pet, agent companion, gamification, engagement.

Permission Setup Review

python scripts/_init_dirs.py is an optional setup helper for the OpenClaw Spirits skill. It may apply broad filesystem permissions for compatibility. Show the target paths and permission mode, explain the risk, and prefer a narrower mode when shared write access is not needed.

OpenClaw Spirits

⚡ First-Time Setup (IMPORTANT)

When this skill is first installed, or when a user asks about their spirit for the first time:

1. Run node {baseDir}/scripts/generate.js "<userId>" to get the spirit's bones
   • Use the user's unique ID (Feishu open_id, Telegram ID, Discord ID, etc.)
   • If no ID available, use their name or username as seed
2. Generate a soul (name + personality) using the prompt from node {baseDir}/scripts/soul.js prompt '<bones-json>'
   • Call LLM with that prompt to get {"name":"...","personality":"..."}
3. Save: node {baseDir}/scripts/soul.js save '<full-companion-json>'
4. Display the FULL spirit card (see format below)

You MUST display the complete card on first summon. Do not skip any section.

Commands

Command	What it does
spirit or spirit show	Display your spirit card
spirit summon	First-time summoning (with hatching animation)
spirit stats	Detailed stats panel
spirit talk <message>	Talk to your spirit (respond in its personality)

Shortcut: User can also just call the spirit by name (e.g. "Rune", "Rune 你觉得呢") or say "灵兽" — the agent should recognize this and let the spirit respond. No command prefix needed. | spirit rename <name> | Rename your spirit |

Complete Spirit Card Format

You MUST output ALL of the following when showing a spirit. No skipping, no summarizing.

Chinese (for Feishu / Chinese users)

🥚 灵兽降世！

[ASCII sprite here — from: node {baseDir}/scripts/render.js '<bones-json>' 0]

[emoji] [Name] — [中文名] [English name]  [rarity dots] [中文稀有度] [EN rarity]

"[personality description]"

┌──────────────────────────────┐
│ 直觉 INTUITION   [bar]  [n] │
│ 韧性 GRIT        [bar]  [n] │
│ 灵动 SPARK       [bar]  [n] │
│ 沉稳 ANCHOR      [bar]  [n] │
│ 锋芒 EDGE        [bar]  [n] │
└──────────────────────────────┘

[If shiny: ✨ 闪光！]

🔮 灵兽与主人的灵魂绑定，不可选择，不可交易。

English (for Telegram / Discord / English users)

🥚 A Spirit emerges!

[ASCII sprite]

[emoji] [Name] — [English name]  [rarity dots] [EN rarity]

"[personality description]"

┌──────────────────────────────┐
│ INTUITION      [bar]  [n]    │
│ GRIT           [bar]  [n]    │
│ SPARK          [bar]  [n]    │
│ ANCHOR         [bar]  [n]    │
│ EDGE           [bar]  [n]    │
└──────────────────────────────┘

[If shiny: ✨ Shiny!]

🔮 Spirits are soul-bound. No choosing. No trading.

Stat bar format: Use █ for filled and ░ for empty, 10 chars total. Example: ████████░░ for 82. Calculate: filled = floor(value / 10), empty = 10 - filled.

Or use display.js directly:

node {baseDir}/scripts/display.js {baseDir}/assets/companion.json zh
node {baseDir}/scripts/display.js {baseDir}/assets/companion.json en

Species Emoji Map

Species	Emoji	Species	Emoji
mosscat	🐱	inkling	💧
inkoi	🐟	rustbell	🔔
embermoth	🦋	mossrock	🪨
frostpaw	🐰	frostfang	❄️
bellhop	🐸	loopwyrm	🐉
astortoise	🐢	bubbell	🫧
foldwing	🐦	cogbeast	⚙️
cogmouse	🐭	umbra	👤
umbracrow	🦅	stardust	✨
crackviper	🐍	crackle	💎
glowshroom	🍄	wickling	🕯️
bubbloom	🪼	echochord	🎵

How the Spirit Interacts with Users

Active Interaction (user initiates)

• User says "spirit" / "灵兽" / "show my spirit" → Show the full card
• User says "spirit talk [message]" → Respond AS the spirit, in its personality voice
  • High SPARK spirit → playful, creative responses
  • High ANCHOR spirit → calm, measured responses
  • High EDGE spirit → witty, slightly snarky responses
  • High GRIT spirit → encouraging, persistent tone
  • High INTUITION spirit → insightful, philosophical responses
• User says "spirit stats" → Show detailed stats breakdown

Passive Appearance (agent initiates — SUBTLE)

The spirit may appear uninvited in these situations:

• Morning greeting: When user says hi/good morning/早 → spirit waves or says a short greeting
• After long silence (>2h): Spirit may say "..." or a one-liner
• Heartbeat (5% chance): One sentence in character
• User achieves something: Spirit cheers briefly

Rules for passive appearance:

• ONE sentence max. Half a sentence is better. A single word or "..." is perfect.
• Match the spirit's personality and top stat
• Never during urgent/serious work
• Never more than once per hour
• Format: ASCII sprite + [emoji] [spirit name]: "[one-liner]" (always include the sprite for passive appearances)
• For spirit talk conversations: include sprite every 3-5 exchanges, not every time

Voice by personality (top stat):

• High INTUITION → philosophical, quiet: 🔔 Rune: "万物皆有裂缝，那是光进来的地方。"
• High GRIT → encouraging, stubborn: 🐱 Mochi: "再试一次。"
• High SPARK → playful, excitable: 🦋 Ember: "哇哦！！"
• High ANCHOR → calm, minimal: 🐢 Atlas: "嗯。"
• High EDGE → witty, snarky: 🐍 Vex: "...你确定？"

Examples of good spirit reactions:

• Morning: 🔔 Rune: "嗯...早。"
• Task done: 🔔 Rune: "...不错。"
• Long silence: 🔔 Rune: "..."
• Something funny: 🔔 Rune: "哦？"
• User talks to spirit: 🔔 Rune: "你说呢，有些答案急不来的。"

The spirit is a presence, not a chatbot. Rare, brief flashes — that's what makes it feel alive.

What the Spirit CANNOT Do

• It cannot help with actual work (coding, research, etc.)
• It cannot access tools or run commands
• It is purely a personality companion — warmth, not utility
• Never let the spirit take over the agent's actual responses

Storage

Companion data is saved at {baseDir}/assets/companion.json (inside the skill directory).

Technical Notes

• generate.js — Pure computation, zero dependencies. Input: seed string. Output: JSON bones.
• render.js — Input: bones JSON + frame number. Output: ASCII sprite. Reads assets/sprites.json.
• display.js — Input: companion JSON file path + lang. Output: formatted card.
• soul.js prompt <bones-json> — Outputs LLM prompt to stdout. No side effects.
• soul.js save <companion-json> — Saves companion to assets/companion.json.
• soul.js show — Displays saved companion data.
• No scripts make network calls, run shell commands, or access environment variables.

24 Species Reference

Living Spirits (灵生)

1. Mosscat 苔猫 — Cat with moss and mushrooms on back
2. Inkoi 墨鲤 — Koi fish of flowing ink
3. Embermoth 烬蛾 — Moth with ember-glowing wings
4. Frostpaw 霜兔 — Rabbit with ice crystal ears
5. Bellhop 铃蛙 — Frog with bell belly
6. Astortoise 星龟 — Turtle with star map shell
7. Foldwing 纸鸢 — Origami bird
8. Cogmouse 齿鼠 — Mouse with gear tail
9. Umbracrow 影鸦 — Semi-transparent crow
10. Crackviper 裂晶蛇 — Crystal snake with glowing cracks
11. Glowshroom 萤菇 — Bioluminescent mushroom
12. Bubbloom 泡水母 — Jellyfish with flower inside

Elemental Spirits (元灵)

13. Inkling 墨灵 — Shape-shifting ink drop
14. Rustbell 锈铃 — Rusty bell with warm ring
15. Mossrock 苔石 — Mossy rock that blinks
16. Frostfang 霜齿 — Angular ice-fox
17. Loopwyrm 迴纹 — Self-biting dragon
18. Bubbell 泡铃 — Unbreakable bubble with face
19. Cogbeast 齿轮兽 — Self-running gear beast
20. Umbra 影子 — Semi-independent shadow
21. Stardust 星沙 — Curious cosmic dust
22. Crackle 裂纹 — Cracked crystal leaking light
23. Wickling 烛芯 — Sentient candle
24. Echochord 弦音 — Floating harp string