mlclaw 0.1.0

package/entrypoint.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LIVE_DIR="${OPENCLAW_LIVE_DIR:-/tmp/openclaw-live}"
+
+if [ "${MLCLAW_GATEWAY_DISABLED:-0}" = "1" ]; then
+  echo "[mlclaw] gateway disabled"
+  exit 0
+fi
+
+if [ -z "${HUGGINGFACE_HUB_TOKEN:-}" ] && [ -n "${HF_TOKEN:-}" ]; then
+  export HUGGINGFACE_HUB_TOKEN="$HF_TOKEN"
+fi
+
+# State, workspace, and config paths are ALWAYS derived from the live dir,
+# never inherited: older deployments set OPENCLAW_STATE_DIR=/data/... as Space
+# variables, and any state written outside the live dir would be invisible to
+# snapshot/restore — the bucket would back up an empty tree.
+export OPENCLAW_STATE_DIR="$LIVE_DIR/.openclaw"
+export OPENCLAW_WORKSPACE_DIR="$LIVE_DIR/workspace"
+export OPENCLAW_CONFIG_PATH="$LIVE_DIR/.openclaw/openclaw.json"
+export OPENCLAW_GATEWAY_PORT="${MLCLAW_OPENCLAW_PORT:-7861}"
+STATE_DIR="$OPENCLAW_STATE_DIR"
+WORKSPACE_DIR="$OPENCLAW_WORKSPACE_DIR"
+CONFIG_PATH="$OPENCLAW_CONFIG_PATH"
+
+# Restore durable state from the bucket BEFORE creating any live dirs: the
+# restore target is the live dir itself and must not exist yet. Fails the boot
+# if the bucket has state but its manifest or every snapshot is corrupt (never
+# silently start fresh then snapshot over a bucket that still holds data).
+echo "[hf-state-sync] starting restore"
+RESTORE_TIMEOUT_SECONDS="${MLCLAW_RESTORE_TIMEOUT_SECONDS:-180}"
+if command -v timeout >/dev/null 2>&1; then
+  timeout "${RESTORE_TIMEOUT_SECONDS}s" node /app/hf-state-sync.js restore
+else
+  node /app/hf-state-sync.js restore
+fi
+echo "[hf-state-sync] restore complete"
+
+mkdir -p "$LIVE_DIR" "$WORKSPACE_DIR" "$STATE_DIR"
+chown -R node:node "$LIVE_DIR"
+
+if [ -n "${OPENCLAW_AGENT_NAME:-}" ]; then
+  printf "%s\n" "$OPENCLAW_AGENT_NAME" > "$STATE_DIR/agent-name.txt"
+fi
+
+if [ ! -f "$CONFIG_PATH" ]; then
+  cp /app/openclaw.default.json "$CONFIG_PATH"
+fi
+chown -R node:node "$LIVE_DIR"
+
+if [ -n "${OPENCLAW_MODEL:-}" ]; then
+  echo "[huggingface-config] configuring selected Hugging Face model"
+  gosu node node /app/scripts/configure-huggingface-model.mjs "$CONFIG_PATH"
+  echo "[huggingface-config] Hugging Face model configured"
+fi
+
+if [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_ALLOWED_USERS:-}" ]; then
+  echo "[telegram-config] configuring Telegram channel"
+  gosu node node /app/scripts/configure-telegram.mjs "$CONFIG_PATH" "$TELEGRAM_ALLOWED_USERS"
+  echo "[telegram-config] Telegram channel configured"
+fi
+
+if [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ "${OPENCLAW_TELEGRAM_CONNECTIVITY_PROBE:-0}" = "1" ]; then
+  if command -v curl >/dev/null 2>&1; then
+    PROBE_OUT="/tmp/openclaw-telegram-probe.json"
+    PROBE_PROXY=()
+    PROBE_API_ROOT="${TELEGRAM_API_ROOT:-https://api.telegram.org}"
+    PROBE_API_ROOT="${PROBE_API_ROOT%/}"
+    if [ -n "${TELEGRAM_PROXY:-}" ]; then
+      PROBE_PROXY=(--proxy "$TELEGRAM_PROXY")
+    fi
+    if curl -fsS --connect-timeout 20 --max-time 30 "${PROBE_PROXY[@]}" \
+      "${PROBE_API_ROOT}/bot${TELEGRAM_BOT_TOKEN}/getMe" \
+      -o "$PROBE_OUT"; then
+      gosu node node /app/scripts/report-telegram-probe.mjs "$PROBE_OUT" || true
+    else
+      echo "[telegram-probe] curl getMe failed"
+    fi
+    rm -f "$PROBE_OUT"
+  else
+    echo "[telegram-probe] curl is unavailable; skipping"
+  fi
+fi
+
+chown -R node:node "$LIVE_DIR"
+exec gosu node node /app/hf-state-sync.js supervise -- node /app/mlclaw-space-runtime.js

