# mlclaw

Adopt this skill: https://proskills.md/skills/other/huggingface-mlclaw-agents-skills-mlclaw

Page: https://proskills.md/skills/other/huggingface-mlclaw-agents-skills-mlclaw
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/mlclaw/SKILL.md
size: 8000
upstream: https://github.com/huggingface/mlclaw/blob/main/.agents/skills/mlclaw/SKILL.md

````text
---
name: mlclaw
description: Use when setting up, operating, migrating, repairing, or explaining an OpenClaw deployment on Hugging Face with the ML Claw `mlclaw` CLI. Covers the browser Space gateway, Hugging Face OAuth, local gateway mode, private Storage Buckets, Telegram as an optional connector, Docker context pinning, model selection through the Hugging Face Router, OpenAI API key setup, costs, diagnostics, and state safety.
---

# ML Claw

## Core Rule

Use the `mlclaw` CLI as the source of truth. Do not hand-create Hugging Face
Spaces, buckets, secrets, or Docker containers unless debugging a failed
`mlclaw` operation. Keep bootstrap credentials local to the user's machine.
Space OAuth credentials may be stored only through ML Claw's encrypted,
process-isolated integration store.

Default to the browser Space gateway unless the user explicitly asks for local
gateway mode.

## What ML Claw Creates

An ML Claw deployment has:

- a private Hugging Face Storage Bucket for durable OpenClaw state snapshots;
- a private Hugging Face Docker Space for the default browser gateway;
- no explicit Space hardware request by default; Hugging Face assigns the
  default free CPU hardware unless `--hardware` or a feature requiring paid
  hardware is used;
- a prebuilt `ghcr.io/huggingface/mlclaw` runtime image by default;
- Hugging Face OAuth enabled on the Space;
- automatic Hugging Face MCP and Research Agent integrations authorized by an
  admin-only OAuth step after ordinary Hugging Face sign-in;
- a local deployment manifest under `~/.config/mlclaw/deployments/`;
- local secrets under `~/.config/mlclaw/secrets/`;
- app Spaces mount the private Storage Bucket read-write at
  `/data/mlclaw-state` for snapshot storage without storing the user's broad
  Hub token in the Space;
- preinstalled Hugging Face tooling in the OpenClaw workspace, including
  `hf`, `hf-discover`, `uv`, HF Python libraries, and baseline Hugging Face
  Agent Skills mirrored into both `.agents/skills` and `skills`;
- optional local Docker gateway mode for users who want the gateway on their
  own machine;
- Hugging Face Router model configuration through an isolated HF Broker.

The bucket is the durable state source. The live gateway is disposable. Do not
mount a bucket as the live OpenClaw database filesystem. Space gateway mode
uses the mounted bucket only for verified snapshots; live SQLite and workspace
state stay on local container disk under
`/home/node/.local/share/mlclaw/live`.

ML Claw waits for OpenClaw's native first-run identity bootstrap to finish,
then seeds a managed Hugging Face tooling note into workspace `AGENTS.md` so
new sessions see the available Hugging Face skills directly in context. If a
long-running session predates the seed, start a new OpenClaw session so its
skill snapshot is rebuilt.

## Required Inputs

Collect or confirm:

- Hugging Face token access: `HF_TOKEN`, `HF_TOKEN_PATH`, `$HF_HOME/token`, or
  `hf auth login`.
- A separate fine-grained Hugging Face token is installed as the broker-owned
  `MLCLAW_BROKER_HF_TOKEN`; the active CLI login is used only to provision
  resources. Legacy dedicated Router tokens remain supported for inference.
- Agent name, unless a Telegram bot token is supplied and the user wants the
  name derived from the bot username.
- Gateway mode:
  - `space`: default browser gateway, private Space, HF OAuth protected.
  - `local`: Docker gateway on the user's machine.
- Optional model override.
- Optional Docker context for local mode.
- Optional Telegram bot token and one positive private-chat user ID. A separate
  unYOLO approval bot token remains available for existing two-bot deployments.
- Optional explicit owner, name, or bucket only when the user needs them.

If a Telegram conversation token is provided, ML Claw calls Telegram `getMe`,
removes a trailing `_bot` from the bot username, and can derive the agent,
bucket, and Space names from that. It also verifies that the approval token
belongs to a different bot. Ask the user to start a private chat with both bots
before bootstrap.

