Skip to content

README.md

Latest commit

 

History

History
142 lines (110 loc) · 5.06 KB

README.md

File metadata and controls

142 lines (110 loc) · 5.06 KB

MetaClaw Plugin

One-Click Install

Download the zip, extract, enable — MetaClaw environment is set up automatically.

macOS / Linux

curl -LO https://github.com/aiming-lab/MetaClaw/releases/download/v0.4.0/metaclaw-plugin.zip
unzip metaclaw-plugin.zip -d ~/.openclaw/extensions
openclaw plugins enable metaclaw-openclaw
openclaw gateway restart

China users: If GitHub downloads are slow or timeout, use a mirror:

curl -LO https://ghfast.top/https://github.com/aiming-lab/MetaClaw/releases/download/v0.4.0/metaclaw-plugin.zip

Windows (PowerShell)

Invoke-WebRequest -Uri https://github.com/aiming-lab/MetaClaw/releases/download/v0.4.0/metaclaw-plugin.zip -OutFile metaclaw-plugin.zip
Expand-Archive metaclaw-plugin.zip -DestinationPath $env:USERPROFILE\.openclaw\extensions
openclaw plugins enable metaclaw-openclaw
openclaw gateway restart

China users: If GitHub downloads are slow or timeout, replace the download URL with:

https://ghfast.top/https://github.com/aiming-lab/MetaClaw/releases/download/v0.4.0/metaclaw-plugin.zip

Then run

metaclaw setup
metaclaw start

What the plugin does automatically

  • Creates an isolated Python virtual environment (.venv)
  • Installs MetaClaw ([rl,evolve,scheduler]) via pip
  • Auto-installs the official WeChat plugin (@tencent-weixin/openclaw-weixin) when enabled
  • Installs metaclaw CLI wrapper and configures PATH (macOS / Linux / Windows)
  • Patches outbound LLM fetch to inject X-Session-Id / X-Turn-Type headers

Requirements

  • Python ≥ 3.11
  • OpenClaw (any version)
  • macOS / Linux / Windows
  • RAM ≥ 4 GB recommended. MetaClaw's dependencies (PyTorch, etc.) are heavy. On machines with ≤ 2 GB RAM, pip may get killed by the OS (OOM). Add swap space before installing: 
    sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Full auto mode (optional)

openclaw config set plugins.entries.metaclaw-openclaw.config.oneClickMetaclaw true

Enables: venv + pip + default config + metaclaw start on gateway load.

Config

~/.openclaw/openclaw.json:

Minimal (pip install on gateway load; manual metaclaw setup + start):

{
  "plugins": {
    "entries": {
      "metaclaw-openclaw": {
        "enabled": true
      }
    }
  }
}

Full auto (oneClickMetaclaw):

{
  "plugins": {
    "entries": {
      "metaclaw-openclaw": {
        "enabled": true,
        "config": {
          "oneClickMetaclaw": true
        }
      }
    }
  }
}
Key Notes
oneClickMetaclaw Default false. true: venv + pip + default ~/.metaclaw/config.yaml if missing + metaclaw start.
autoInstallMetaclaw Default true. false skips venv creation and pip (ignored when oneClickMetaclaw is true).
autoStartMetaclaw Default false; true when oneClickMetaclaw. When enabled, runs metaclaw start from the venv after pip.
pipPython Default python3. Used to create the venv. Use a python3.12-style command or an absolute interpreter path if python3 is too old.
pipInstallSpec Default aiming-metaclaw[rl,evolve,scheduler] from PyPI.
pipExtraArgs Extra pip flags.

Plugin

On gateway load, the plugin:

  • Creates a Python virtual environment (.venv) inside the plugin directory if one does not already exist.
  • Installs MetaClaw into the venv via pip install (from PyPI, works with Chinese mirrors).
  • Auto-installs the official WeChat plugin (@tencent-weixin/openclaw-weixin) when wechat.enabled is true.
  • Creates a metaclaw wrapper script and auto-configures PATH (macOS / Linux / Windows) so you can run metaclaw directly.
  • Patches fetch to inject X-Session-Id / X-Turn-Type on outbound LLM POSTs (before_prompt_build / agent_end).
  • metaclaw setup / metaclaw start are up to you unless oneClickMetaclaw is true.

Troubleshooting

Issue What to do
plugin not found: metaclaw-openclaw Put the folder under ~/.openclaw/extensions/metaclaw-openclaw or set plugins.load.paths to its absolute path.
tinker / Python version [rl,…] needs Python ≥ 3.11.
venv creation fails Install python3-venv: apt install python3-venv (Debian/Ubuntu) or ensure your Python has the venv module.
pip install fails in venv Check pipPython points to Python ≥ 3.11; use pipExtraArgs for custom pip flags.
pip install timeout (China) pip defaults to PyPI which has Chinese mirrors. If still slow, set pipExtraArgs to ["-i", "https://pypi.tuna.tsinghua.edu.cn/simple"].
spawn metaclaw ENOENT Only if autoStartMetaclaw — the plugin uses the venv's Python to run metaclaw.
Server freezes / pip killed during install Not enough RAM. Add 4 GB swap: sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile, then retry.