Goalark Channel for Moltbot

Connect Moltbot to Goalark mobile app for AI-assisted goal management.

Overview

This plugin enables Moltbot to communicate with users through the Goalark mobile app. Messages are routed through a WebSocket relay server that handles:

• Device pairing via 6-character codes
• Real-time bidirectional messaging
• Token-based authentication with revocation support
• MCP Server for accessing Goalark data (goals, tasks, inspirations)
• Skill configuration for intent recognition and structured responses

Architecture

┌─────────────┐     WebSocket     ┌──────────────┐     WebSocket     ┌─────────────┐
│ Goalark App │ ←───────────────→ │ Relay Server │ ←───────────────→ │   Moltbot   │
│   (Flutter) │                   │   (:7003)    │                   │  (Gateway)  │
└─────────────┘                   └──────────────┘                   └──────┬──────┘
                                                                            │
                                                                      MCP (stdio)
                                                                            │
                                                                     ┌──────▼──────┐
                                                                     │ MCP Server  │
                                                                     │ (12 tools)  │
                                                                     └──────┬──────┘
                                                                            │
                                                                     ┌──────▼──────┐
                                                                     │  Flask API  │
                                                                     │   (:7002)   │
                                                                     └─────────────┘

Installation

1. Install the plugin

cd goalark-channel
pnpm install
pnpm build

2. Configure Moltbot

Add to your ~/.openclaw/moltbot.json:

{
  "plugins": {
    "goalark": {
      "relayUrl": "http://localhost:7003"
    }
  }
}

3. Start the Relay Server

cd goalark-server
python run_websocket.py

4. Pair with Goalark App

1. Start Moltbot gateway
2. A pairing code will be displayed (e.g., AB12CD)
3. Open Goalark app → Settings → Pair Device
4. Enter the 6-character code
5. Done! You can now chat with Moltbot from Goalark

Protocol

Authentication

First time (unpaired):

// Bot → Server
{"event": "authenticate", "data": {"device_id": "uuid", "role": "bot"}}

// Server → Bot
{"event": "authenticated", "data": {"device_id": "uuid", "role": "bot", "paired": false}}

After pairing:

// Bot → Server
{"event": "authenticate", "data": {"token": "jwt", "role": "bot"}}

// Server → Bot
{"event": "authenticated", "data": {"device_id": "uuid", "user_id": "uuid", "paired": true}}

Pairing Flow

// Bot → Server
{"event": "request_pairing_code", "data": {"device_id": "uuid"}}

// Server → Bot
{"event": "pairing_code", "data": {"code": "AB12CD", "expires_in": 600}}

// After user enters code in app...
// Server → Bot
{"event": "paired", "data": {"device_token": "jwt", "user_id": "uuid"}}

Messaging

// User message (Server → Bot)
{"event": "user_message", "data": {"session_id": "uuid", "text": "Hello", "client_msg_id": "uuid"}}

// Assistant response (Bot → Server)
{"event": "assistant_message", "data": {"session_id": "uuid", "text": "Hi!", "reply_to": "uuid"}}

API Reference

GoalarkRelayClient

import { GoalarkRelayClient } from '@moltbot/goalark-channel';

const client = new GoalarkRelayClient({
  id: 'account-1',
  relayUrl: 'http://localhost:7003',
  deviceId: 'unique-device-id',
  paired: false,
});

// Connect
await client.connect();

// Listen for messages
client.on('userMessage', (data) => {
  console.log('User said:', data.text);

  // Reply
  client.sendMessage({
    session_id: data.session_id,
    text: 'Hello from Moltbot!',
    reply_to: data.client_msg_id,
  });
});

MCP Server Integration

The plugin includes an MCP (Model Context Protocol) server that provides 12 tools for accessing Goalark data:

Available Tools

| Category | Tools | |----------|-------| | Goals | get_goals, get_goal_detail | | Tasks | get_tasks, create_task, complete_task | | Inspirations | get_inspirations, create_inspiration | | Info | get_info_items | | Summaries | get_today_summary, get_week_summary | | Commands | generate_daily_report, breakdown_goal, organize_inspirations, generate_weekly_summary |

MCP Configuration

The MCP server is configured in mcp-config.json:

{
  "mcpServers": {
    "goalark": {
      "command": "python",
      "args": ["run_mcp.py"],
      "cwd": "/path/to/goalark-server",
      "env": {
        "MCP_USER_ID": "${user_id}"
      }
    }
  }
}

Testing MCP Server

# Start MCP server directly
cd goalark-server
MCP_USER_ID=test_user python run_mcp.py

# Test with JSON-RPC
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | MCP_USER_ID=test python run_mcp.py

Skill Configuration

The skill file skills/goalark.md provides:

• Tool documentation and parameters
• Intent recognition patterns (e.g., "帮我创建任务" → create_task)
• Response format with metadata types
• Quick command shortcuts (/daily_report, /breakdown_goal, etc.)

Metadata Response Format

When the assistant uses tools, responses include metadata for UI updates:

{
  "text": "已创建任务：完成报告",
  "metadata": {
    "type": "data_mutation",
    "action": "create_task",
    "success": true,
    "data": { "id": 123, "title": "完成报告" }
  }
}

The Goalark App parses this metadata to:

• Show task execution progress
• Refresh relevant data lists
• Display structured outputs

Environment Variables (openclaw.plugin.json)

| Variable | Description | Example | |----------|-------------|---------| | GOALARK_PYTHON | Absolute path to the virtualenv Python binary | /path/to/goalark-server/.venv/bin/python | | GOALARK_SERVER_DIR | Absolute path to the goalark-server directory | /path/to/goalark/goalark-server |

Note: ${user_id} in the same file is an OpenClaw runtime substitution (not an OS env var).

Development

# Watch mode
pnpm dev

# Build
pnpm build

# Clean
pnpm clean

License

MIT