Neoclaw

📖 Table of Contents

• 📖 Table of Contents
• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 🌐 Gateway Configuration
• ⏰ Cron Jobs
• 🔌 MCP Servers & Skills
• 🧠 Memory System
• 🏗️ Architecture
• 🤝 Contributing
• 📄 License

✨ Features

• Multiple AI backends: Supports Claude Code (default) and Opencode, both with MCP Servers, Skills, streaming responses, and tool calls.
• Multi-platform gateways: Feishu (DM/group/topic), WeChat Work, and Web Dashboard; all three can run simultaneously.
• Streaming responses: Feishu uses streaming cards for a typewriter effect; Dashboard pushes deltas in real time; WeChat Work simulates streaming by chunking messages.
• Requirement clarification: Proactively opens interactive questionnaires via the AskUserQuestion tool.
• Multimodal: Supports Feishu image messages; the AI can directly understand image content.
• Session isolation & concurrency control: One working directory per conversation, plus a serial queue to prevent concurrent conflicts.
• Cron jobs: Supports cron expressions and one-off jobs, created directly from chat via the AI.
• Three-layer memory system: Identity, semantic knowledge, and episodic summaries, backed by SQLite FTS5 full-text search.
• Self-evolving: NeoClaw can modify its own code through conversation, and apply changes via the /restart command.
• Slash commands: /clear (clear session), /restart (restart service), /status (status), /help (help).

📦 Installation

Prerequisites:

• pnpm v10+
• Bun v1.0+
• One AI backend:
  • Claude Code (default)
  • Opencode
• At least one messaging platform account (Feishu or WeChat Work)

# 1. Clone the repo
git clone https://github.com/amszuidas/neoclaw.git
cd neoclaw

# 2. Install dependencies
pnpm install

Run CLI commands from the repo root using pnpm cli:

🚀 Quick Start

Initialize

pnpm cli onboard

Configure

Edit ~/.neoclaw/config.json and configure at least the AI backend and one gateway:

{
  "agent": "claude_code", // "claude_code" (default) or "opencode"
  "timeoutSecs": 600,
  // Agent-specific settings
  "agents": {
    "claude_code": {
      "model": "claude-sonnet-4-6", // Optional model override
    },
  },
  // Configure either Feishu or WeChat Work (or both)
  "channels": {
    "feishu": {
      "appId": "YOUR_FEISHU_APP_ID",
      "appSecret": "YOUR_FEISHU_APP_SECRET",
      "verificationToken": "",
      "encryptKey": "",
      "domain": "feishu", // "feishu" or "lark"
    },
    "wework": {
      "botId": "YOUR_WEWORK_BOT_ID",
      "secret": "YOUR_WEWORK_SECRET",
    },
    // Optional: enable Web Dashboard
    "dashboard": {
      "enabled": false,
      "port": 3000,
    },
  },
}

See how to obtain credentials in Gateway Configuration.

Start

pnpm cli start

The service daemonizes automatically and runs in the background. Logs: ~/.neoclaw/logs/neoclaw.log

# Stop
pnpm cli stop

# Dev mode (auto-restart on file changes)
pnpm run dev

With Dashboard enabled, open http://localhost:5173 in your browser to chat with NeoClaw.

🌐 Gateway Configuration

Feishu

See FEISHU_CONFIG.md for detailed instructions.

Config fields:

Env var overrides: FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_VERIFICATION_TOKEN, FEISHU_ENCRYPT_KEY, FEISHU_DOMAIN, FEISHU_GROUP_AUTO_REPLY

Key steps:

1. Create an app in the Feishu Open Platform
2. Configure event subscriptions (message receive, card action callbacks)
3. Fill credentials into the config file

WeChat Work

See WEWORK_BOT.md for detailed instructions.

Config fields:

Env var overrides: WEWORK_BOT_ID, WEWORK_SECRET, WEWORK_GROUP_AUTO_REPLY

Key steps:

1. In the WeChat Work Admin Console -> Application Management -> Intelligent Assistant, create a bot
2. Choose API mode -> Long connection
3. Fill botId and secret into the config file

Dashboard

{
  "dashboard": {
    "enabled": true,
    "port": 3000, // WebSocket server port
    "cors": true,
  },
}

Env var overrides: NEOCLAW_DASHBOARD_ENABLED, NEOCLAW_DASHBOARD_PORT, NEOCLAW_DASHBOARD_CORS

After starting, visit http://localhost:5173 for real-time streaming responses, session management, Markdown rendering, and a thinking panel.

Feature Comparison

⏰ Cron Jobs

In chat, the AI will automatically call the neoclaw cron command to create and manage jobs. You can also run it directly in your terminal:

# Create a one-off job
neoclaw cron create --message "Generate monthly report" --run-at "2024-03-01T09:00:00+08:00" --label "Monthly report"

# Create a recurring job (Mon-Fri 09:00)
neoclaw cron create --message "Daily morning brief" --cron-expr "0 9 * * 1-5" --label "Morning brief"

# List all jobs
neoclaw cron list

# Include disabled jobs
neoclaw cron list --include-disabled

# Delete a job
neoclaw cron delete --job-id <jobId>

# Update a job
neoclaw cron update --job-id <jobId> --label "New name" --enabled true

Cron expression format (5 fields): min hour day month weekday. For example, 0 9 * * 1-5 means 09:00 Monday to Friday.

🔌 MCP Servers & Skills

NeoClaw configures MCP Servers and Skills at a unified layer, translates them into the underlying agent formats, and hot-loads changes every time a new agent process starts (no daemon restart required).

MCP Servers

Add entries under mcpServers in ~/.neoclaw/config.json:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": { "API_KEY": "xxx" },
    },
    "remote-server": {
      "type": "http",
      "url": "https://mcp.example.com/sse",
      "headers": { "Authorization": "Bearer xxx" },
    },
  },
}

Supported types: stdio, http, sse.

Skills

Place skill directories under ~/.neoclaw/skills/ (customizable via skillsDir or the NEOCLAW_SKILLS_DIR env var). Each skill directory must include a SKILL.md file:

~/.neoclaw/skills/
  deploy/
    SKILL.md
  code-review/
    SKILL.md

Skills are synced into workspaces on new process start: newly added skills are linked, deleted skills are cleaned up, and edits to SKILL.md take effect immediately via symlinks.

🧠 Memory System

NeoClaw includes a built-in three-layer memory system, injected into each workspace via an MCP server (neoclaw-memory):

~/.neoclaw/memory/
├── identity/
│   └── SOUL.md       # Identity: personality, values, communication style
├── knowledge/        # Semantic memory: persistent knowledge by topic
├── episodes/         # Episodic memory: session summaries generated on session end
└── index.sqlite      # FTS5 full-text search index

Four MCP tools: memory_search (full-text search), memory_read (read file), memory_save (save content), memory_list (list memories)

Memory rules:

• Relevant memories are searched automatically at the start of each conversation to provide context
• Important owner information is saved into knowledge memory
• Other users can search but cannot write
• Memory contents are not leaked to non-owner users

🏗️ Architecture

graph LR
    Phone["📱 Phone"]
    IM["Feishu / WeChat Work / Dashboard\nMessage gateways: receive, send, render"]
    GW["NeoClaw Gateway\nRouting, session management, permission control"]
    Agent["Local Agent\nClaude Code / Opencode"]
    PC["💻 Your computer"]

    Phone -->|Send messages| IM
    IM -->|InboundMessage| GW
    GW -->|Call| Agent
    Agent -->|Stream output| GW
    GW -->|Render & push| IM
    IM -->|Streaming cards| Phone
    Agent --- PC

🤝 Contributing

Issues and pull requests are welcome!

1. Fork this repository
2. Create a branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a pull request

📄 License

This project is open-sourced under the Apache-2.0 license.