@bryceli/openclaw 0.1.0 → 0.1.1

package/README.md

@@ -1,45 +1,39 @@
-# OpenClaw
+# OpenClaw Lightweight Wrapper
 
-This project installs `openclaw` locally with npm and keeps all OpenClaw state inside this project.
+This package is a lightweight wrapper around `openclaw`.
 
-## What is isolated
+## Why this version is lighter
 
-- OpenClaw is installed in local `node_modules`
-- config is stored in `.openclaw-home/openclaw.json`
-- secrets are stored in `.openclaw-home/.env`
-- workspace is stored in `.openclaw-home/workspace`
+- `npm install @bryceli/openclaw` only installs the wrapper
+- the heavy upstream `openclaw` runtime is installed later, on demand
+- runtime files are stored in the current project under `.openclaw-runtime`
+- config files are stored in the current project under `.openclaw-home`
 
-## Package name
+## Current-project isolation
 
-This publishable wrapper package is intended to be published as `@bryceli/openclaw`.
+Everything is project-local:
+
+- `.openclaw-runtime`
+- `.openclaw-home/openclaw.json`
+- `.openclaw-home/.env`
+- `.openclaw-home/workspace`
 
 ## Quick start
 
 ```bash
-npm install
-npm run setup
-npm run gateway
+npx @bryceli/openclaw
 ```
 
-## Useful commands
+Or explicitly:
 
 ```bash
-npm run openclaw -- --version
-npm run dashboard
-npm run models:list
+npx @bryceli/openclaw setup
+npx @bryceli/openclaw gateway
+npx @bryceli/openclaw dashboard
 ```
 
-## Interface types
-
-- OpenAI Compatible (最常用)
-- Anthropic Native (原生)
-- OpenAI Responses (新接口)
-- Google Gemini (原生)
-- Ollama Native (本地原生)
-
 ## Notes
 
-- This project is only for OpenClaw.
-- It does not configure Claude Code.
-- It does not configure OpenCode.
-- All paths are project-local through `OPENCLAW_HOME`.
+- The wrapper defaults to `setup` when no subcommand is given.
+- The OpenClaw runtime is installed lazily when you first run setup or gateway-related commands.
+- The UI keeps short Chinese annotations, but the package itself stays lightweight.

package/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "./scripts/cli.mjs";

package/package.json

@@ -1,25 +1,33 @@
-{
+{
   "name": "@bryceli/openclaw",
-  "version": "0.1.0",
-  "description": "Project-local OpenClaw installer and model configurator.",
+  "version": "0.1.1",
+  "description": "Lightweight OpenClaw wrapper with project-local runtime install.",
   "type": "module",
+  "bin": {
+    "bryce-openclaw": "index.js"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "index.js",
+    "README.md",
+    "scripts"
+  ],
   "scripts": {
-    "setup": "node scripts/setup-openclaw.mjs",
-    "openclaw": "node scripts/run-openclaw.mjs",
-    "gateway": "node scripts/run-openclaw.mjs gateway run",
-    "dashboard": "node scripts/run-openclaw.mjs dashboard",
-    "models:list": "node scripts/run-openclaw.mjs models list",
-    "models:test": "node scripts/run-openclaw.mjs models test"
+    "setup": "node index.js setup",
+    "openclaw": "node index.js openclaw",
+    "gateway": "node index.js gateway",
+    "dashboard": "node index.js dashboard",
+    "models:list": "node index.js models:list",
+    "models:test": "node index.js models:test",
+    "runtime:install": "node index.js runtime:install"
   },
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
     "@clack/prompts": "^0.10.1",
-    "openclaw": "latest",
     "picocolors": "^1.1.1"
   }
-}
+}

package/scripts/cli.mjs

