myclaw

Personal AI assistant built on agentsdk-go.

Features

• CLI Agent - Single message or interactive REPL mode
• Gateway - Full orchestration: channels + cron + heartbeat
• Telegram Channel - Receive and send messages via Telegram bot (text + image + document)
• Feishu Channel - Receive and send messages via Feishu (Lark) bot
• WeCom Channel - Receive inbound messages and send markdown replies via WeCom intelligent bot API mode
• WhatsApp Channel - Receive and send messages via WhatsApp (QR code login)
• Web UI - Browser-based chat interface with WebSocket (responsive, PC + mobile)
• Multi-Provider - Support for Anthropic and OpenAI models
• Multimodal - Image recognition and document processing
• Cron Jobs - Scheduled tasks with JSON persistence
• Heartbeat - Periodic tasks from HEARTBEAT.md
• Memory - Long-term (MEMORY.md) + daily memories
• Skills - Custom skill loading from workspace

Quick Start

# Build
make build

# Build smaller release binary
make build-release

# Interactive config setup
make setup

# Or initialize config and workspace manually
make onboard

# Set your API key
export MYCLAW_API_KEY=your-api-key

# Run agent (single message)
./myclaw agent -m "Hello"

# Run agent (REPL mode)
make run

# Start gateway (channels + cron + heartbeat)
make gateway

Makefile Targets

| Target | Description | |--------|-------------| | make build | Build binary | | make build-release | Build optimized binary with -trimpath -ldflags="-s -w" | | make package | Package optimized binary to dist/myclaw-<os>-<arch>.gz | | make package-all | Package optimized binaries for darwin/arm64 linux/amd64 linux/arm64 | | make run | Run agent REPL | | make gateway | Start gateway (channels + cron + heartbeat) | | make onboard | Initialize config and workspace | | make status | Show myclaw status | | make setup | Interactive config setup (generates ~/.myclaw/config.json) | | make tunnel | Start cloudflared tunnel for Feishu webhook | | make test | Run tests | | make test-race | Run tests with race detection | | make test-cover | Run tests with coverage report | | make docker-up | Docker build and start | | make docker-up-tunnel | Docker start with cloudflared tunnel | | make docker-down | Docker stop | | make lint | Run golangci-lint |

Binary Packaging

# Smaller binary for release
make build-release

# Create compressed package (.gz)
make package

# Build and package default multi-platform artifacts
make package-all

# Or customize target platforms
make package-all PLATFORMS="linux/amd64 linux/arm64"

make package creates a single archive dist/myclaw-<os>-<arch>.gz. make package-all creates multiple archives under dist/, suitable for release distribution and low-bandwidth deployment.

Architecture

┌─────────────────────────────────────────────────────────┐
│                      CLI (cobra)                        │
│              agent | gateway | onboard | status          │
└──────┬──────────────────┬───────────────────────────────┘
       │                  │
       ▼                  ▼
┌──────────────┐  ┌───────────────────────────────────────┐
│  Agent Mode  │  │              Gateway                  │
│  (single /   │  │                                       │
│   REPL)      │  │  ┌─────────┐  ┌──────┐  ┌─────────┐  │
└──────┬───────┘  │  │ Channel │  │ Cron │  │Heartbeat│  │
       │          │  │ Manager │  │      │  │         │  │
       │          │  └────┬────┘  └──┬───┘  └────┬────┘  │
       │          │       │          │           │        │
       ▼          │       ▼          ▼           ▼        │
┌──────────────┐  │  ┌─────────────────────────────────┐  │
│  agentsdk-go │  │  │          Message Bus             │  │
│   Runtime    │◄─┤  │    Inbound ←── Channels          │  │
│              │  │  │    Outbound ──► Channels          │  │
└──────────────┘  │  └──────────────┬──────────────────┘  │
                  │                 │                      │
                  │                 ▼                      │
                  │  ┌──────────────────────────────────┐  │
                  │  │      agentsdk-go Runtime         │  │
                  │  │   (ReAct loop + tool execution)  │  │
                  │  └──────────────────────────────────┘  │
                  │                                       │
                  │  ┌──────────┐  ┌────────────────────┐  │
                  │  │  Memory  │  │      Config        │  │
                  │  │ (MEMORY  │  │  (JSON + env vars) │  │
                  │  │  + daily)│  │                    │  │
                  │  └──────────┘  └────────────────────┘  │
                  └───────────────────────────────────────┘

Data Flow (Gateway Mode):
  Telegram/Feishu/WeCom/WhatsApp/WebUI ──► Channel ──► Bus.Inbound ──► processLoop
                                                                      │
                                                                      ▼
                                                               Runtime.Run()
                                                                      │
                                                                      ▼
                                       Bus.Outbound ──► Channel ──► Telegram/Feishu/WeCom/WhatsApp/WebUI

