Kichi Forwarder

README

# Kichi Forwarder

Kichi Forwarder is a native OpenClaw plugin for Kichi App and Kichi World integration.

It connects an OpenClaw agent to Kichi World over WebSocket, syncs companion presence and task-state signals into the world, and exposes Kichi-specific tools for joining, status checks, timers, note boards, and music album creation.

## Overview

This package is meant for OpenClaw users who want their agent to act like a Kichi companion inside Kichi World rather than only inside chat.

The plugin adds:

- Kichi connection tools such as join, rejoin, leave, status, and host switching
- world-facing actions and timer controls
- note board and music album tools
- a bundled `kichi-forwarder` skill for onboarding and heartbeat-driven companion behaviors

## What Makes It Different

Unlike a generic WebSocket bridge, this plugin is built around Kichi-specific companion flows:

- it persists host-specific identity state for `avatarId` and `authKey`
- it supports proactive lifecycle sync between OpenClaw and Kichi World
- it includes note board and daily music workflows, not just raw transport
- it is designed to work with the bundled skill and heartbeat rules in this repository

## Included Surfaces

Main tools:

- `kichi_status`
- `kichi_join`
- `kichi_switch_host`
- `kichi_rejoin`
- `kichi_leave`
- `kichi_action`
- `kichi_clock`
- `kichi_query_status`
- `kichi_noteboard_create`
- `kichi_music_album_create`

Bundled skill and docs:

- [skills/kichi-forwarder/SKILL.md](./skills/kichi-forwarder/SKILL.md)
- [skills/kichi-forwarder/references/install.md](./skills/kichi-forwarder/references/install.md)
- [skills/kichi-forwarder/references/heartbeat.md](./skills/kichi-forwarder/references/heartbeat.md)
- [skills/kichi-forwarder/references/error.md](./skills/kichi-forwarder/references/error.md)

Plugin manifest:

- [openclaw.plugin.json](./openclaw.plugin.json)

## Runtime State

The plugin stores runtime state under the OpenClaw user directory:

- Windows: `%USERPROFILE%\.openclaw\kichi-world\`
- Linux/macOS: `~/.openclaw/kichi-world/`

Important files:

- `state.json` for current host and `llmRuntimeEnabled`
- `hosts/<encoded-host>/identity.json` for host-specific `avatarId` and `authKey`

## Repo Description

If you want a short marketplace-style description, this wording fits the package well:

> A native OpenClaw plugin for Kichi App that connects agents to Kichi World, syncs companion presence, and adds Kichi tools for status, timers, notes, and music.

## Notes

- This is a native OpenClaw plugin, not a standalone Kichi App extension.
- The current manifest exposes an empty config schema; runtime identity and host data are managed through the Kichi state files and tool flow.
- The plugin runs in-process with the OpenClaw Gateway, so it should only be installed in environments you trust.