mlclaw

ML Claw

ML Claw deploys an OpenClaw agent on Hugging Face with durable state in a private Storage Bucket. The default deployment is a protected Hugging Face Space: its source stays private, its app URL is reachable, and the browser gateway is protected by ML Claw's Hugging Face OAuth session.

ml-intern is Hugging Face's open-source ML engineer for reading papers, training models, and shipping models.

The browser never receives an OpenClaw gateway token. ML Claw authenticates the signed-in Hugging Face user, then proxies HTTP and WebSocket traffic to OpenClaw on loopback using OpenClaw trusted-proxy auth.

After signing in, an administrator can authorize the hosted Hugging Face MCP server and Research Agent with the same Hugging Face account. Ordinary users grant only identity scopes. Integration credentials stay in the trusted ML Claw wrapper; the unprivileged OpenClaw process receives only loopback MCP access.

Install

With Node.js:

npx mlclaw@latest bootstrap

Without Node.js, the launcher fetches a pinned Node runtime into your user cache and runs the same npm package:

bash <(curl -fsSL https://raw.githubusercontent.com/huggingface/mlclaw/main/mlclaw.sh)

On Windows:

irm https://raw.githubusercontent.com/huggingface/mlclaw/main/mlclaw.ps1 | iex

You need a Hugging Face account and a token available through HF_TOKEN, HF_TOKEN_PATH, $HF_HOME/token, or hf auth login. If an interactive bootstrap cannot find a token, it offers to install the official Hugging Face CLI, asks whether you need to create an account, opens the appropriate browser flow, and resumes after sign-in. Non-interactive runs never install software and still require a token up front. You never paste that token into someone else's app; the bootstrapper runs locally.

The hf CLI login is a provisioning credential: ML Claw uses it to create and configure resources owned by your account. HF Broker uses a separate, durable fine-grained credential whose selected permissions form unYOLO's hard upstream authority ceiling. Interactive bootstrap opens an empty Hugging Face token form so you can choose those permissions and resources, then accepts the new token through a hidden local prompt. Creating or replacing this credential never changes the active hf CLI login. For automation, pass a 0600 file through --broker-hf-token-file; ML Claw does not accept the token as a command-line value.

The broker owns the selected credential; OpenClaw receives only a separate agent credential that can call the broker's typed, policy-checked routes. It cannot read the token or use the admin-only operator API. Rerunning bootstrap reuses a healthy saved broker credential without reopening the form. A missing, invalid, or wrong-account credential must be repaired before ML Claw continues; it never silently substitutes the active CLI login. When a selected permission does not cover an operation, HF Broker denies that operation without weakening the rest of the deployment. Existing dedicated inference tokens remain supported through MLCLAW_ROUTER_TOKEN, HF_ROUTER_TOKEN, or --router-token-file.

Default Flow

npx mlclaw@latest bootstrap --name mlclaw

This creates:

• a protected Docker Space for the browser gateway when the account can host it;
• a private Storage Bucket for OpenClaw state after the Space is accepted;
• no explicit Space hardware request unless you pass --hardware;
• a Docker Space that starts from the prebuilt ghcr.io/huggingface/mlclaw image;
• Hugging Face OAuth metadata for browser auth, Hugging Face MCP, and Research Agent access in the Space README;
• Space variables, a bucket volume mount for state sync, and separate write-only secrets for session signing and OAuth credential encryption;
• an MLCLAW_BROKER_HF_TOKEN Space secret consumed only by the isolated HF Broker process;
• a local deployment manifest under ~/.config/mlclaw.

Hugging Face currently requires PRO for Docker Space hosting. When creation is rejected for that reason, interactive bootstrap checks for a usable local Docker or rootless Podman engine and offers to run the same gateway locally. No bucket is created before hosted eligibility is known. Bootstrap does not install a container engine or change daemon permissions.

Automation fails instead of changing execution location implicitly. Opt in to the same fallback with:

npx mlclaw@latest bootstrap --yes --allow-local-fallback

Open the Space, sign in with your Hugging Face account, and use the OpenClaw browser gateway directly. The gateway includes a small ML Claw control link for settings, status, credentials, and sign out.

Expose the Space source only when you explicitly want a public demo or template:

npx mlclaw@latest bootstrap --name mlclaw --public-space

Choose a Hugging Face Router model with --model:

npx mlclaw@latest bootstrap \
  --name mlclaw \
  --model huggingface/zai-org/GLM-5.2:fireworks-ai

Recommended router-compatible options:

• huggingface/zai-org/GLM-5.2:fireworks-ai: default long-context model with tool support.
• huggingface/google/gemma-4-26B-A4B-it:deepinfra: lower-cost Gemma option with tool and structured-output support.
• huggingface/Qwen/Qwen3.6-35B-A3B:deepinfra: strong Qwen 3.6 option with tool and structured-output support.
• huggingface/Qwen/Qwen3.6-27B:deepinfra: live Qwen 3.6 option with tool and structured-output support.
• huggingface/zai-org/GLM-5.2:deepinfra: long-context GLM option with tool and structured-output support.
• huggingface/moonshotai/Kimi-K2.7-Code:deepinfra: coding-focused Kimi option with tool and structured-output support.
• huggingface/openai/gpt-oss-120b:deepinfra: larger GPT-OSS option with tool and structured-output support.
• huggingface/openai/gpt-oss-20b:deepinfra: lower-cost GPT-OSS option with tool and structured-output support.
• huggingface/deepseek-ai/DeepSeek-V4-Flash:deepinfra: low-cost long-context DeepSeek V4 option.
• huggingface/deepseek-ai/DeepSeek-V4-Pro:deepinfra: higher-quality long-context DeepSeek V4 option.
• huggingface/MiniMaxAI/MiniMax-M3:together: long-context MiniMax option with tool and structured-output support.

Fireworks options are also included for Kimi K2.7 Code, GPT-OSS 120B and 20B, DeepSeek V4 Flash and Pro, and MiniMax M3. Use the provider suffix :fireworks-ai. The current Router catalog does not expose the Gemma 4 or Qwen 3.6 presets through Fireworks.

Optional Telegram

A Telegram deployment can use one BotFather bot for conversations and unYOLO approval buttons. ML Claw runs Telegram Bot Mux inside the trusted runtime. The mux owns Telegram polling and gives OpenClaw and unYOLO separate local queues and credentials.

Start a private chat with the bot, then pass one positive Telegram user ID:

npx mlclaw@latest bootstrap \
  --telegram-token-file ~/secrets/mlclaw-bot.env \
  --telegram-user-id 1234567890 \
  --hardware cpu-upgrade \
  --sleep-time -1

The token file may contain TELEGRAM_BOT_TOKEN=... or a raw token. The physical bot token stays in a mux-owned runtime file. OpenClaw, HF Broker, and the supervised unyolo-telegram ingress receive short-lived local client tokens instead. The mux routes bk: approval callbacks only to unYOLO and sends other updates to OpenClaw.

Existing two-bot deployments remain supported. Pass --approval-telegram-token-file to keep a distinct approval bot. That file may contain MLCLAW_UNYOLO_TELEGRAM_BOT_TOKEN=... or a raw token, and ML Claw verifies that it identifies a different bot.

ML Claw manages Telegram API roots inside the runtime, so user-supplied TELEGRAM_API_ROOT and TELEGRAM_PROXY values are rejected. The