@@ -0,0 +1,65 @@
+import pc from "picocolors";
+import { ensureRuntimeInstalled } from "./runtime-install.mjs";
+import { runOpenClaw } from "./run-openclaw.mjs";
+import { runSetup } from "./setup-openclaw.mjs";
+
+const command = process.argv[2] ?? "setup";
+const rest = process.argv.slice(3);
+
+try {
+  switch (command) {
+    case "setup":
+      await runSetup();
+      break;
+    case "runtime:install":
+      await ensureRuntimeInstalled();
+      console.log(pc.green("OpenClaw runtime installed for the current project."));
+      break;
+    case "gateway":
+      await runOpenClaw(["gateway", "run", ...rest]);
+      break;
+    case "dashboard":
+      await runOpenClaw(["dashboard", ...rest]);
+      break;
+    case "models:list":
+      await runOpenClaw(["models", "list", ...rest]);
+      break;
+    case "models:test":
+      await runOpenClaw(["models", "test", ...rest]);
+      break;
+    case "openclaw":
+      await runOpenClaw(rest);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      break;
+    default:
+      await runOpenClaw([command, ...rest]);
+      break;
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(pc.red(message));
+  process.exit(1);
+}
+
+function printHelp() {
+  console.log(
+    [
+      "Usage:",
+      "  npx @bryceli/openclaw",
+      "  npx @bryceli/openclaw setup",
+      "  npx @bryceli/openclaw gateway",
+      "  npx @bryceli/openclaw dashboard",
+      "  npx @bryceli/openclaw models:list",
+      "  npx @bryceli/openclaw models:test",
+      "",
+      "Notes:",
+      "  setup installs only a small wrapper first.",
+      "  The heavy OpenClaw runtime is installed lazily into ./.openclaw-runtime when needed.",
+      "  All config is stored in the current project via ./.openclaw-home."
+    ].join("\n")
+  );
+}

package/scripts/paths.mjs

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function getPackageRoot() {
+  return path.resolve(__dirname, "..");
+}
+
+export function getProjectRoot() {
+  return process.cwd();
+}
+
+export function getOpenClawHome(projectRoot = getProjectRoot()) {
+  return path.join(projectRoot, ".openclaw-home");
+}
+
+export function getRuntimeRoot(projectRoot = getProjectRoot()) {
+  return path.join(projectRoot, ".openclaw-runtime");
+}
+
+export function getRuntimePackageJson(projectRoot = getProjectRoot()) {
+  return path.join(getRuntimeRoot(projectRoot), "package.json");
+}

package/scripts/run-openclaw.mjs

@@ -1,29 +1,34 @@
-import { spawn } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { ensureRuntimeInstalled } from "./runtime-install.mjs";
+import { getOpenClawHome, getProjectRoot } from "./paths.mjs";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const projectRoot = path.resolve(__dirname, "..");
-const openclawHome = path.join(projectRoot, ".openclaw-home");
+export async function runOpenClaw(args = process.argv.slice(2)) {
+  const projectRoot = getProjectRoot();
+  const openclawHome = getOpenClawHome(projectRoot);
+  const { runtimeBin } = await ensureRuntimeInstalled({ quiet: false });
 
-const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
-const args = ["exec", "--", "openclaw", ...process.argv.slice(2)];
+  await new Promise((resolve, reject) => {
+    const child = spawn(runtimeBin, args, {
+      cwd: projectRoot,
+      env: {
+        ...process.env,
+        OPENCLAW_HOME: openclawHome
+      },
+      stdio: "inherit"
+    });
 
-const child = spawn(npmCommand, args, {
-  cwd: projectRoot,
-  env: {
-    ...process.env,
-    OPENCLAW_HOME: openclawHome
-  },
-  stdio: "inherit"
-});
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`OpenClaw exited via signal ${signal}`));
+        return;
+      }
 
-child.on("exit", (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
-  }
+      if ((code ?? 0) !== 0) {
+        reject(new Error(`OpenClaw exited with code ${code ?? 0}`));
+        return;
+      }
 
-  process.exit(code ?? 0);
-});
+      resolve();
+    });
+  });
+}

package/scripts/runtime-install.mjs

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import pc from "picocolors";
+import { getProjectRoot, getRuntimePackageJson, getRuntimeRoot } from "./paths.mjs";
+
+const RUNTIME_PACKAGE_JSON = {
+  name: "openclaw-runtime-local",
+  private: true,
+  version: "0.0.0",
+  description: "Project-local OpenClaw runtime installed by @bryceli/openclaw",
+  type: "module"
+};
+
+export async function ensureRuntimeInstalled({ quiet = false } = {}) {
+  const projectRoot = getProjectRoot();
+  const runtimeRoot = getRuntimeRoot(projectRoot);
+  const runtimePackageJson = getRuntimePackageJson(projectRoot);
+  const runtimeBin = getRuntimeExecutable(projectRoot);
+
+  if (existsSync(runtimeBin)) {
+    return { projectRoot, runtimeRoot, runtimeBin };
+  }
+
+  mkdirSync(runtimeRoot, { recursive: true });
+  if (!existsSync(runtimePackageJson)) {
+    writeFileSync(runtimePackageJson, `${JSON.stringify(RUNTIME_PACKAGE_JSON, null, 2)}\n`, "utf8");
+  }
+
+  if (!quiet) {
+    console.log(pc.cyan("Installing OpenClaw runtime into the current project (.openclaw-runtime)..."));
+  }
+
+  await runNpmInstall(runtimeRoot);
+
+  if (!existsSync(runtimeBin)) {
+    throw new Error("OpenClaw runtime install finished but the executable was not found.");
+  }
+
+  return { projectRoot, runtimeRoot, runtimeBin };
+}
+
+export function getRuntimeExecutable(projectRoot = getProjectRoot()) {
+  const binName = process.platform === "win32" ? "openclaw.cmd" : "openclaw";
+  return path.join(getRuntimeRoot(projectRoot), "node_modules", ".bin", binName);
+}
+
+function runNpmInstall(runtimeRoot) {
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(npmCommand, ["install", "--no-save", "openclaw@latest"], {
+      cwd: runtimeRoot,
+      env: withNodePath(process.env),
+      stdio: "inherit"
+    });
+
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`npm install terminated by signal ${signal}`));
+        return;
+      }
+
+      if (code !== 0) {
+        reject(new Error(`npm install exited with code ${code}`));
+        return;
+      }
+
+      resolve();
+    });
+  });
+}
+
+function withNodePath(env) {
+  const nextEnv = { ...env };
+  const nodeDir = process.execPath ? path.dirname(process.execPath) : "";
+  if (!nodeDir) {
+    return nextEnv;
+  }
+
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  nextEnv.Path = nextEnv.Path ? `${nodeDir}${delimiter}${nextEnv.Path}` : nodeDir;
+  nextEnv.PATH = nextEnv.PATH ? `${nodeDir}${delimiter}${nextEnv.PATH}` : nodeDir;
+  return nextEnv;
+}