package/mlclaw.ps1

@@ -0,0 +1,108 @@
+$ErrorActionPreference = "Stop"
+
+$MinNodeMajor = if ($env:MLCLAW_MIN_NODE_MAJOR) { [int]$env:MLCLAW_MIN_NODE_MAJOR } else { 22 }
+$NodeVersion = if ($env:MLCLAW_NODE_VERSION) { $env:MLCLAW_NODE_VERSION } else { "v24.16.0" }
+$PackageSpec = if ($env:MLCLAW_NPM_SPEC) { $env:MLCLAW_NPM_SPEC } else { "mlclaw" }
+$CacheRoot = if ($env:MLCLAW_CACHE_DIR) {
+  $env:MLCLAW_CACHE_DIR
+} elseif ($env:LOCALAPPDATA) {
+  Join-Path $env:LOCALAPPDATA "mlclaw"
+} else {
+  Join-Path $HOME ".cache\mlclaw"
+}
+
+function Get-NodeMajor($NodeBin) {
+  try {
+    $major = & $NodeBin -p 'Number(process.versions.node.split(".")[0])'
+    return [int]$major
+  } catch {
+    return 0
+  }
+}
+
+function Test-CompatibleNode($NodeBin) {
+  return (Get-NodeMajor $NodeBin) -ge $MinNodeMajor
+}
+
+function Get-SystemNode {
+  $cmd = Get-Command node -ErrorAction SilentlyContinue
+  if ($cmd -and (Test-CompatibleNode $cmd.Source)) {
+    return $cmd.Source
+  }
+  return $null
+}
+
+function Get-NodeArch {
+  if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") {
+    return "arm64"
+  }
+  return "x64"
+}
+
+function Install-CachedNode {
+  $arch = Get-NodeArch
+  $archiveName = "node-$NodeVersion-win-$arch"
+  $targetDir = Join-Path $CacheRoot "node\$NodeVersion-win-$arch"
+  $nodeBin = Join-Path $targetDir "node.exe"
+  if ((Test-Path $nodeBin) -and (Test-CompatibleNode $nodeBin)) {
+    return $targetDir
+  }
+
+  $parent = Split-Path $targetDir -Parent
+  New-Item -ItemType Directory -Force -Path $parent | Out-Null
+  $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) ("mlclaw-node-" + [System.Guid]::NewGuid().ToString("N"))
+  New-Item -ItemType Directory -Force -Path $tempDir | Out-Null
+  try {
+    $zipPath = Join-Path $tempDir "node.zip"
+    $url = "https://nodejs.org/dist/$NodeVersion/$archiveName.zip"
+    Write-Error "mlclaw: installing Node.js $NodeVersion into $targetDir" -ErrorAction Continue
+    Invoke-WebRequest -Uri $url -OutFile $zipPath
+    Expand-Archive -Path $zipPath -DestinationPath $tempDir -Force
+    if (Test-Path $targetDir) {
+      Remove-Item -Recurse -Force $targetDir
+    }
+    Move-Item (Join-Path $tempDir $archiveName) $targetDir
+  } finally {
+    Remove-Item -Recurse -Force $tempDir -ErrorAction SilentlyContinue
+  }
+  return $targetDir
+}
+
+function Invoke-MLClaw($NodeBin, [string[]]$CliArgs) {
+  $nodeDir = Split-Path $NodeBin -Parent
+  $env:PATH = "$nodeDir;$env:PATH"
+  $npmCli = Join-Path $nodeDir "node_modules\npm\bin\npm-cli.js"
+  if (-not (Test-Path $npmCli)) {
+    $npmCommand = Get-Command npm -ErrorAction SilentlyContinue
+    if (-not $npmCommand) {
+      throw "npm was not found for Node runtime $NodeBin"
+    }
+    & $npmCommand.Source exec --yes --package $PackageSpec -- mlclaw @CliArgs
+    exit $LASTEXITCODE
+  }
+  & $NodeBin $npmCli exec --yes --package $PackageSpec -- mlclaw @CliArgs
+  exit $LASTEXITCODE
+}
+
+function Test-NodeHasNpm($NodeBin) {
+  $nodeDir = Split-Path $NodeBin -Parent
+  $npmCli = Join-Path $nodeDir "node_modules\npm\bin\npm-cli.js"
+  if (Test-Path $npmCli) {
+    return $true
+  }
+  $oldPath = $env:PATH
+  try {
+    $env:PATH = "$nodeDir;$env:PATH"
+    return [bool](Get-Command npm -ErrorAction SilentlyContinue)
+  } finally {
+    $env:PATH = $oldPath
+  }
+}
+
+$node = Get-SystemNode
+if ($node -and (Test-NodeHasNpm $node)) {
+  Invoke-MLClaw $node $args
+}
+
+$nodeDir = Install-CachedNode
+Invoke-MLClaw (Join-Path $nodeDir "node.exe") $args

