Your personal AI assistant with Telegram interface, multi-model support, ClawHub skills, and SOUL.md personality.

Inspired by OpenClaw and built with the same philosophy - a self-hosted AI agent that you control.

• Node.js 22+ (required)
• Telegram account (for bot interface)
• API Key for one of:
  • Anthropic Claude (recommended)
  • Kimi (Moonshot)
  • MiniMax

# Clone the repository
git clone https://github.com/Softorize/mikiclaw
cd mikiclaw

# Install dependencies
npm install

# Build the project
npm run build

npm run setup

The setup wizard will guide you through:

1. AI Provider Selection - Choose your preferred AI model
2. Telegram Bot Token - Get from @BotFather
3. API Key - Enter your chosen provider's API key
4. Personality - Select your assistant's personality
5. Security Settings - Configure tool policies (allowlist recommended)
6. Encryption - Enable credential encryption (highly recommended)
7. Rate Limiting - Protect against abuse

npm start

Message your Telegram bot to get started!

• Features
• Quick Start
• Documentation
• Configuration
• Security
• Commands
• Personality (SOUL.md)
• Skills System
• Deployment Options
• Troubleshooting
• Development
• Contributing

• Architecture Guide - components, request lifecycle, and extension points
• Automation Workflows - webhook/heartbeat triggers, conditions, actions, and signed request examples
• Operations & Observability - health, metrics, logging, approvals, and runbooks
• Deployment Guide
• Troubleshooting Guide
• Memory & Learning

Control a headless browser to interact with websites:

• browser_navigate - Open a webpage
• browser_screenshot - Capture current page
• browser_click - Click elements
• browser_type - Type in input fields
• browser_content - Get page text
• browser_evaluate - Run JavaScript
• browser_fill - Fill form fields
• browser_select - Select dropdown options
• browser_scroll - Scroll page
• browser_back/forward - Navigation
• browser_snapshot - Structured page snapshot

Use these commands in Telegram (default channel adapter):

{
  "telegram": {
    "botToken": "encrypted:...",  // Your Telegram bot token
    "allowedUsers": []            // Limit to specific users (optional)
  },
  "discord": {
    "botToken": "...",            // Discord bot token
    "allowedGuilds": [],          // Limit to specific guilds (optional)
    "allowedChannels": []         // Limit to specific channels (optional)
  },
  "slack": {
    "appToken": "...",            // Slack app-level token
    "botToken": "...",            // Slack bot token
    "signingSecret": "...",       // Slack signing secret
    "allowedChannels": []         // Limit to specific channels (optional)
  },
  "webchat": {
    "enabled": true,              // Enable web interface
    "port": 18791,                // WebChat port
    "bindAddress": "127.0.0.1"    // Bind address
  },
  "ai": {
    "provider": "anthropic",      // anthropic | openai | kimi | minimax | local
    "model": "claude-sonnet-4-20250514",
    "routing": {
      "enabled": true,            // Enable provider routing + failover
      "strategy": "balanced",     // quality-first | speed-first | cost-first | balanced
      "fallbackProviders": ["openai", "kimi", "minimax", "local"]
    },
    "providers": {
      "anthropic": { "apiKey": "encrypted:..." },
      "openai": { "apiKey": "encrypted:..." },
      "kimi": { "apiKey": "encrypted:..." },
      "minimax": { "apiKey": "encrypted:...", "groupId": "..." },
      "local": {
        "baseUrl": "http://localhost:8000/v1",
        "apiKey": "not-needed"
      }
    }
  },
  "webhooks": {
    "enabled": false,
    "port": 19091,
    "secret": "replace-me",
    "maxPayloadBytes": 1048576,
    "rateLimitPerMinute": 60,
    "endpoints": [
      {
        "path": "/incoming/build-fail",
        "url": "https://example.com/webhooks/build-fail",
        "method": "POST",
        "events": ["*"],
        "secret": "replace-me"
      }
    ]
  },
  "automation": {
    "enabled": false,
    "workflows": [
      {
        "id": "build-failure-alert",
        "enabled": true,
        "trigger": { "type": "webhook", "path": "/incoming/build-fail" },
        "condition": { "field": "data.status", "equals": "failed" },
        "action": {
          "type": "emit_webhook_event",
          "eventType": "alerts.build.failed",
          "message": "Build failed for {{data.project}} on {{data.branch}}"
        }
      }
    ]
  },
  "heartbeat": {
    "enabled": true,              // Enable periodic check-ins
    "intervalMinutes": 30
  },
  "memory": {
    "perUserEntryCap": 500,       // Max entries per user in long-term memory
    "maxConnectedContextEntries": 8,
    "semanticMinSimilarity": 0.75
  },
  "channels": {
    "default": "telegram",
    "enabled": ["telegram"]
  },
  "security": {
    "encryptCredentials": true,   // Encrypt API keys
    "toolPolicy": "allowlist-only", // allowlist-only | block-destructive | allow-all
    "allowedCommands": ["git status", "ls", "cat", "echo"],
    "blockedCommands": ["rm -rf /", "dd if=", "mkfs"]
  },
  "rateLimit": {
    "enabled": true,              // Enable rate limiting
    "maxRequestsPerMinute": 20
  }
}

# Copy .env.example to .env
cp .env.example .env

1. Always use allowlist-only policy for production
2. Enable credential encryption (default)
3. Restrict allowed users in config if possible
4. Keep the master key file secure: ~/.mikiclaw_key
5. Review allowed commands regularly
6. Monitor logs in ~/.mikiclaw/logs/

{
  "security": {
    // MOST SECURE: Only explicitly allowed commands
    "toolPolicy": "allowlist-only",
    "allowedCommands": [
      "git status", "git log", "git diff",
      "ls", "cat", "head", "tail",
      "grep", "find", "pwd", "echo",
      "npm run", "tsc"
    ],
    
    // Defense in depth: always block these
    "blockedCommands": [
      "rm -rf /", "dd if=", "mkfs", "fdisk",
      "curl | sh", "wget | sh",
      "base64 -d", "eval $(",
      "/dev/tcp/", "nc -e", "bash -i"
    ],
    
    // Encrypt all credentials
    "encryptCredentials": true
  }
}

📖 See SECURITY.md for detailed security documentation.

Define your assistant's personality by editing ~/.mikiclaw/workspace/SOUL.md:

# Identity
- Name: Miki
- Role: Your personal AI assistant
- Voice: Warm, curious, friendly but competent

# Principles
1. Be helpful without being overwhelming.
2. Ask clarifying questions when needed.
3. Admit what you don't know.
4. Keep responses concise and actionable.

# Boundaries
- Don't execute destructive commands without confirmation.
- Don't share private system details.
- Stop and ask if something seems unsafe.

# Interaction Style
- Use light formatting (bold for emphasis)
- Use emojis sparingly (1-2 per message)
- Format code in code blocks
- End with a question or offer

During setup, choose from:

Extend mikiclaw with skills from ClawHub.

# List installed skills
node dist/index.js skills list

# Install a skill
node dist/index.js skills install <skill-name>

# Show config location
node dist/index.js config

Create a skill manifest at ~/.mikiclaw/skills/<name>/claw.json:

{
  "name": "my-custom-skill",
  "version": "1.0.0",
  "description": "My custom skill description",
  "author": "Your Name",
  "tools": [
    {
      "name": "my_tool",
      "description": "What this tool does",
      "command": "echo",
      "inputSchema": {
        "type": "object",
        "properties": {
          "input": { "type": "string" }
        }
      }
    }
  ]
}

Use this for development only:

npm install
npm run build
npm run setup
npm start

Build once before configuring any service:

npm install
npm run build
npm run setup

Create /etc/systemd/system/mikiclaw.service:

[Unit]
Description=mikiclaw AI assistant service
After=network.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/ABSOLUTE/PATH/TO/mikiclaw
ExecStart=/usr/bin/env node /ABSOLUTE/PATH/TO/mikiclaw/dist/index.js start
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

# Enable + start
sudo systemctl daemon-reload
sudo systemctl enable mikiclaw
sudo systemctl start mikiclaw

# Verify + logs
sudo systemctl status mikiclaw
sudo journalctl -u mikiclaw -f

Create ~/Library/LaunchAgents/com.softorize.mikiclaw.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.softorize.mikiclaw</string>

    <key>ProgramArguments</key>
    <array>
      <string>/usr/bin/env</string>
      <string>node</string>
      <string>/ABSOLUTE/PATH/TO/mikiclaw/dist/index.js</string>
      <string>start</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/ABSOLUTE/PATH/TO/mikiclaw</string>

    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/ABSOLUTE/PATH/TO/mikiclaw/logs/launchd-out.log</string>
    <key>StandardErrorPath</key>
    <string>/ABSOLUTE/PATH/TO/mikiclaw/logs/launchd-err.log</string>
  </dict>
</plist>

mkdir -p ./logs