Project Structure

cmd/myclaw/          CLI entry point (agent, gateway, onboard, status)
internal/
  bus/               Message bus (inbound/outbound channels)
  channel/           Channel interface + implementations
    telegram.go      Telegram bot (polling, text/image/document)
    feishu.go        Feishu/Lark bot (webhook)
    wecom.go         WeCom intelligent bot (webhook, encrypted)
    whatsapp.go      WhatsApp (whatsmeow, QR login)
    webui.go         Web UI (WebSocket, embedded HTML)
    static/          Embedded web UI assets
  config/            Configuration loading (JSON + env vars)
  cron/              Cron job scheduling with JSON persistence
  gateway/           Gateway orchestration (bus + runtime + channels)
  heartbeat/         Periodic heartbeat service
  memory/            Memory system (long-term + daily)
  skills/            Custom skill loader
docs/
  telegram-setup.md  Telegram bot setup guide
  feishu-setup.md    Feishu bot setup guide
  wecom-setup.md     WeCom intelligent bot setup guide
scripts/
  setup.sh           Interactive config generator
workspace/
  skills/            Optional custom skills (`SKILL.md`)
  AGENTS.md          Agent system prompt
  SOUL.md            Agent personality

Configuration

Run make setup for interactive config, or copy config.example.json to ~/.myclaw/config.json:

{
  "provider": {
    "type": "anthropic",
    "apiKey": "your-api-key",
    "baseUrl": ""
  },
  "agent": {
    "model": "claude-sonnet-4-5-20250929"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-bot-token",
      "allowFrom": ["123456789"]
    },
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "your-app-secret",
      "verificationToken": "your-verification-token",
      "port": 9876,
      "allowFrom": []
    },
    "wecom": {
      "enabled": true,
      "token": "your-token",
      "encodingAESKey": "your-43-char-encoding-aes-key",
      "receiveId": "",
      "port": 9886,
      "allowFrom": ["zhangsan"]
    },
    "whatsapp": {
      "enabled": true,
      "allowFrom": []
    },
    "webui": {
      "enabled": true,
      "allowFrom": []
    }
  },
  "skills": {
    "enabled": true,
    "dir": ""
  }
}

Provider Types

| Type | Config | Env Vars | |------|--------|----------| | anthropic (default) | "type": "anthropic" | MYCLAW_API_KEY, ANTHROPIC_API_KEY | | openai | "type": "openai" | OPENAI_API_KEY |

When using OpenAI, set the model to an OpenAI model name (e.g., gpt-4o).

Environment Variables

| Variable | Description | |----------|-------------| | MYCLAW_API_KEY | API key (any provider) | | ANTHROPIC_API_KEY | Anthropic API key | | OPENAI_API_KEY | OpenAI API key (auto-sets type to openai) | | MYCLAW_BASE_URL | Custom API base URL | | MYCLAW_TELEGRAM_TOKEN | Telegram bot token | | MYCLAW_FEISHU_APP_ID | Feishu app ID | | MYCLAW_FEISHU_APP_SECRET | Feishu app secret | | MYCLAW_WECOM_TOKEN | WeCom intelligent bot callback token | | MYCLAW_WECOM_ENCODING_AES_KEY | WeCom intelligent bot callback EncodingAESKey | | MYCLAW_WECOM_RECEIVE_ID | Optional receive ID for strict decrypt validation |

Prefer environment variables over config files for sensitive values like API keys.

Skills

myclaw supports local skills loaded from SKILL.md files.

• skills.enabled: enable or disable skills (default true)
• skills.dir: custom skills directory; empty means <agent.workspace>/skills
• myclaw onboard automatically creates the default skills directory

Skill layout:

<workspace>/skills/<skill-name>/SKILL.md

Minimal SKILL.md example:

---
name: writer
description: writing helper
keywords: [write, draft]
---
# Writer
Use this skill for writing tasks.

After changing skills, restart myclaw gateway to apply updates.

Skill diagnostics:

./myclaw skills list
./myclaw skills info writer
./myclaw skills check
./myclaw skills list --json

JSON contract (stable):

• Common fields for all --json outputs:
  • schemaVersion (int, currently 1)
  • command (skills.list | skills.info | skills.check)
  • ok (bool)
• skills list --json:
  • enabled, dir, loaded, skills[]
  • skills[] item: name, description, keywords[]
• skills info <name> --json:
  • name, description, dir, keywords[], source, preview
  • optional: handlerError
• skills check --json:
  • enabled, dir, skillFolders, loaded, `missingSkillM