## Install And Run

With Node.js:

```bash
npx mlclaw@latest bootstrap --name mlclaw
```

Without Node.js on macOS/Linux:

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

On Windows PowerShell:

```powershell
irm https://raw.githubusercontent.com/osolmaz/mlclaw/main/mlclaw.ps1 | iex
```

For repo-local development, use:

```bash
npm install
npm run build
node dist/mlclaw.mjs --help
```

## Recommended First Setup: Browser Space Gateway

Interactive:

```bash
npx mlclaw@latest bootstrap --name mlclaw
```

Automation:

```bash
npx mlclaw@latest bootstrap \
  --name mlclaw \
  --model huggingface/google/gemma-4-26B-A4B-it:deepinfra \
  --yes
```

After the Space builds, open it in the browser and sign in with the user's
Hugging Face account. The Space server proxies authenticated browser traffic to
OpenClaw on loopback using trusted-proxy auth. Do not ask the user for an
OpenClaw gateway token for the browser Space path.

Generated Spaces use the prebuilt `ghcr.io/huggingface/mlclaw:<package>-openclaw-<version>`
image by default. Use `--bundled-runtime` only for development or emergency
fallbacks where the Space must build all runtime files directly from the
uploaded Space repository.

Create a public Space only when the user explicitly asks for a public demo or
template-style deployment:

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

## Optional Telegram

Telegram is optional and should not be required for the default setup. One
BotFather bot can carry OpenClaw conversations and unYOLO approval buttons.
ML Claw runs Telegram Bot Mux as the only upstream poller and gives each
consumer its own local token and queue.

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

Use a positive user ID for a one-to-one chat; ML Claw rejects group and channel
IDs. The physical token stays in the trusted mux process. OpenClaw, HF Broker,
and `unyolo-telegram` receive only local mux credentials. The mux routes `bk:`
callbacks exclusively to unYOLO and keeps its SQLite queue in protected durable
state.

Existing two-bot deployments remain supported through
`--approval-telegram-token-file`. The approval file may contain
`MLCLAW_UNYOLO_TELEGRAM_BOT_TOKEN=...` or a raw token, and it must identify a
different bot. User-supplied Telegram API roots and Telegram-specific proxies
remain unsupported because ML Claw manages those routes internally.

Free Hugging Face Spaces intentionally block outbound TLS to some messaging
APIs for anti-abuse reasons. Telegram and Discord connectivity from a Space
requires upgraded paid Space hardware today. Local gateway mode avoids that
restriction because messaging traffic originates from the user's machine.

## Local Gateway Mode

Use local gateway mode when the user wants the gateway on their machine:

```bash
npx mlclaw@latest bootstrap --gateway local --name mlclaw
```

After the first setup, `mlclaw bootstrap` and `mlclaw configure` automatically
select the only local deployment. Use the same command to reconfigure or resume
it. If local configuration is missing, interactive bootstrap can recover a
validated deployment marker from an owned Storage Bucket; credentials and
machine-specific container bindings must be supplied again.

Tailnet access is explicit:

```bash
npx mlclaw@latest bootstrap --gateway local --tailscale=direct
npx mlclaw@latest bootstrap --gateway local --tailscale=serve
npx mlclaw@latest bootstrap --gateway local --tailscale=off
```

Direct mode binds loopback and the exact Tailscale IPv4 address. Serve mode
keeps the gateway on loopback and creates one HTTPS Serve mapping. A Serve
administrator approval prompt is resumable: approve the printed URL, then run
bootstrap again.

If the user has multiple Docker en
````

## File: README.md
upstream: https://github.com/huggingface/mlclaw/blob/main/README.md

````text
<p align="center">
  <img src="https://raw.githubusercontent.com/huggingface/mlclaw/main/assets/mlclaw.svg" alt="ML Claw" width="180">
</p>

# 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](https://github.com/huggingface/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:

```bash
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
bash <(curl -fsSL https://raw.githubusercontent.com/huggingface/mlclaw/main/mlclaw.sh)
```

On Windows:

```powershell
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

```bash
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:

```bash
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:

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

Choose a Hugging Face Router model with `--model`:

```bash
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](https://github.com/osolmaz/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:

```bash
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 
````