# Load + start
launchctl load -w ~/Library/LaunchAgents/com.softorize.mikiclaw.plist
launchctl start com.softorize.mikiclaw

# Status + logs
launchctl list | grep mikiclaw
tail -f ./logs/launchd-out.log

Install NSSM, then in elevated PowerShell:

npm install
npm run build
npm run setup

nssm install MikiClaw "C:\Program Files\nodejs\node.exe" "C:\ABSOLUTE\PATH\mikiclaw\dist\index.js" start
nssm set MikiClaw AppDirectory "C:\ABSOLUTE\PATH\mikiclaw"
nssm set MikiClaw AppStdout "C:\ABSOLUTE\PATH\mikiclaw\logs\service-out.log"
nssm set MikiClaw AppStderr "C:\ABSOLUTE\PATH\mikiclaw\logs\service-err.log"
nssm start MikiClaw

npm install -g pm2
pm2 start dist/index.js --name "mikiclaw" -- start
pm2 save
pm2 startup
pm2 status
pm2 logs mikiclaw

docker build -t mikiclaw .
docker run -d \
  --name mikiclaw \
  -v mikiclaw-data:/home/nodejs/.mikiclaw \
  mikiclaw

See docs/DEPLOYMENT.md for Railway/Render/GCP/AWS examples.

After pulling new code:

git pull
npm install
npm run build

Then restart based on service manager:

# systemd
sudo systemctl restart mikiclaw

# launchd
launchctl kickstart -k gui/$(id -u)/com.softorize.mikiclaw

# PM2
pm2 restart mikiclaw

# Check health (with auth token)
curl -H "X-Auth-Token: YOUR_TOKEN" http://localhost:19090/health

# Get auth token (localhost only)
curl http://localhost:19090/token

Logs are stored in ~/.mikiclaw/logs/ with daily rotation.

# View today's log
tail -f ~/.mikiclaw/logs/mikiclaw-$(date +%Y-%m-%d).log

# Search logs
grep "ERROR" ~/.mikiclaw/logs/*.log

1. Check if bot is running: npm run status
2. Verify Telegram token is correct
3. Check logs: ~/.mikiclaw/logs/
4. Ensure bot is not rate limited

1. Review your tool policy in config
2. Add command to allowedCommands list
3. Consider switching to block-destructive policy temporarily

1. Verify API key is correct and has credits
2. Check network connectivity
3. Review rate limits on your API plan
4. Check logs for detailed error messages

# Check key file permissions
ls -la ~/.mikiclaw_key

# Fix permissions if needed
chmod 600 ~/.mikiclaw_key

1. By default, only localhost can access without auth
2. Get auth token: curl http://localhost:19090/token
3. Use token in header: curl -H "X-Auth-Token: TOKEN" http://localhost:19090/health

1. Check logs: ~/.mikiclaw/logs/
2. Run status: npm run status
3. Review configuration: cat ~/.mikiclaw/config.json
4. Open an issue on GitHub

mikiclaw/
├── src/
│   ├── agent/          # Agent logic and tools
│   ├── ai/             # AI providers + router/failover
│   ├── automation/     # Workflow engine (trigger/condition/action)
│   ├── bot/            # Telegram bot handlers
│   ├── channels/       # Channel adapters
│   ├── commands/       # CLI commands
│   ├── config/         # Configuration and encryption
│   ├── heartbeat/      # Scheduled tasks
│   ├── observability/  # Runtime metrics store
│   ├── personality/    # SOUL.md and memory
│   ├── security/       # Access grants + risky action approvals
│   ├── skills/         # Skills system
│   ├── utils/          # Utilities (validation, retry, logging)
│   ├── webhooks/       # Signed webhook server + event delivery
│   └── index.ts        # Entry point
├── tests/              # Test suite
├── dist/               # Compiled JavaScript
└── workspace/          # Runtime workspace

# Run in development mode (with hot reload)
npm run dev

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run all tests
npm test

# Run specific test file
npx vitest tests/validation.test.ts

# Run with coverage
npm run test:coverage

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

# Fork and clone
git clone https://github.com/YOUR_USERNAME/mikiclaw
cd mikiclaw

# Install dependencies
npm install

# Create a branch
git checkout -b feature/your-feature

# Make changes and test
npm run dev
npm test

# Commit and push
git commit -m "feat: add your feature"
git push origin feature/your-feature

MIT License - see LICENSE for details.

• Inspired by OpenClaw
• Built with Telegraf for Telegram
• AI integration via @anthropic-ai/sdk

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: This README and inline code comments

Made with ❤️ by Softorize