package/mlclaw.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MIN_NODE_MAJOR="${MLCLAW_MIN_NODE_MAJOR:-22}"
+NODE_VERSION="${MLCLAW_NODE_VERSION:-v24.16.0}"
+PACKAGE_SPEC="${MLCLAW_NPM_SPEC:-mlclaw}"
+CACHE_ROOT="${MLCLAW_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/mlclaw}"
+
+die() {
+  printf 'mlclaw: %s\n' "$*" >&2
+  exit 1
+}
+
+node_major() {
+  "$1" -p 'Number(process.versions.node.split(".")[0])' 2>/dev/null || printf '0\n'
+}
+
+node_is_compatible() {
+  local node_bin="$1"
+  local major
+  major="$(node_major "$node_bin")"
+  [ "$major" -ge "$MIN_NODE_MAJOR" ]
+}
+
+system_node() {
+  if command -v node >/dev/null 2>&1 && node_is_compatible "$(command -v node)"; then
+    command -v node
+  fi
+}
+
+platform_name() {
+  case "$(uname -s)" in
+    Darwin) printf 'darwin' ;;
+    Linux) printf 'linux' ;;
+    *) die "unsupported operating system: $(uname -s)" ;;
+  esac
+}
+
+arch_name() {
+  case "$(uname -m)" in
+    x86_64 | amd64) printf 'x64' ;;
+    arm64 | aarch64) printf 'arm64' ;;
+    *) die "unsupported CPU architecture: $(uname -m)" ;;
+  esac
+}
+
+cached_node_dir() {
+  printf '%s/node/%s-%s-%s\n' "$CACHE_ROOT" "$NODE_VERSION" "$(platform_name)" "$(arch_name)"
+}
+
+install_node() {
+  command -v curl >/dev/null 2>&1 || die "curl is required to install Node.js"
+  command -v tar >/dev/null 2>&1 || die "tar is required to install Node.js"
+
+  local os arch archive_name url temp_dir target_dir
+  os="$(platform_name)"
+  arch="$(arch_name)"
+  archive_name="node-${NODE_VERSION}-${os}-${arch}"
+  url="https://nodejs.org/dist/${NODE_VERSION}/${archive_name}.tar.xz"
+  target_dir="$(cached_node_dir)"
+
+  if [ -x "$target_dir/bin/node" ] && node_is_compatible "$target_dir/bin/node"; then
+    printf '%s\n' "$target_dir"
+    return
+  fi
+
+  temp_dir="$(mktemp -d "${TMPDIR:-/tmp}/mlclaw-node.XXXXXX")"
+  mkdir -p "$(dirname "$target_dir")"
+  printf 'mlclaw: installing Node.js %s into %s\n' "$NODE_VERSION" "$target_dir" >&2
+  if ! curl -fsSL "$url" -o "$temp_dir/node.tar.xz"; then
+    rm -rf "$temp_dir"
+    die "failed to download Node.js from $url"
+  fi
+  if ! tar -xJf "$temp_dir/node.tar.xz" -C "$temp_dir"; then
+    rm -rf "$temp_dir"
+    die "failed to unpack Node.js archive"
+  fi
+  rm -rf "$target_dir"
+  mv "$temp_dir/$archive_name" "$target_dir"
+  rm -rf "$temp_dir"
+  printf '%s\n' "$target_dir"
+}
+
+run_with_node() {
+  local node_bin="$1"
+  shift
+  local npm_cli node_path
+  node_path="$(dirname "$node_bin")"
+  npm_cli="$(dirname "$node_bin")/../lib/node_modules/npm/bin/npm-cli.js"
+  if [ -f "$npm_cli" ]; then
+    PATH="$node_path:$PATH" exec "$node_bin" "$npm_cli" exec --yes --package "$PACKAGE_SPEC" -- mlclaw "$@"
+  fi
+  if command -v npm >/dev/null 2>&1; then
+    PATH="$node_path:$PATH" exec npm exec --yes --package "$PACKAGE_SPEC" -- mlclaw "$@"
+  fi
+  die "npm was not found for Node runtime $node_bin"
+}
+
+node_has_npm() {
+  local node_bin="$1"
+  local node_path npm_cli
+  node_path="$(dirname "$node_bin")"
+  npm_cli="$(dirname "$node_bin")/../lib/node_modules/npm/bin/npm-cli.js"
+  [ -f "$npm_cli" ] || PATH="$node_path:$PATH" command -v npm >/dev/null 2>&1
+}
+
+main() {
+  local node_bin node_dir
+  node_bin="$(system_node || true)"
+  if [ -n "$node_bin" ] && node_has_npm "$node_bin"; then
+    run_with_node "$node_bin" "$@"
+  fi
+  node_dir="$(install_node)"
+  run_with_node "$node_dir/bin/node" "$@"
+}
+
+main "$@"

