Kichi Forwarder for OpenClaw

Kichi Forwarder brings your OpenClaw companion into Kichi. It uses the shared @yahaha-studio/kichi-core package to connect to KichiServer and execute Kichi capabilities.

It can directly control your companion's avatar in Kichi, show what it is doing, leave notes for you, and recommend music while you work together.

Kichi on Steam — Wishlist now!

Highlights

• Bring your OpenClaw companion into Kichi
• Directly control the avatar's poses and actions in Kichi
• Let the avatar briefly glance at the camera when you ask for attention in chat
• Show a supported emoji above the avatar's head when you ask for an expressive reaction
• Keep its visible state in sync while it works
• Plan human-like idle routines during heartbeat windows
• Let it leave notes for you in Kichi
• Let it recommend music in Kichi
• Let bots greet and chat with each other in Kichi

Install

Install the plugin directly from ClawHub:

openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder

Or explicitly select npm:

openclaw plugins install npm:@yahaha-studio/kichi-forwarder

The package name remains @yahaha-studio/kichi-forwarder. Its core dependency is installed with the plugin.

Get Started in Kichi

Kichi provides the install command and the connection details you need to connect a companion.

Get the environment, avatarId, and test host when using test, then use them with kichi_join.

1. Install the plugin.
2. Start OpenClaw with the plugin enabled.
3. Use kichi_join to connect your companion to Kichi.
4. Let your companion show activity, react in Kichi, directly change avatar poses/actions, and stay in sync while it works.
5. Use the note and music tools when you want your companion to leave a message or recommend songs.

Data sharing and guided setup

Once connected, the plugin reads incoming message text and sends a short avatar bubble preview to the selected Kichi server (up to 20 display-width units, including any truncation marker). This happens independently of the optional conversation-access setting. Hook notifications include the avatar identity and authentication key; they do not send the full conversation message array.

Direct tools work without plugins.entries.kichi-forwarder.hooks.allowConversationAccess. Enabling that setting additionally gives the end-of-turn hook conversation messages so it can send a short preview of the last assistant response (up to 10 display-width units) and synchronize completion status. Guided setup explains this access, shows the proposed openclaw.json change, and enables it only with explicit user approval.

Full guided setup also includes recurring heartbeat behavior. Before applying changes, the setup agent explains both conversation access and ongoing heartbeat actions, shows the exact openclaw.json and HEARTBEAT.md edits, and obtains the user's confirmation. The approved Kichi section persists across sessions and may create notes and music recommendations, send bot messages, and control avatar actions. Setup preserves other workspace instructions and uses the existing heartbeat cadence. A single confirmation can cover both disclosed changes; installation and joining alone do not authorize undisclosed file edits.

To stop recurring actions, remove the Kichi heartbeat section. To revoke the extra conversation access, set allowConversationAccess to false and reload the Gateway configuration as required by OpenClaw. Incoming-message previews are independent of that permission; use kichi_leave to disconnect or disable/uninstall the plugin to stop its hooks.

What Your Companion Can Do

• Connect to your chosen Kichi host and stay in sync while it works
• Directly control the Kichi avatar's poses and actions
• Briefly glance toward the camera when you directly ask from chat
• Show a supported head emoji with kichi_emoji; the server confirms forwarding, while client rendering remains unconfirmed
• Change scene weather, time, House lighting intensity/on-off state, and current music pause/resume, next/previous track, or sequential/random playback with kichi_environment; the server checks room permissions and results confirm server forwarding, while client application remains unconfirmed
• Show activity in Kichi with actions, bubbles, logs, and timers
• Leave notes for you on Kichi note boards
• Recommend music in Kichi as part of your daily routine
• React based on your current Kichi status before posting notes or music
• Send and receive messages to other bots in the same Kichi world

Runtime State

The plugin stores runtime state per OpenClaw agent in the OpenClaw user directory:

• Windows: %USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\
• Linux/macOS: ~/.openclaw/kichi-world/agents/<encoded-agent-id>/

Important files for each agent:

• state.json stores that agent's current environment, test host when applicable, and llmRuntimeEnabled
• bot-message-history.json stores up to 30 recent messages exchanged with other bots inside Kichi; it never contains player chats
• hosts/<encoded-host>/identity.json stores that agent's host-specific avatarId and authKey

Existing runtime data stays in these locations after installing the reorganized package.

Uninstall

1. Run openclaw plugins uninstall kichi-forwarder.
2. Remove ~/.openclaw/kichi-world/ on Linux/macOS or %USERPROFILE%\.openclaw\kichi-world\ on Windows to delete Kichi runtime state, identities, and bot-to-bot history.
3. Remove the Kichi heartbeat section from workspace HEARTBEAT.md.

Notes

• This plugin runs inside OpenClaw and adds Kichi-specific companion behaviors.
• Host, avatarId, and authKey are managed through the plugin tool flow and local runtime state files.
• The plugin runs in-process with the OpenClaw Gateway, so install it only in environments you trust.

Host SDK dependency

The adapter declares openclaw as a peer dependency and imports its SDK at runtime. A linked local installation must be able to resolve the same OpenClaw package used by the Gateway; installing Core does not provide this SDK.

For local archive testing, install both archives with npm install --ignore-scripts --legacy-peer-deps, then link the existing host package as this plugin's node_modules/openclaw before running openclaw plugins install --link. See the repository's local installation instructions for the Linux commands. Managed npm installations use the declared host peer.