@better-openclaw/core 1.0.26 → 1.0.31

package/src/frameworks/openclaw.ts

@@ -0,0 +1,325 @@
+import { randomBytes } from "node:crypto";
+import { generateOpenClawConfig } from "../generators/openclaw-json.js";
+import type { ResolverOutput } from "../types.js";
+import type {
+	AgentFrameworkDefinition,
+	EnvLine,
+	FrameworkComposeOptions,
+	FrameworkConfigOptions,
+	FrameworkConfigResult,
+	FrameworkEnvOptions,
+	GatewayBuildResult,
+} from "./types.js";
+
+// ─── Image Variants ─────────────────────────────────────────────────────────
+
+const IMAGE_VARIANTS: Record<string, string> = {
+	official: "ghcr.io/openclaw/openclaw",
+	coolify: "coollabsio/openclaw",
+	alpine: "alpine/openclaw",
+};
+
+function getOpenclawImage(variant: string, version: string): string {
+	const base = IMAGE_VARIANTS[variant] ?? IMAGE_VARIANTS.official;
+	const tag = variant === "official" ? version : "latest";
+	return `${base}:${tag}`;
+}
+
+// ─── Provider API Keys ──────────────────────────────────────────────────────
+
+const PROVIDER_ENV_KEYS = [
+	"OPENAI_API_KEY",
+	"ANTHROPIC_API_KEY",
+	"GOOGLE_API_KEY",
+	"XAI_API_KEY",
+	"DEEPSEEK_API_KEY",
+	"GROQ_API_KEY",
+	"OPENROUTER_API_KEY",
+	"MISTRAL_API_KEY",
+	"TOGETHER_API_KEY",
+	"OLLAMA_API_KEY",
+];
+
+// ─── OpenClaw Framework Definition ──────────────────────────────────────────
+
+export const openclawFramework: AgentFrameworkDefinition = {
+	id: "openclaw",
+	name: "OpenClaw",
+	icon: "🦀",
+	description: "Full-featured AI agent gateway with CLI, bridge, and skill system",
+	runtime: "node",
+	canBePrimary: true,
+	canBeCompanion: false,
+	networkName: "openclaw-network",
+	imageVariants: IMAGE_VARIANTS,
+	defaultImageVariant: "official",
+
+	buildGatewayService(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult {
+		const allVolumes = new Set<string>();
+
+		// Gateway environment
+		const gatewayEnv: Record<string, string> = {
+			HOME: "/home/node",
+			TERM: "xterm-256color",
+			OPENCLAW_GATEWAY_TOKEN: "${OPENCLAW_GATEWAY_TOKEN}",
+			OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: "${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}",
+			// Claude web-provider session vars (optional, user fills in .env)
+			CLAUDE_AI_SESSION_KEY: "${CLAUDE_AI_SESSION_KEY:-}",
+			CLAUDE_WEB_SESSION_KEY: "${CLAUDE_WEB_SESSION_KEY:-}",
+			CLAUDE_WEB_COOKIE: "${CLAUDE_WEB_COOKIE:-}",
+		};
+
+		// Add AI provider API keys to gateway environment
+		for (const key of PROVIDER_ENV_KEYS) {
+			gatewayEnv[key] = `\${${key}}`;
+		}
+
+		// Gateway volumes (bind-mount style matching real docker-setup.sh)
+		const gatewayVolumes: string[] = [
+			"${OPENCLAW_CONFIG_DIR:-./openclaw/config}:/home/node/.openclaw",
+			"${OPENCLAW_WORKSPACE_DIR:-./openclaw/workspace}:/home/node/.openclaw/workspace",
+		];
+
+		// Collect env vars and volume mounts from companion services
+		for (const { definition: def } of resolved.services) {
+			for (const env of def.openclawEnvVars) {
+				gatewayEnv[env.key] = env.secret ? `\${${env.key}}` : env.defaultValue;
+			}
+			if (def.openclawVolumeMounts) {
+				for (const vol of def.openclawVolumeMounts) {
+					const isBindMount =
+						vol.name.startsWith("./") || vol.name.startsWith("/") || vol.name.startsWith("~");
+					if (!isBindMount) {
+						allVolumes.add(vol.name);
+					}
+					gatewayVolumes.push(`${vol.name}:${vol.containerPath}`);
+				}
+			}
+		}
+
+		// Gateway service
+		const defaultImage = getOpenclawImage(
+			options.frameworkImageVariant ?? "official",
+			options.frameworkVersion,
+		);
+		const gateway: Record<string, unknown> = {
+			image: `\${OPENCLAW_IMAGE:-${defaultImage}}`,
+			environment: gatewayEnv,
+			volumes: gatewayVolumes,
+			ports: ["${OPENCLAW_GATEWAY_PORT:-18789}:18789", "${OPENCLAW_BRIDGE_PORT:-18790}:18790"],
+			networks: [this.networkName],
+			init: true,
+			restart: "unless-stopped",
+			command: [
+				"node",
+				"dist/index.js",
+				"gateway",
+				"--bind",
+				"${OPENCLAW_GATEWAY_BIND:-lan}",
+				"--port",
+				"18789",
+				"--allow-unconfigured",
+			],
+			healthcheck: {
+				test: [
+					"CMD",
+					"node",
+					"-e",
+					"fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
+				],
+				interval: "30s",
+				timeout: "5s",
+				retries: 5,
+				start_period: "20s",
+			},
+		};
+
+		// Traefik labels for the gateway
+		const gwTraefikLabels = options.traefikLabels?.get("openclaw-gateway");
+		if (gwTraefikLabels) {
+			gateway.labels = gwTraefikLabels;
+		}
+
+		if (options.bareMetalNativeHost) {
+			gateway.extra_hosts = ["host.docker.internal:host-gateway"];
+		}
+
+		if (dependsOn && Object.keys(dependsOn).length > 0) {
+			gateway.depends_on = dependsOn;
+		}
+
+		// CLI companion service (matching real OpenClaw docker-compose.yml)
+		const cliEnv: Record<string, string> = {
+			HOME: "/home/node",
+			TERM: "xterm-256color",
+			OPENCLAW_GATEWAY_TOKEN: "${OPENCLAW_GATEWAY_TOKEN}",
+			OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: "${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}",
+			BROWSER: "echo",
+			CLAUDE_AI_SESSION_KEY: "${CLAUDE_AI_SESSION_KEY:-}",
+			CLAUDE_WEB_SESSION_KEY: "${CLAUDE_WEB_SESSION_KEY:-}",
+			CLAUDE_WEB_COOKIE: "${CLAUDE_WEB_COOKIE:-}",
+		};
+
+		for (const key of PROVIDER_ENV_KEYS) {
+			cliEnv[key] = `\${${key}}`;
+		}
+
+		const cliService: Record<string, unknown> = {
+			image: `\${OPENCLAW_IMAGE:-${defaultImage}}`,
+			network_mode: "service:openclaw-gateway",
+			cap_drop: ["NET_RAW", "NET_ADMIN"],
+			security_opt: ["no-new-privileges:true"],
+			environment: cliEnv,
+			volumes: [
+				"${OPENCLAW_CONFIG_DIR:-./openclaw/config}:/home/node/.openclaw",
+				"${OPENCLAW_WORKSPACE_DIR:-./openclaw/workspace}:/home/node/.openclaw/workspace",
+			],
+			stdin_open: true,
+			tty: true,
+			init: true,
+			entrypoint: ["node", "dist/index.js"],
+			depends_on: ["openclaw-gateway"],
+		};
+
+		return { gatewayService: gateway, cliService, allVolumes };
+	},
+
+	generateConfig(resolved: ResolverOutput, options: FrameworkConfigOptions): FrameworkConfigResult {
+		const content = generateOpenClawConfig(resolved, {
+			deploymentType: options.deploymentType as any,
+			gatewayPort: options.gatewayPort,
+			openclawVersion: options.frameworkVersion,
+		});
+		return {
+			path: "openclaw/config/openclaw.json",
+			content,
+		};
+	},
+
+	getBaseEnvVars(options: FrameworkEnvOptions): EnvLine[] {
+		const version = options.frameworkVersion ?? "latest";
+		const gatewayToken = options.generateSecrets ? randomBytes(24).toString("hex") : "";
+
+		const imageVariantMap: Record<string, string> = {
+			official: "",
+			coolify: "coollabsio/openclaw:latest",
+			alpine: "alpine/openclaw:latest",
+		};
+		const imageValue = imageVariantMap[options.frameworkImageVariant ?? "official"] ?? "";
+
+		return [
+			{
+				comment: "OpenClaw version to deploy",
+				key: "OPENCLAW_VERSION",
+				exampleValue: version,
+				actualValue: version,
+			},
+			{
+				comment: "Authentication token for the OpenClaw gateway API",
+				key: "OPENCLAW_GATEWAY_TOKEN",
+				exampleValue: "your_gateway_token_here",
+				actualValue: gatewayToken,
+			},
+			{
+				comment: "Port the OpenClaw gateway listens on",
+				key: "OPENCLAW_GATEWAY_PORT",
+				exampleValue: "18789",
+				actualValue: "18789",
+			},
+			{
+				comment: "Port for the OpenClaw ACP bridge (WebSocket)",
+				key: "OPENCLAW_BRIDGE_PORT",
+				exampleValue: "18790",
+				actualValue: "18790",
+			},
+			{
+				comment:
+					"Gateway network bind mode: 'lan' (all interfaces, required for Docker). Use 'loopback' only for native (non-Docker) installs with Tailscale serve/funnel",
+				key: "OPENCLAW_GATEWAY_BIND",
+				exampleValue: "lan",
+				actualValue: "lan",
+			},
+			{
+				comment: "Host path to OpenClaw configuration directory",
+				key: "OPENCLAW_CONFIG_DIR",
+				exampleValue: "./openclaw/config",
+				actualValue: "./openclaw/config",
+			},
+			{
+				comment: "Host path to OpenClaw workspace directory",
+				key: "OPENCLAW_WORKSPACE_DIR",
+				exampleValue: "./openclaw/workspace",
+				actualValue: "./openclaw/workspace",
+			},
+			{
+				comment: `OpenClaw Docker image variant: ${options.frameworkImageVariant ?? "official"} (official, coolify, alpine)`,
+				key: "OPENCLAW_IMAGE",
+				exampleValue: "",
+				actualValue: imageValue,
+			},
+			{
+				comment:
+					"Extra bind mounts for gateway and CLI containers (comma-separated, format: source:target[:options])",
+				key: "OPENCLAW_EXTRA_MOUNTS",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "Named volume or host path for /home/node persistence across container restarts",
+				key: "OPENCLAW_HOME_VOLUME",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "Extra apt packages to install during Docker image build (space-separated)",
+				key: "OPENCLAW_DOCKER_APT_PACKAGES",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "Alternative auth: gateway password (use token OR password, not both)",
+				key: "OPENCLAW_GATEWAY_PASSWORD",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "Override state directory path (default: ~/.openclaw)",
+				key: "OPENCLAW_STATE_DIR",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "Override config file path (default: ~/.openclaw/openclaw.json)",
+				key: "OPENCLAW_CONFIG_PATH",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "Import missing keys from login shell profile (set to 1 to enable)",
+				key: "OPENCLAW_LOAD_SHELL_ENV",
+				exampleValue: "",
+				actualValue: "",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return ["convex", "mission-control", "tailscale"];
+	},
+
+	getRecommendedServices(): string[] {
+		return ["clawrouter"];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "OpenClaw Core";
+	},
+};

package/src/frameworks/registry.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import {
+	getAllFrameworks,
+	getCompanionFrameworks,
+	getFrameworkById,
+	getPrimaryFrameworks,
+} from "./registry.js";
+
+// Ensure all frameworks are auto-registered by importing the barrel
+import "./index.js";
+
+const EXPECTED_FRAMEWORK_IDS = [
+	"openclaw",
+	"copaw",
+	"nanoclaw",
+	"nanobot",
+	"zeroclaw",
+	"memu",
+	"claude-code",
+	"codex",
+];
+
+describe("framework registry", () => {
+	it("has all 8 frameworks registered", () => {
+		const all = getAllFrameworks();
+		expect(all.length).toBe(8);
+		const ids = all.map((fw) => fw.id);
+		for (const id of EXPECTED_FRAMEWORK_IDS) {
+			expect(ids).toContain(id);
+		}
+	});
+
+	it("returns undefined for unknown framework", () => {
+		expect(getFrameworkById("nonexistent")).toBeUndefined();
+	});
+
+	it("retrieves each framework by id", () => {
+		for (const id of EXPECTED_FRAMEWORK_IDS) {
+			const fw = getFrameworkById(id);
+			expect(fw).toBeDefined();
+			expect(fw!.id).toBe(id);
+			expect(fw!.name).toBeTruthy();
+			expect(fw!.icon).toBeTruthy();
+			expect(fw!.description).toBeTruthy();
+		}
+	});
+
+	it("all frameworks expose required methods", () => {
+		for (const fw of getAllFrameworks()) {
+			expect(typeof fw.buildGatewayService).toBe("function");
+			expect(typeof fw.generateConfig).toBe("function");
+			expect(typeof fw.getBaseEnvVars).toBe("function");
+			expect(typeof fw.getMandatoryServices).toBe("function");
+			expect(typeof fw.getRecommendedServices).toBe("function");
+			expect(typeof fw.getProviderEnvKeys).toBe("function");
+			expect(typeof fw.getEnvSectionName).toBe("function");
+		}
+	});
+
+	it("getPrimaryFrameworks returns only frameworks with canBePrimary", () => {
+		const primaries = getPrimaryFrameworks();
+		for (const fw of primaries) {
+			expect(fw.canBePrimary).toBe(true);
+		}
+		expect(primaries.length).toBeGreaterThanOrEqual(1);
+		// OpenClaw must always be a primary
+		expect(primaries.some((fw) => fw.id === "openclaw")).toBe(true);
+	});
+
+	it("getCompanionFrameworks returns only frameworks with canBeCompanion", () => {
+		const companions = getCompanionFrameworks();
+		for (const fw of companions) {
+			expect(fw.canBeCompanion).toBe(true);
+		}
+	});
+
+	it("openclaw has mandatory services (convex, mission-control, tailscale)", () => {
+		const openclaw = getFrameworkById("openclaw")!;
+		const mandatory = openclaw.getMandatoryServices();
+		expect(mandatory).toContain("convex");
+		expect(mandatory).toContain("mission-control");
+		expect(mandatory).toContain("tailscale");
+	});
+
+	it("memu has postgresql as mandatory service", () => {
+		const memu = getFrameworkById("memu")!;
+		expect(memu.getMandatoryServices()).toContain("postgresql");
+	});
+
+	it("non-openclaw frameworks do not require convex/mission-control/tailscale", () => {
+		for (const id of ["copaw", "nanoclaw", "nanobot", "zeroclaw", "claude-code", "codex"]) {
+			const fw = getFrameworkById(id)!;
+			const mandatory = fw.getMandatoryServices();
+			expect(mandatory).not.toContain("convex");
+			expect(mandatory).not.toContain("mission-control");
+			expect(mandatory).not.toContain("tailscale");
+		}
+	});
+
+	it("openclaw and copaw recommend clawrouter", () => {
+		const openclaw = getFrameworkById("openclaw")!;
+		expect(openclaw.getRecommendedServices()).toContain("clawrouter");
+
+		const copaw = getFrameworkById("copaw")!;
+		expect(copaw.getRecommendedServices()).toContain("clawrouter");
+	});
+
+	it("other frameworks do not recommend clawrouter", () => {
+		for (const id of ["nanoclaw", "nanobot", "zeroclaw", "claude-code", "codex"]) {
+			const fw = getFrameworkById(id)!;
+			expect(fw.getRecommendedServices()).not.toContain("clawrouter");
+		}
+	});
+
+	it("each framework has a unique network name", () => {
+		const names = getAllFrameworks().map((fw) => fw.networkName);
+		expect(new Set(names).size).toBe(names.length);
+	});
+
+	it("each framework provides env vars via getBaseEnvVars", () => {
+		for (const fw of getAllFrameworks()) {
+			const vars = fw.getBaseEnvVars({});
+			expect(Array.isArray(vars)).toBe(true);
+			// Each env var should have key and comment
+			for (const v of vars) {
+				expect(v.key).toBeTruthy();
+				expect(typeof v.comment).toBe("string");
+			}
+		}
+	});
+});

package/src/frameworks/registry.ts

@@ -0,0 +1,28 @@
+import type { AgentFrameworkDefinition, AgentFrameworkId } from "./types.js";
+
+const frameworkMap = new Map<AgentFrameworkId, AgentFrameworkDefinition>();
+
+/** Register a framework implementation. */
+export function registerFramework(fw: AgentFrameworkDefinition): void {
+	frameworkMap.set(fw.id, fw);
+}
+
+/** Get a framework by its ID. Returns undefined if not registered. */
+export function getFrameworkById(id: string): AgentFrameworkDefinition | undefined {
+	return frameworkMap.get(id as AgentFrameworkId);
+}
+
+/** Get all registered frameworks. */
+export function getAllFrameworks(): AgentFrameworkDefinition[] {
+	return [...frameworkMap.values()];
+}
+
+/** Get all frameworks that can be a primary orchestrator. */
+export function getPrimaryFrameworks(): AgentFrameworkDefinition[] {
+	return getAllFrameworks().filter((fw) => fw.canBePrimary);
+}
+
+/** Get all frameworks that can run as companions. */
+export function getCompanionFrameworks(): AgentFrameworkDefinition[] {
+	return getAllFrameworks().filter((fw) => fw.canBeCompanion);
+}

package/src/frameworks/types.ts

@@ -0,0 +1,146 @@
+import type { ResolverOutput } from "../types.js";
+
+// ─── Framework Identifiers ──────────────────────────────────────────────────
+
+export type AgentFrameworkId =
+	| "openclaw"
+	| "copaw"
+	| "nanoclaw"
+	| "nanobot"
+	| "zeroclaw"
+	| "memu"
+	| "claude-code"
+	| "codex";
+
+// ─── Gateway Build Types ────────────────────────────────────────────────────
+
+export interface GatewayBuildResult {
+	gatewayService: Record<string, unknown>;
+	cliService: Record<string, unknown> | null;
+	allVolumes: Set<string>;
+}
+
+export interface FrameworkComposeOptions {
+	projectName: string;
+	proxy: string;
+	proxyHttpPort?: number;
+	proxyHttpsPort?: number;
+	domain?: string;
+	gpu: boolean;
+	platform: string;
+	deployment: string;
+	frameworkVersion: string;
+	frameworkImageVariant: string;
+	bareMetalNativeHost?: boolean;
+	traefikLabels?: Map<string, Record<string, string>>;
+	hardened: boolean;
+	frameworkInstallMethod: string;
+}
+
+// ─── Env Line (for env file generation) ─────────────────────────────────────
+
+export interface EnvLine {
+	comment: string;
+	key: string;
+	exampleValue: string;
+	actualValue: string;
+}
+
+export interface FrameworkEnvOptions {
+	generateSecrets: boolean;
+	domain?: string;
+	frameworkVersion: string;
+	frameworkImageVariant: string;
+}
+
+// ─── Config Generation ──────────────────────────────────────────────────────
+
+export interface FrameworkConfigOptions {
+	deploymentType: string;
+	gatewayPort: number;
+	frameworkVersion: string;
+}
+
+export interface FrameworkConfigResult {
+	/** File path relative to project root (e.g. "openclaw/config/openclaw.json") */
+	path: string;
+	/** File content (JSON, YAML, TOML, etc.) */
+	content: string;
+}
+
+// ─── Agent Framework Definition ─────────────────────────────────────────────
+
+export interface AgentFrameworkDefinition {
+	/** Unique identifier, kebab-case. */
+	id: AgentFrameworkId;
+
+	/** Human-readable name. */
+	name: string;
+
+	/** Icon for UI display. */
+	icon: string;
+
+	/** Short description for CLI/Web UI selection. */
+	description: string;
+
+	/** Primary language/runtime of this framework. */
+	runtime: "node" | "python" | "rust" | "go";
+
+	/** Whether this framework can serve as the primary orchestrator (gateway). */
+	canBePrimary: boolean;
+
+	/** Whether this framework can run as a companion service alongside another primary. */
+	canBeCompanion: boolean;
+
+	/** Docker network name this framework uses (replaces hardcoded "openclaw-network"). */
+	networkName: string;
+
+	/** Map of image variant names to Docker image strings. */
+	imageVariants: Record<string, string>;
+
+	/** Default image variant key. */
+	defaultImageVariant: string;
+
+	/**
+	 * Build the gateway (primary orchestrator) service entry for docker-compose.
+	 * Returns null if this framework cannot be primary.
+	 */
+	buildGatewayService(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult;
+
+	/**
+	 * Build a companion container entry (when running alongside another primary).
+	 * Returns null if this framework cannot be a companion.
+	 */
+	buildCompanionService?(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+	): Record<string, unknown> | null;
+
+	/**
+	 * Generate the framework-specific config file (like openclaw.json).
+	 * Returns null if no config file is needed.
+	 */
+	generateConfig(
+		resolved: ResolverOutput,
+		options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null;
+
+	/** Framework-specific env vars to include in .env files. */
+	getBaseEnvVars(options: FrameworkEnvOptions): EnvLine[];
+
+	/** Service IDs that are mandatory when this framework is primary. */
+	getMandatoryServices(): string[];
+
+	/** Service IDs that are recommended when this framework is primary. */
+	getRecommendedServices(): string[];
+
+	/** AI provider API key env var names to inject into gateway environment. */
+	getProviderEnvKeys(): string[];
+
+	/** Section header name for .env file comments (e.g. "OpenClaw Core"). */
+	getEnvSectionName(): string;
+}