package/openclaw.default.json

@@ -0,0 +1,67 @@
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "${OPENCLAW_MODEL}"
+      }
+    }
+  },
+  "gateway": {
+    "mode": "local",
+    "bind": "loopback",
+    "port": 7861,
+    "auth": {
+      "mode": "trusted-proxy",
+      "trustedProxy": {
+        "userHeader": "x-forwarded-user",
+        "requiredHeaders": ["x-forwarded-proto", "x-forwarded-host"],
+        "allowLoopback": true
+      }
+    },
+    "trustedProxies": ["127.0.0.1", "::1"],
+    "controlUi": {
+      "dangerouslyDisableDeviceAuth": true,
+      "allowedOrigins": ["${MLCLAW_PUBLIC_URL}"]
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": false,
+      "botToken": "${TELEGRAM_BOT_TOKEN}",
+      "dmPolicy": "allowlist",
+      "allowFrom": [],
+      "timeoutSeconds": 45,
+      "pollingStallThresholdMs": 60000,
+      "commands": {
+        "native": false
+      },
+      "network": {
+        "autoSelectFamily": false,
+        "dnsResultOrder": "ipv4first"
+      }
+    }
+  },
+  "messages": {
+    "queue": {
+      "byChannel": {
+        "telegram": "collect"
+      },
+      "debounceMsByChannel": {
+        "telegram": 1500
+      },
+      "cap": 20,
+      "drop": "summarize"
+    }
+  },
+  "session": {
+    "dmScope": "per-channel-peer",
+    "reset": {
+      "mode": "daily",
+      "atHour": 4,
+      "idleMinutes": 1440
+    }
+  },
+  "cron": {
+    "enabled": true
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "mlclaw",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/osolmaz/mlclaw"
+  },
+  "homepage": "https://github.com/osolmaz/mlclaw#readme",
+  "bugs": {
+    "url": "https://github.com/osolmaz/mlclaw/issues"
+  },
+  "type": "module",
+  "bin": {
+    "mlclaw": "dist/mlclaw.mjs"
+  },
+  "files": [
+    ".agents/skills/",
+    ".gitattributes",
+    "assets/",
+    "dist/hf-state-sync.js",
+    "dist/mlclaw.mjs",
+    "dist/mlclaw-space-runtime.js",
+    "Dockerfile",
+    "entrypoint.sh",
+    "mlclaw.ps1",
+    "mlclaw.sh",
+    "LICENSE",
+    "openclaw.default.json",
+    "README.md",
+    "scripts/configure-telegram.mjs",
+    "scripts/configure-huggingface-model.mjs",
+    "scripts/report-telegram-probe.mjs",
+    "space/",
+    "src/hf-bucket-client/",
+    "src/hf-state-sync/",
+    "src/vendor/",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "npm run build:state-sync && npm run build:space-runtime && npm run build:mlclaw",
+    "build:state-sync": "esbuild src/hf-state-sync/cli.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/hf-state-sync.js --banner:js=\"import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);\"",
+    "build:space-runtime": "esbuild src/mlclaw-space-runtime/cli.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/mlclaw-space-runtime.js --banner:js=\"import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);\"",
+    "build:mlclaw": "esbuild src/mlclaw/cli.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/mlclaw.mjs --banner:js=\"import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);\"",
+    "build:probe": "esbuild scripts/parity-probe.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/parity-probe.mjs --banner:js=\"import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);\"",
+    "pack:check": "node scripts/check-package.mjs",
+    "prepack": "npm run build",
+    "check:secrets": "node scripts/check-secrets.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "@huggingface/splitmix64-wasm": "^0.0.1",
+    "@huggingface/xetchunk-wasm": "^0.0.6",
+    "commander": "^14.0.3",
+    "skillflag": "^0.2.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/scripts/configure-huggingface-model.mjs

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+
+const [configPath] = process.argv.slice(2);
+
+if (!configPath) {
+  console.error("Usage: configure-huggingface-model.mjs <config-path>");
+  process.exit(2);
+}
+
+const modelRef = (process.env.OPENCLAW_MODEL || "").trim();
+const prefix = "huggingface/";
+
+if (!modelRef.startsWith(prefix)) {
+  process.exit(0);
+}
+
+const providerModelId = modelRef.slice(prefix.length).trim();
+if (!providerModelId) {
+  process.exit(0);
+}
+
+function displayNameFromModelId(id) {
+  const withoutPolicy = id.replace(/:(cheapest|fastest)$/i, "");
+  const base = withoutPolicy.split("/").pop() || withoutPolicy;
+  return base.replace(/[-_]+/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function isLikelyImageModel(id) {
+  const lower = id.toLowerCase();
+  return (
+    lower.includes("-vl") ||
+    lower.includes("vision") ||
+    lower.includes("multimodal") ||
+    lower.includes("gemma-3") ||
+    lower.includes("gemma-4") ||
+    lower.includes("llama-4")
+  );
+}
+
+function contextWindowForModel(id) {
+  const lower = id.toLowerCase();
+  if (lower.includes("gemma-4") || lower.includes("qwen3.6")) return 262144;
+  if (lower.includes("qwen3-8b") || lower.includes("qwen3-14b")) return 40960;
+  return 131072;
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+config.models ||= {};
+config.models.providers ||= {};
+config.models.providers.huggingface ||= {};
+
+const provider = config.models.providers.huggingface;
+provider.baseUrl ||= "https://router.huggingface.co/v1";
+provider.api ||= "openai-completions";
+provider.models = Array.isArray(provider.models) ? provider.models : [];
+
+const defaultEntry = {
+  id: providerModelId,
+  name: displayNameFromModelId(providerModelId),
+  input: isLikelyImageModel(providerModelId) ? ["text", "image"] : ["text"],
+  contextWindow: contextWindowForModel(providerModelId),
+  maxTokens: 8192,
+  reasoning: /r1|reason|thinking|reasoner|qwq/i.test(providerModelId),
+  cost: {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+  },
+  api: "openai-completions",
+};
+
+const existingIndex = provider.models.findIndex(
+  (entry) => entry && typeof entry === "object" && entry.id === providerModelId,
+);
+
+if (existingIndex >= 0) {
+  provider.models[existingIndex] = {
+    ...defaultEntry,
+    ...provider.models[existingIndex],
+  };
+} else {
+  provider.models.push(defaultEntry);
+}
+
+fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });

package/scripts/configure-telegram.mjs

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+
+const [configPath, allowedUsersRaw] = process.argv.slice(2);
+
+if (!configPath) {
+  console.error("Usage: configure-telegram.mjs <config-path> <allowed-users>");
+  process.exit(2);
+}
+
+const allowedUsers = (allowedUsersRaw || "")
+  .split(",")
+  .map((value) => value.trim())
+  .filter(Boolean);
+const telegramProxy = (process.env.TELEGRAM_PROXY || "").trim();
+const telegramApiRoot = (process.env.TELEGRAM_API_ROOT || "").trim().replace(/\/+$/, "");
+
+if (allowedUsers.length === 0) {
+  process.exit(0);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+config.channels ||= {};
+config.channels.telegram ||= {};
+config.messages ||= {};
+config.messages.queue ||= {};
+config.messages.queue.byChannel ||= {};
+config.messages.queue.debounceMsByChannel ||= {};
+
+config.messages.queue.byChannel.telegram ||= "collect";
+config.messages.queue.debounceMsByChannel.telegram ??= 1500;
+config.messages.queue.cap ??= 20;
+config.messages.queue.drop ||= "summarize";
+
+Object.assign(config.channels.telegram, {
+  enabled: true,
+  botToken: "${TELEGRAM_BOT_TOKEN}",
+  dmPolicy: "allowlist",
+  allowFrom: allowedUsers,
+  timeoutSeconds: 45,
+  pollingStallThresholdMs: 60000,
+  commands: {
+    ...(config.channels.telegram.commands || {}),
+    native: false
+  },
+  network: {
+    ...(config.channels.telegram.network || {}),
+    autoSelectFamily: false,
+    dnsResultOrder: "ipv4first"
+  },
+  ...(telegramProxy ? { proxy: "${TELEGRAM_PROXY}" } : {}),
+  ...(telegramApiRoot ? { apiRoot: "${TELEGRAM_API_ROOT}" } : {}),
+  groups: config.channels.telegram.groups || {}
+});
+
+fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });

package/scripts/report-telegram-probe.mjs

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+
+const [probePath] = process.argv.slice(2);
+
+if (!probePath) {
+  process.exit(0);
+}
+
+try {
+  const payload = JSON.parse(fs.readFileSync(probePath, "utf8"));
+  if (payload?.ok && payload?.result?.username) {
+    console.log(`[telegram-probe] curl getMe ok (@${payload.result.username})`);
+  } else {
+    console.log("[telegram-probe] curl getMe returned an unexpected response");
+  }
+} catch {
+  console.log("[telegram-probe] curl getMe response could not be parsed");
+}

package/space/README.md

@@ -0,0 +1,42 @@
+---
+title: ML Claw
+emoji: 🦞
+colorFrom: yellow
+colorTo: red
+sdk: docker
+app_port: 7860
+hf_oauth: true
+hf_oauth_expiration_minutes: 43200
+pinned: false
+secrets:
+  - HF_TOKEN
+  - MLCLAW_SESSION_SECRET
+  - OPENAI_API_KEY
+---
+
+# ML Claw
+
+<p align="center">
+  <img src="assets/mlclaw.svg" alt="ML Claw" width="160">
+</p>
+
+ML Claw runs OpenClaw in a Hugging Face Space with a browser gateway protected
+by Hugging Face OAuth. Duplicate this Space or use `mlclaw bootstrap` to create
+your own deployment.
+
+The public Space process is an ML Claw proxy. It authenticates the signed-in
+Hugging Face user, then forwards browser traffic to OpenClaw on loopback using
+OpenClaw trusted-proxy auth. The browser never receives an OpenClaw gateway
+token.
+
+Durable state lives in a private Hugging Face Storage Bucket configured by
+`OPENCLAW_HF_STATE_BUCKET`. The bucket is not mounted as a live filesystem;
+`hf-state-sync` restores verified snapshots on boot and uploads new snapshots
+during runtime and shutdown.
+
+Manage an existing deployment from your machine with:
+
+```bash
+mlclaw doctor <owner/space> --fix
+mlclaw update <owner/space>
+```