npm package: @funnyaibox/openclaw-goalark-channel
Description: Goalark channel plugin for OpenClaw - connects Goalark mobile app via relay
Latest version: 0.1.1

# 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

```bash
cd goalark-channel
pnpm install
pnpm build
```

### 2. Configure Moltbot

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

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

### 3. Start the Relay Server

```bash
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):**
```json
// Bot → Server
{"event": "authenticate", "data": {"device_id": "uuid", "role": "bot"}}

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

**After pairing:**
```json
// Bot → Server
{"event": "authenticate", "data": {"token": "jwt", "role": "bot"}}

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

### Pairing Flow

```json
// 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

```json
// 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

```typescript
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`:

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

### Testing MCP Server

```bash
# 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:

```json
{
  "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

```bash
# Watch mode
pnpm dev

# Build
pnpm build

# Clean
pnpm clean
```

## License

MIT