mlclaw

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:

npx mlclaw@latest bootstrap --name mlclaw

Without Node.js on macOS/Linux:

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

On Windows PowerShell:

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

For repo-local development, use:

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

Recommended First Setup: Browser Space Gateway

Interactive:

npx mlclaw@latest bootstrap --name mlclaw

Automation:

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:

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.

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:

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:

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 engines, pin the intended context:

npx mlclaw@latest bootstrap \
  --gateway local \
  --name mlclaw \
  --docker-context desktop-linux

Common Docker contexts on macOS are desktop-linux, colima, and orbstack. After bootstrap, local gateway commands use the pinned context from the manifest even if the shell's current Docker context changes.

Model Selection

The --model value is the OpenClaw model identifier. For Hugging Face Router models, use the huggingface/ prefix.

Default/recommended:

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

Known useful router-compatible choices:

• huggingface/google/gemma-4-26B-A4B-it:deepinfra: default quality target.
• 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 alternatives using the :fireworks-ai suffix are curated for GLM 5.2, Kimi K2.7 Code, GPT-OSS 120B and 20B, DeepSeek V4 Flash and Pro, and MiniMax M3. The Router catalog does not currently expose the Gemma 4 or Qwen 3.6 presets through Fireworks.

Do not assume every Hub model is a Router chat model. If exact current model availability matters, check the Hugging Face Router catalog or run a direct chat-completions probe.

Operating A Deployment

Check status:

mlclaw gateway status <agent>
mlclaw doctor <owner/space>

Update a Space:

mlclaw update <owner/space>
mlclaw doctor <owner/space> --fix

Move gateway location without losing state:

mlclaw gateway migrate <agent> --to local
mlclaw gateway migrate <agent> --to space

Local gateway lifecycle:

mlclaw gateway logs <agent>
mlclaw gateway stop <agent>
mlclaw gateway start <agent>

OpenAI Credentials

After signing into the Space, use the ML Claw control UI:

• /mlclaw/settings chooses Router model/provider rows. App Spaces without a Hub token save the selection into snapshotted runtime state and restart only OpenClaw; the CLI remains responsible for privileged Space variable changes.
• /mlclaw/status shows runtime, bucket, model, OAuth, and integration status.
• /mlclaw/credentials connects or disconnects Hugging Face MCP and Research Agent access, and stores an OpenAI API key.

The trusted ML Claw wrapper stores Hugging Face OAuth tokens encrypted on the mounted private state volume. OpenClaw runs as a separate unprivileged Unix user and receives only local MCP server URLs plus an internal capability header; never place the OAuth token in OpenClaw config or environment.

After migrating to a local gateway, the MCP proxy uses the local deployment's Hugging Face token inside the trusted wrapper instead of requiring the Space's OAuth client. Migrating back resumes the encrypted OAuth credential retained in the private bucket. OpenClaw receives only a generated HF Broker agent credential; it never receives the broader local Hub token or the broker operator credential.

The OpenAI key is stored as a 0600 runtime file for immediate use. For restart-durable OpenAI credentials, use the local mlclaw CLI or Space settings to set a Space Secret; do not put the user's broad Hub token into the Space just so the browser app can mutate secrets. The key must never be logged or returned to the browser.

Deployment-scoped ChatGPT login uses OpenAI's Codex device-code protocol directly and does not require the Codex CLI:

mlclaw credentials codex login <agent>

After login, ML Claw imports the deployment credential into a managed native OpenClaw OAuth profile and enables OpenClaw's bundled Codex app-server harness for openai/* agent models. OpenClaw contacts OpenAI directly, refreshes the OAuth credential in its private auth store, and discovers the account-visible catalog, including openai/gpt-5.6-sol when entitled. ML Claw does not proxy model discovery or inference and does not install or invoke a Codex CLI from PATH. Normal OPENAI_API_KEY profiles can coexist with subscription OAuth; OpenAI agent turns use the Codex harness with either credential type.

Branding

ML Claw white-labels the browser gateway at the proxy layer. App Spaces default the browser title, PWA manifest, login heading, and ML Claw control link to the agent name. The ML Claw logo is reserved for the control UI brand mark. The gateway shortcut, login logo, and default browser icons use the Hugging Face logo. The OpenClaw assistant fallback avatar defaults to a neutral assistant icon.

Use Space variables for explicit branding:

MLCLAW_BRAND_NAME="Bob Lab"
MLCLAW_BRAND_SHORT_NAME="Bob"
MLCLAW_BRAND_THEME_COLOR="#111827"
MLCLAW_BRAND_LOGO="mlclaw.svg"
MLCLAW_BRAND_FAVICON="hf-logo.svg"
MLCLAW_BRAND_FAVICON_32="hf-logo.svg"
MLCLAW_BRAND_FAVICON_ICO="hf-logo.svg"
MLCLAW_BRAND_APPLE_TOUCH_ICON="assistant-avatar.svg"
MLCLAW_BRAND_ASSISTANT_AVATAR="assistant-avatar.svg"

Brand asset paths are relative to the Space assets/ directory. ML Claw serves them through /assets/brand/logo, /favicon.svg, /favicon-32.png, /favicon.ico, /apple-touch-icon.png, and /manifest.webmanifest.

State Safety

OpenClaw uses local disk. In Space gateway mode, the private bucket is mounted at /data/mlclaw-state, but it stores verified snapshots only. On boot, the runtime restores the newest valid snapshot into /home/node/.local/share/mlclaw/live. During runtime and shutdown, hf-state-sync writes new snapshots back to the mounted bucket. Secrets are kept outside the snapshot path.