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, missingSkillMD[], result
- optional: note

Channel Setup

Telegram

See docs/telegram-setup.md for detailed setup guide.

Quick steps:

Create a bot via @BotFather on Telegram
Set token in config or MYCLAW_TELEGRAM_TOKEN env var
Run make gateway

Feishu (Lark)

See docs/feishu-setup.md for detailed setup guide.

Quick steps:

Create an app at Feishu Open Platform
Enable Bot capability
Add permissions: im:message, im:message:send_as_bot
Configure Event Subscription URL: https://your-domain/feishu/webhook
Subscribe to event: im.message.receive_v1
Set appId, appSecret, verificationToken in config
Run make gateway and make tunnel (for public webhook URL)

WeCom

See docs/wecom-setup.md for detailed setup guide.

Quick steps:

Create a WeCom intelligent bot in API mode and get token, encodingAESKey
Configure callback URL: https://your-domain/wecom/bot
Set token and encodingAESKey in both WeCom console and myclaw config
Optionally set receiveId if you need strict decrypt receive-id validation
Optional: set allowFrom to your user ID(s) as whitelist (if unset/empty, inbound from all users is allowed)
Run make gateway

WeCom notes:

Outbound uses response_url and sends markdown payloads
response_url is short-lived (often single-use); delayed or repeated replies may fail
Outbound markdown content over 20480 bytes is truncated

WhatsApp

Quick steps:

Set "whatsapp": {"enabled": true} in config
Run make gateway
Scan the QR code displayed in terminal with your WhatsApp
Session is stored locally in SQLite (auto-reconnects on restart)

Web UI

Quick steps:

Set "webui": {"enabled": true} in config
Run make gateway
Open http://localhost:18790 in your browser (PC or mobile)

Features:

Responsive design (PC + mobile)
Dark mode (follows system preference)
WebSocket real-time communication
Markdown rendering (code blocks, bold, italic, links)
Auto-reconnect on connection loss

Docker Deployment

Build and Run

docker build -t myclaw .

docker run -d \
  -e MYCLAW_API_KEY=your-api-key \
  -e MYCLAW_TELEGRAM_TOKEN=your-token \
  -p 18790:18790 \
  -p 9876:9876 \
  -p 9886:9886 \
  -v myclaw-data:/root/.myclaw \
  myclaw

Docker Compose

# Create .env from example
cp .env.example .env
# Edit .env with your credentials

# Start gateway
docker compose up -d

# Start with cloudflared tunnel (for Feishu webhook)
docker compose --profile tunnel up -d

# View logs
docker compose logs -f myclaw

Cloudflared Tunnel

For Feishu webhooks, you need a public URL:

# Temporary tunnel (dev)
make tunnel

# Or via docker compose
docker compose --profile tunnel up -d
docker compose logs tunnel | grep trycloudflare

Set the output URL + /feishu/webhook as your Feishu event subscription URL.

Security

~/.myclaw/config.json is set to chmod 600 (owner read/write only)
.gitignore excludes config.json, .env, and workspace memory files
Use environment variables for sensitive values in CI/CD and production
Never commit real API keys or tokens to version control

Testing

make test            # Run all tests
make test-race       # Run with race detection
make test-cover      # Run with coverage report
make lint            # Run golangci-lint

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

myclaw

Features

Quick Start

Makefile Targets

Binary Packaging

Architecture

Project Structure

Configuration

Provider Types

Environment Variables

Skills

Channel Setup

Telegram

Feishu (Lark)

WeCom

WhatsApp

Web UI

Docker Deployment

Build and Run

Docker Compose

Cloudflared Tunnel

Security

Testing

License

About

Uh oh!

Releases 6

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github/workflows		.github/workflows
cmd/myclaw		cmd/myclaw
docs		docs
internal		internal
scripts		scripts
workspace		workspace
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
config.example.json		config.example.json
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

myclaw

Features

Quick Start

Makefile Targets

Binary Packaging

Architecture

Project Structure

Configuration

Provider Types

Environment Variables

Skills

Channel Setup

Telegram

Feishu (Lark)

WeCom

WhatsApp

Web UI

Docker Deployment

Build and Run

Docker Compose

Cloudflared Tunnel

Security

Testing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages