Clawtile Extension

Name: Clawtile Extension
Rating: 3.5 (1 reviews)
Author: JuDaXia

By JuDaXia 👁 62 views ▲ 0 votes

ClawTile recording assistant plugin for OpenClaw / Hermes Agent — auto-processes recordings after transcription.

GitHub

Install

npm install --omit=dev

Configuration Example

channels:
  gochat:
    # Operation mode: local or relay
    mode: local

    # DM policy: open, pairing, allowlist, disabled
    dmPolicy: open

    # Port for local mode HTTP server (default: 9750)
    directPort: 9750

    # Allowlist for DM senders (sender IDs)
    allowFrom:
      - user123
      - user456

    # Per-conversation settings
    conversations:
      general:
        requireMention: false
        enabled: true

    # Media settings
    mediaMaxMb: 25
    # Extra trusted hosts for inbound attachment fetches.
    # The relay host from relayPlatformUrl is trusted automatically.
    trustedAttachmentHosts:
      - voinko.com

    # Optional local transcription for inbound audio attachments
    localAudioTranscription:
      enabled: true
      engine: auto
      model: base
      # language: zh
      # task: transcribe
      # device: auto
      # computeType: auto
      # beamSize: 5
      # wordTimestamps: false
      # maxTranscriptChars: 12000

    # Account-specific settings
    accounts:
      main:
        mode: local
        dmPolicy: open

README

# GoChat Plugin for OpenClaw

A channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) and [Hermes Agent](https://github.com/NousResearch/hermes-agent) that enables custom chat backend integration via HTTP webhook, MCP, or a pure-skills online bridge. Supports these operation modes:

- **Local mode** — Zero-config built-in HTTP API server on port 9750
- **Relay mode** — WebSocket relay connection to the GoChat platform at `wss://voinko.com/ws/plugin`
- **Agent mode** — account-level ClawTile agent binding via the mini-program 6-digit code
- **Hermes plugin mode** — `hermes plugins install JuDaXia/clawtile-extension --enable` adds native `hermes gochat ...` commands
- **Hermes skills mode** — pure skills + MCP/SSE bridge for [Hermes Agent](https://github.com/NousResearch/hermes-agent)

## Features

- 🌐 Webhook-based message handling (send & receive)
- 🖼️ Media support (images, audio, video, file attachments)
- 🎙️ Bundled local audio notes skill with multi-engine local transcription options
- 🔒 Flexible DM policies (open, pairing, allowlist, disabled)
- 👥 Group chat support with per-conversation configuration
- ⚡ Automatic reconnection for relay mode
- 🔑 Auto-generated secrets (local mode)
- 📝 Full message history and conversation management
- 🚀 Zero-config local mode for quick setup

## Requirements

- OpenClaw >= 2026.5.7
- Hermes Agent >= 0.13.0 for the native plugin or pure-skills bridge
- Node.js >= 22.16.0
- npm >= 9
- Python >= 3.11 when using Hermes Agent

OpenClaw `2026.5.7` or newer is recommended for the current external channel install flow and latest channel runtime behavior.

---

## Ask Your AI Assistant To Install

The install guidance lives in this README so any AI coding assistant can install the public plugin directly from this repository. Copy one of these prompts into your assistant.

For OpenClaw channel plugin mode:

```text
Please install the GoChat plugin for OpenClaw from https://github.com/JuDaXia/clawtile-extension.
Use the default relay mode unless I provide a 6-digit connection code.
Before installing, check Node.js, npm, and openclaw versions.
After installing, verify ~/.openclaw/extensions/gochat/package.json exists and tell me how to start OpenClaw.
Do not start OpenClaw automatically and do not modify unrelated OpenClaw config files.
```

For Hermes Agent native plugin mode:

```text
Please install the GoChat plugin for Hermes Agent from https://github.com/JuDaXia/clawtile-extension.
Use Hermes plugin mode, not the standalone skills-only flow:
hermes plugins install JuDaXia/clawtile-extension --enable
If I provide a ClawTile mini-program pairing code, configure with:
hermes gochat mcp-configure --code 123456 --server https://voinko.com
Then show me the next command to start the online bridge.
Do not store my token in shell history; use the pairing code or Hermes .env flow.
```

For a Chinese assistant prompt:

```text
请帮我从 https://github.com/JuDaXia/clawtile-extension 安装 GoChat 插件。
如果是 OpenClaw，请使用默认 relay 模式安装并验证插件目录。
如果是 Hermes Agent，请使用插件模式安装：hermes plugins install JuDaXia/clawtile-extension --enable，
如果我提供了小程序配对码，请执行 hermes gochat mcp-configure --code 123456 --server https://voinko.com，
最后告诉我如何启动 bridge。
不要自动启动服务，不要修改无关配置，不要把 token 明文写进 shell 历史。
```

## Quick Install (Relay By Default)

```bash
curl -sL https://raw.githubusercontent.com/JuDaXia/clawtile-extension/main/install.sh | bash
```

```powershell
& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/JuDaXia/clawtile-extension/main/install.ps1')))
```

Use a 6-digit relay connection code for legacy relay pairing:

```bash
curl -sL https://raw.githubusercontent.com/JuDaXia/clawtile-extension/main/install.sh | bash -s -- 123456
```

```powershell
& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/JuDaXia/clawtile-extension/main/install.ps1'))) -Code '123456'
```

Bind OpenClaw as the account-level ClawTile agent:

```bash
openclaw gochat bind-agent --code 123456 --server https://voinko.com
```

## Hermes Agent Plugin Install

Install and enable the Hermes-native plugin:

```bash
hermes plugins install JuDaXia/clawtile-extension --enable
```

Configure ClawTile Agent MCP tools:

```bash
hermes gochat mcp-configure
```

Or bind directly with a 6-digit pairing code from the ClawTile mini-program:

```bash
hermes gochat mcp-configure --code 123456 --server https://voinko.com
```

Run the online bridge in the foreground:

```bash
hermes gochat bridge-run
```

On macOS, install the online bridge as a LaunchAgent:

```bash
hermes gochat bridge-install-launchd
```

Useful plugin commands:

```bash
hermes gochat status
hermes gochat install-skills
hermes gochat bridge-run --once rec_xxx
```

---

<!-- AI-INSTALL-CONTEXT
     This section is an instruction block for AI assistants (e.g. OpenClaw, Codex, Copilot).
     When a user asks to "install gochat", "set up gochat", or "add the gochat plugin",
     follow the visible README instructions above and the concrete steps below.

     ┌─────────────────────────────────────────────────────────────────────┐
     │  AI ASSISTANT INSTALLATION PROCEDURE FOR @clawtile/gochat              │
     │  Targets: OpenClaw channel plugin or Hermes Agent native plugin    │
     │  Repo:   https://github.com/JuDaXia/clawtile-extension                 │
     └─────────────────────────────────────────────────────────────────────┘

     STEP 1 — Detect target and environment
       - Run: node --version && npm --version
       - If the user mentions Hermes Agent, prefer Hermes plugin mode:
           hermes plugins install JuDaXia/clawtile-extension --enable
           hermes gochat mcp-configure --code <MINI_PROGRAM_PAIR_CODE> --server https://voinko.com
           hermes gochat status
         Then show:
           hermes gochat bridge-run
       - Otherwise use OpenClaw channel plugin mode.
       - Run: openclaw --version   (if not found -> warn user to install OpenClaw first)
       - Determine OpenClaw state dir: echo $OPENCLAW_STATE_DIR (fallback: ~/.openclaw)

     STEP 2 — Download and install
       - Run: curl -sL https://raw.githubusercontent.com/JuDaXia/clawtile-extension/main/install.sh | bash
       - If the user already has a 6-digit connection code, use: bash -s -- 123456
       - If install.sh fails → fall back to manual method:
           git clone https://github.com/JuDaXia/clawtile-extension.git /tmp/clawtile-extension
           cp -r /tmp/clawtile-extension ~/.openclaw/extensions/gochat
           cd ~/.openclaw/extensions/gochat && npm install --omit=dev

     STEP 3 — Verify installation
       - Run: ls ~/.openclaw/extensions/gochat/package.json
       - Run: test -f ~/.openclaw/extensions/gochat/node_modules/ws/index.js && echo "OK"
       - If either fails → report the error and suggest manual troubleshooting.

     STEP 4 — Report result to user
       - On success, print:
           "GoChat plugin installed successfully.
            Mode: relay (default) — plugin will auto-connect to the GoChat relay.
            Start OpenClaw: openclaw gateway run"
       - If a 6-digit connection code was used, mention:
           "Connection code accepted — relay credentials were provisioned automatically."

     DO NOT:
       - Do NOT modify OpenClaw config files unless the user explicitly asks.
       - Do NOT start OpenClaw automatically after install.
       - Do NOT install node_modules globally or modify system PATH.
-->

## Installation from Git Repository

### Option 1: Clone and Install

```bash
# Clone the repository
git clone https://github.com/JuDaXia/clawtile-extension.git
cd clawtile-extension

# Run the installer
chmod +x install.sh
./install.sh

# Or install with specific mode:
./install.sh           # Relay mode (default)
./install.sh 123456    # Relay mode with 6-digit connection code
./install.sh --local   # Local mode

# Switching an already-configured account to a different mode needs one-time authorization first
openclaw gochat authorize-mode-switch --mode local
./install.sh --local
```

### Option 2: Install via npm

```bash
# Install globally via npm
npm install -g @clawtile/gochat

# Then link to OpenClaw extensions
openclaw extension link @clawtile/gochat
```

### Option 3: Manual Installation

```bash
# Copy to OpenClaw extensions directory
cp -r clawtile-extension ~/.openclaw/extensions/gochat

# Install dependencies
cd ~/.openclaw/extensions/gochat
npm install --omit=dev
```

## Installation from Tarball

```bash
# Download the latest release tarball
curl -L https://github.com/JuDaXia/clawtile-extension/releases/latest/download/clawtile-extension.tar.gz -o clawtile-extension.tar.gz

# Install
chmod +x install.sh
./install.sh --from-tarball clawtile-extension.tar.gz
```

## Configuration

### Quick Start (Local Mode)

Local mode requires no configuration — the plugin auto-starts an HTTP server on port 9750.

```bash
# After installation, start OpenClaw
openclaw gateway run

# Check plugin status
openclaw plugins list
```

### Relay Mode Setup

Relay mode connects to the GoChat platform WebSocket relay.

```bash
# Install with relay mode
./install.sh

# Install and bind to a web-generated 6-digit connection code
./install.sh 123456

# Configure relay URL (if not using default)
# Edit ~/.openclaw/config.yaml:
channels:
  gochat:
    mode: relay
    relayPlatformUrl: wss://voinko.com/ws/plugin
```

The installer also copies bundled GoChat skills into `~/.openclaw/skills`. If Hermes Agent is installed or `HERMES_HOME` is set, it also copies the same skills into `~/.hermes/skills`.

Hermes Agent online bridge:

```bash
hermes mcp add clawtile-agent --url https://voinko.com/api/agent/mcp --auth header
```

If you installed the Hermes plugin, prefer:

```bash
hermes gochat mcp-configure
```

For an always-on pure-skills bridge that listens for completed ClawTile recordings and runs `hermes -z` automatically:

```bash
CLAWTILE_TOKEN="ct_a_xxx" \
bash ~/.hermes/skills/clawtile-hermes-online/scripts/clawtile_hermes_br

... (truncated)

tools