package/scripts/setup-openclaw.mjs

@@ -1,13 +1,12 @@
-import * as p from "@clack/prompts";
+import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { ensureRuntimeInstalled } from "./runtime-install.mjs";
+import { getOpenClawHome, getProjectRoot } from "./paths.mjs";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const projectRoot = path.resolve(__dirname, "..");
-const openclawHome = path.join(projectRoot, ".openclaw-home");
+const projectRoot = getProjectRoot();
+const openclawHome = getOpenClawHome(projectRoot);
 const workspaceDir = path.join(openclawHome, "workspace");
 const configPath = path.join(openclawHome, "openclaw.json");
 const envPath = path.join(openclawHome, ".env");
@@ -45,12 +44,27 @@ const INTERFACE_TYPES = [
   }
 ];
 
-await main();
+export async function runSetup() {
+  await main();
+}
 
 async function main() {
   console.clear();
   p.intro(pc.bgBlue(pc.white(" OpenClaw Local Setup (安装器) ")));
 
+  const installRuntimeAnswer = await p.confirm({
+    message: "Install the heavy OpenClaw runtime now? (现在安装真正的 OpenClaw 运行时)",
+    initialValue: true
+  });
+
+  if (p.isCancel(installRuntimeAnswer)) {
+    exitCancelled();
+  }
+
+  if (installRuntimeAnswer) {
+    await ensureRuntimeInstalled();
+  }
+
   const interfaceType = await p.select({
     message: "Select the API interface type (选择接口类型)",
     options: INTERFACE_TYPES.map((item) => ({
@@ -70,7 +84,7 @@ async function main() {
     throw new Error(`Unsupported interface type: ${interfaceType}`);
   }
 
-  const suggestedBaseUrl = await getSuggestedBaseUrl(interfaceConfig);
+  const suggestedBaseUrl = interfaceConfig.defaultBaseUrl;
   const baseUrl = await promptRequiredText({
     message: "Enter the API base URL (接口地址)",
     placeholder: suggestedBaseUrl,
@@ -106,17 +120,9 @@ async function main() {
   });
 
   mkdirSync(workspaceDir, { recursive: true });
-  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  writeFileSync(configPath, `${JSON.stringify(config.file, null, 2)}\n`, "utf8");
   writeFileSync(envPath, buildEnvFile(config.envEntries), "utf8");
 
-  const notes = [];
-  if (interfaceType === "openai-responses" && !isOfficialOpenAiBaseUrl(baseUrl)) {
-    notes.push("Custom Responses endpoints are written using OpenClaw's practical openai-completions compatibility mode.");
-  }
-  if (interfaceType === "ollama-native") {
-    notes.push("Ollama uses native API mode with no /v1 suffix so tool calling stays reliable.");
-  }
-
   let outro = `${pc.green("OpenClaw project setup complete")}\n\n`;
   outro += `${pc.cyan("Project")}: ${projectRoot}\n`;
   outro += `${pc.cyan("OPENCLAW_HOME")}: ${openclawHome}\n`;
@@ -125,21 +131,9 @@ async function main() {
   outro += `${pc.cyan("Primary model")}: ${config.primaryModelRef}\n`;
   outro += `${pc.cyan("Fallback model")}: ${config.fallbackModelRef}\n`;
 
-  if (notes.length) {
-    outro += `\n${pc.yellow("Notes")}:\n- ${notes.join("\n- ")}`;
-  }
-
   p.outro(outro);
 }
 
-async function getSuggestedBaseUrl(interfaceConfig) {
-  if (interfaceConfig.value === "ollama-native") {
-    return "http://127.0.0.1:11434";
-  }
-
-  return interfaceConfig.defaultBaseUrl;
-}
-
 function buildOpenClawConfig({ interfaceType, baseUrl, apiKey, primaryModelId, fallbackModelId }) {
   const providerId = getProviderId(interfaceType);
   const envEntries = buildEnvEntries(interfaceType, apiKey);
@@ -158,40 +152,33 @@ function buildOpenClawConfig({ interfaceType, baseUrl, apiKey, primaryModelId, f
     }
   }));
 
-  const config = {
-    agents: {
-      defaults: {
-        workspace: workspaceDir,
-        model: {
-          primary: `${providerId}/${primaryModelId}`,
-          fallbacks:
-            fallbackModelId && fallbackModelId !== primaryModelId
-              ? [`${providerId}/${fallbackModelId}`]
-              : []
-        },
-        models: Object.fromEntries(
-          modelRefs.map((ref, index) => [
-            ref,
-            { alias: index === 0 ? "Primary (主模型)" : "Fallback (备用模型)" }
-          ])
-        )
+  return {
+    file: {
+      agents: {
+        defaults: {
+          workspace: workspaceDir,
+          model: {
+            primary: `${providerId}/${primaryModelId}`,
+            fallbacks:
+              fallbackModelId && fallbackModelId !== primaryModelId
+                ? [`${providerId}/${fallbackModelId}`]
+                : []
+          },
+          models: Object.fromEntries(
+            modelRefs.map((ref, index) => [
+              ref,
+              { alias: index === 0 ? "Primary (主模型)" : "Fallback (备用模型)" }
+            ])
+          )
+        }
+      },
+      models: {
+        mode: "merge",
+        providers: {
+          [providerId]: buildProviderConfig({ interfaceType, baseUrl, providerModels })
+        }
       }
     },
-    models: {
-      mode: "merge",
-      providers: {
-        [providerId]: buildProviderConfig({
-          providerId,
-          interfaceType,
-          baseUrl,
-          providerModels
-        })
-      }
-    }
-  };
-
-  return {
-    ...config,
     envEntries,
     primaryModelRef: `${providerId}/${primaryModelId}`,
     fallbackModelRef:
@@ -201,7 +188,7 @@ function buildOpenClawConfig({ interfaceType, baseUrl, apiKey, primaryModelId, f
   };
 }
 
-function buildProviderConfig({ providerId, interfaceType, baseUrl, providerModels }) {
+function buildProviderConfig({ interfaceType, baseUrl, providerModels }) {
   if (interfaceType === "google-gemini") {
     return {
       baseUrl,
@@ -243,12 +230,6 @@ function buildEnvEntries(interfaceType, apiKey) {
     };
   }
 
-  if (interfaceType === "google-gemini") {
-    return {
-      OPENCLAW_MODEL_API_KEY: apiKey
-    };
-  }
-
   return {
     OPENCLAW_MODEL_API_KEY: apiKey
   };
@@ -257,15 +238,11 @@ function buildEnvEntries(interfaceType, apiKey) {
 function buildEnvFile(entries) {
   const lines = Object.entries(entries)
     .filter(([, value]) => typeof value === "string" && value.length > 0)
-    .map(([key, value]) => `${key}=${escapeEnvValue(value)}`);
+    .map(([key, value]) => `${key}=${JSON.stringify(String(value))}`);
 
   return `${lines.join("\n")}\n`;
 }
 
-function escapeEnvValue(value) {
-  return JSON.stringify(String(value));
-}
-
 function getProviderId(interfaceType) {
   switch (interfaceType) {
     case "anthropic-native":
@@ -332,7 +309,7 @@ async function tryDetectModelId(baseUrl, interfaceType) {
         return tagId.trim();
       }
     } catch {
-      // Best-effort only.
+      // Best effort only.
     }
   }
 
@@ -348,10 +325,6 @@ function stripTrailingSlash(value) {
   return String(value ?? "").replace(/\/+$/, "");
 }
 
-function isOfficialOpenAiBaseUrl(value) {
-  return /https:\/\/api\.openai\.com\/?v1?$/i.test(stripTrailingSlash(value));
-}
-
 async function promptRequiredText({ message, placeholder, initialValue }) {
   const answer = await p.text({
     message,
@@ -390,4 +363,4 @@ async function promptOptionalText({ message, placeholder, initialValue }) {
 function exitCancelled() {
   p.cancel("Operation cancelled");
   process.exit(0);
-}
+}