@better-openclaw/core 1.0.22 → 1.0.24

package/src/generators/env.ts

@@ -203,6 +203,54 @@ export function generateEnvFiles(
 		actualValue: "",
 	});
 
+	lines.push({
+		comment: formatComment(
+			"Alternative auth: gateway password (use token OR password, not both)",
+			"OpenClaw Core",
+			false,
+			true,
+		),
+		key: "OPENCLAW_GATEWAY_PASSWORD",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Override state directory path (default: ~/.openclaw)",
+			"OpenClaw Core",
+			false,
+			false,
+		),
+		key: "OPENCLAW_STATE_DIR",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Override config file path (default: ~/.openclaw/openclaw.json)",
+			"OpenClaw Core",
+			false,
+			false,
+		),
+		key: "OPENCLAW_CONFIG_PATH",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Import missing keys from login shell profile (set to 1 to enable)",
+			"OpenClaw Core",
+			false,
+			false,
+		),
+		key: "OPENCLAW_LOAD_SHELL_ENV",
+		exampleValue: "",
+		actualValue: "",
+	});
+
 	if (options.domain) {
 		lines.push({
 			comment: formatComment("Primary domain for service routing", "OpenClaw Core", false, false),
@@ -212,6 +260,98 @@ export function generateEnvFiles(
 		});
 	}
 
+	// ── Tools API Keys (web search, fetch) ──────────────────────────────────
+
+	lines.push({
+		comment:
+			"\n# ═══════════════════════════════════════════════════════════════════════════════\n# Tools API Keys (web search, fetch, voice)\n# ═══════════════════════════════════════════════════════════════════════════════",
+		key: "",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Brave Search API key for web search tool (default provider)",
+			"OpenClaw Tools",
+			false,
+			true,
+		),
+		key: "BRAVE_API_KEY",
+		exampleValue: "your_brave_api_key_here",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Perplexity API key for web search tool (alternative provider)",
+			"OpenClaw Tools",
+			false,
+			true,
+		),
+		key: "PERPLEXITY_API_KEY",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Firecrawl API key for enhanced web fetch fallback",
+			"OpenClaw Tools",
+			false,
+			true,
+		),
+		key: "FIRECRAWL_API_KEY",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"ElevenLabs API key for Talk mode (text-to-speech)",
+			"OpenClaw Tools",
+			false,
+			true,
+		),
+		key: "ELEVENLABS_API_KEY",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	// ── Swarm / Remote Gateway ───────────────────────────────────────────────
+
+	lines.push({
+		comment:
+			"\n# ═══════════════════════════════════════════════════════════════════════════════\n# Swarm / Remote Gateway Connection\n# ═══════════════════════════════════════════════════════════════════════════════",
+		key: "",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Auth token for connecting to a remote OpenClaw gateway (swarm upstream)",
+			"OpenClaw Swarm",
+			false,
+			true,
+		),
+		key: "OPENCLAW_REMOTE_GATEWAY_TOKEN",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Password for remote gateway auth (alternative to token)",
+			"OpenClaw Swarm",
+			false,
+			true,
+		),
+		key: "OPENCLAW_REMOTE_GATEWAY_PASSWORD",
+		exampleValue: "",
+		actualValue: "",
+	});
+
 	// ── AI Provider API Keys ─────────────────────────────────────────────────
 
 	if (resolved.aiProviders && resolved.aiProviders.length > 0) {
@@ -334,7 +474,17 @@ export function generateEnvFiles(
 		"OPENCLAW_EXTRA_MOUNTS",
 		"OPENCLAW_HOME_VOLUME",
 		"OPENCLAW_DOCKER_APT_PACKAGES",
+		"OPENCLAW_GATEWAY_PASSWORD",
+		"OPENCLAW_STATE_DIR",
+		"OPENCLAW_CONFIG_PATH",
+		"OPENCLAW_LOAD_SHELL_ENV",
 		"OPENCLAW_DOMAIN",
+		"BRAVE_API_KEY",
+		"PERPLEXITY_API_KEY",
+		"FIRECRAWL_API_KEY",
+		"ELEVENLABS_API_KEY",
+		"OPENCLAW_REMOTE_GATEWAY_TOKEN",
+		"OPENCLAW_REMOTE_GATEWAY_PASSWORD",
 		"CLAUDE_AI_SESSION_KEY",
 		"CLAUDE_WEB_SESSION_KEY",
 		"CLAUDE_WEB_COOKIE",
@@ -406,6 +556,7 @@ export function generateEnvFiles(
 		"# ═══════════════════════════════════════════════════════════════════════════════",
 		"# OpenClaw Environment Configuration",
 		`# Generated at ${new Date().toISOString()}`,
+		"# Docs: https://better-openclaw.dev/docs | Cloud: https://clawexa.net",
 		"# ═══════════════════════════════════════════════════════════════════════════════",
 		"",
 	].join("\n");
@@ -491,6 +642,69 @@ export function getStructuredEnvVars(resolved: ResolverOutput): EnvVarGroup[] {
 			required: true,
 			defaultValue: "18789",
 		},
+		{
+			key: "OPENCLAW_GATEWAY_PASSWORD",
+			description: "Alternative auth: gateway password (use token OR password)",
+			secret: true,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "OPENCLAW_STATE_DIR",
+			description: "Override state directory path (default: ~/.openclaw)",
+			secret: false,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "OPENCLAW_CONFIG_PATH",
+			description: "Override config file path (default: ~/.openclaw/openclaw.json)",
+			secret: false,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "BRAVE_API_KEY",
+			description: "Brave Search API key for web search tool (default provider)",
+			secret: true,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "PERPLEXITY_API_KEY",
+			description: "Perplexity API key for web search (alternative provider)",
+			secret: true,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "FIRECRAWL_API_KEY",
+			description: "Firecrawl API key for enhanced web fetch fallback",
+			secret: true,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "ELEVENLABS_API_KEY",
+			description: "ElevenLabs API key for Talk mode (text-to-speech)",
+			secret: true,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "OPENCLAW_REMOTE_GATEWAY_TOKEN",
+			description: "Auth token for connecting to a remote OpenClaw gateway (swarm upstream)",
+			secret: true,
+			required: false,
+			defaultValue: "",
+		},
+		{
+			key: "OPENCLAW_REMOTE_GATEWAY_PASSWORD",
+			description: "Password for remote gateway auth (alternative to token)",
+			secret: true,
+			required: false,
+			defaultValue: "",
+		},
 	];
 
 	for (const v of coreVars) {

package/src/generators/openclaw-json.ts

@@ -459,7 +459,31 @@ export function generateOpenClawConfig(
 				workspace: isDocker ? "/home/node/.openclaw/workspace" : "./workspace",
 				compaction: { mode: "safeguard" },
 				maxConcurrent: 4,
-				subagents: { maxConcurrent: 8 },
+				subagents: {
+					maxConcurrent: 8,
+					// Allow spawning sub-agents under any agent ID (essential for swarm collaboration)
+					allowAgents: ["*"],
+				},
+				// Sandbox defaults for agent exec isolation
+				...(isDocker
+					? {
+							sandbox: {
+								docker: {
+									containerPrefix: "openclaw-sandbox",
+									workdir: "/workspace",
+									readOnlyRoot: true,
+									network: "none",
+									capDrop: ["ALL"],
+									pidsLimit: 256,
+									memory: "512m",
+								},
+								browser: {
+									enabled: false,
+									autoStart: false,
+								},
+							},
+						}
+					: {}),
 			},
 		},
 		messages: {
@@ -490,12 +514,23 @@ export function generateOpenClawConfig(
 			wideArea: {
 				enabled: true,
 			},
+			// mDNS/Bonjour for local-network instance discovery (swarm auto-discovery)
+			// "minimal" hides sensitive metadata; "full" exposes cliPath/sshPort for easier discovery
+			mdns: {
+				mode: isDocker ? "off" : "minimal",
+			},
 		},
 		canvasHost: {
 			enabled: true,
 			liveReload: true,
 		},
 		channels: {},
+		// Node host config — controls how this instance exposes services to other gateway nodes
+		nodeHost: {
+			browserProxy: {
+				enabled: true,
+			},
+		},
 		gateway: {
 			port: options.gatewayPort,
 			mode: "local",
@@ -517,9 +552,41 @@ export function generateOpenClawConfig(
 			},
 			// Tailscale serve only works on bare-metal/local (not inside Docker containers)
 			...(isDocker ? {} : { tailscale: { mode: "serve", resetOnExit: true } }),
+			reload: {
+				mode: "hybrid",
+			},
+			http: {
+				endpoints: {
+					chatCompletions: { enabled: false },
+					responses: { enabled: false },
+				},
+			},
 			nodes: {
+				browser: {
+					// "auto" lets gateway pick best node for browser proxying; "manual" pins to specific node
+					mode: "auto",
+				},
+				// Allowlist/denylist for node.invoke commands across the swarm
+				allowCommands: [],
 				denyCommands: ["camera.snap", "camera.clip", "screen.record"],
 			},
+			// Remote gateway connection — enables this instance to connect to another OpenClaw gateway
+			// Configure for swarm topologies: each instance can connect to one upstream gateway
+			// Transport: "direct" = WebSocket (ws/wss), "ssh" = SSH tunnel for secure remote access
+			remote: {
+				// url: "wss://gateway.example.com:18789",  // Remote gateway WebSocket URL
+				transport: "direct",
+				// token: "${OPENCLAW_REMOTE_GATEWAY_TOKEN}",  // Auth token for the remote gateway
+				// sshTarget: "user@gateway-host",  // For SSH tunnel transport
+				// sshIdentity: "~/.ssh/id_ed25519",  // SSH key for tunnel
+				// tlsFingerprint: "",  // Pin remote gateway TLS cert (sha256)
+			},
+			channelHealthCheckMinutes: 5,
+		},
+		browser: {
+			enabled: true,
+			// WSL2 users may need relayBindHost: "0.0.0.0" for cross-namespace access
+			...(isDocker ? {} : { relayBindHost: "127.0.0.1" }),
 		},
 		skills: {
 			install: { nodeManager: "pnpm" },
@@ -528,6 +595,94 @@ export function generateOpenClawConfig(
 			},
 			...(Object.keys(defaultSkills).length > 0 ? { entries: defaultSkills } : {}),
 		},
+		// ACP (Agent Client Protocol) — external agents can connect to the gateway
+		// Disabled by default; enable when using ACP-compatible agents (e.g. acpx)
+		acp: {
+			enabled: false,
+			dispatch: { enabled: false },
+			maxConcurrentSessions: 4,
+			stream: {
+				deliveryMode: "live",
+				repeatSuppression: true,
+			},
+			runtime: {
+				ttlMinutes: 30,
+			},
+		},
+		// Tools configuration — web search, fetch, exec security, loop detection
+		tools: {
+			web: {
+				search: {
+					// Enabled when a search API key is available (BRAVE_API_KEY, etc.)
+					enabled: true,
+					provider: "brave",
+					maxResults: 5,
+					timeoutSeconds: 10,
+					cacheTtlMinutes: 60,
+				},
+				fetch: {
+					enabled: true,
+					maxChars: 30000,
+					timeoutSeconds: 15,
+					cacheTtlMinutes: 30,
+					readability: true,
+				},
+			},
+			exec: {
+				// Docker: sandbox exec inside a nested container; bare-metal: deny by default
+				host: isDocker ? "sandbox" : "gateway",
+				security: "allowlist",
+				ask: "on-miss",
+				backgroundMs: 30000,
+				timeoutSec: 300,
+			},
+			// Filesystem path guards
+			fs: {
+				// In Docker the workspace is already isolated; on bare-metal restrict to workspace
+				workspaceOnly: !isDocker,
+			},
+			// Prevent stuck tool-call loops
+			loopDetection: {
+				enabled: true,
+				historySize: 30,
+				warningThreshold: 10,
+				criticalThreshold: 20,
+				globalCircuitBreakerThreshold: 30,
+			},
+			sessions: {
+				visibility: "tree",
+			},
+			// Agent-to-agent messaging — allows agents to invoke each other at runtime
+			// Essential for swarm architectures where multiple OpenClaw instances collaborate
+			agentToAgent: {
+				enabled: true,
+				// Allowlist of agent IDs or patterns that can be reached; "*" = any agent
+				allow: ["*"],
+			},
+		},
+		// Session-level agent-to-agent safety limits
+		session: {
+			agentToAgent: {
+				// Max ping-pong turns between requester and target agent (prevents infinite loops)
+				maxPingPongTurns: 5,
+			},
+		},
+		// Memory — vector search over session history and markdown notes
+		memory: {
+			backend: "builtin",
+			citations: "auto",
+		},
+		// UI customization
+		ui: {
+			assistant: {
+				name: "OpenClaw",
+			},
+		},
+		// Media retention
+		media: {
+			preserveFilenames: true,
+			ttlHours: 168, // 7 days
+		},
 		plugins: {
 			enabled: true,
 			entries: {

package/src/generators/postgres-init.ts

@@ -52,6 +52,23 @@ const DB_REQUIREMENTS: Record<string, Omit<DbRequirement, "serviceId" | "service
 	openpanel: { dbName: "openpanel", dbUser: "openpanel", passwordEnvVar: "OPENPANEL_DB_PASSWORD" },
 	usesend: { dbName: "usesend", dbUser: "usesend", passwordEnvVar: "USESEND_DB_PASSWORD" },
 	nextcloud: { dbName: "nextcloud", dbUser: "nextcloud", passwordEnvVar: "NEXTCLOUD_DB_PASSWORD" },
+	// ── SaaS Boilerplates ────────────────────────────────────────────────────
+	"open-saas": { dbName: "opensaas", dbUser: "opensaas", passwordEnvVar: "OPENSAAS_DB_PASSWORD" },
+	"apptension-saas": {
+		dbName: "apptensionsaas",
+		dbUser: "apptensionsaas",
+		passwordEnvVar: "APPTENSION_SAAS_DB_PASSWORD",
+	},
+	"boxyhq-saas": {
+		dbName: "boxyhqsaas",
+		dbUser: "boxyhqsaas",
+		passwordEnvVar: "BOXYHQ_SAAS_DB_PASSWORD",
+	},
+	"ixartz-saas": {
+		dbName: "ixartzsaas",
+		dbUser: "ixartzsaas",
+		passwordEnvVar: "IXARTZ_SAAS_DB_PASSWORD",
+	},
 };
 
 /**

package/src/generators/readme.ts

@@ -366,7 +366,8 @@ ${warningList}
 
 	sections.push(`---
 
-Generated by [OpenClaw](https://openclaw.dev) • ${new Date().toISOString().split("T")[0]}
+Generated by [better-openclaw](https://better-openclaw.dev) • ${new Date().toISOString().split("T")[0]}
+Deploy without managing servers: [Clawexa Cloud](https://clawexa.net)
 `);
 
 	return sections.join("\n");

package/src/generators/scripts.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import { generateScripts } from "./scripts.js";
 
 describe("generateScripts", () => {
-	it("generates all 5 expected scripts", () => {
+	it("generates all 10 expected scripts (5 bash + 5 PowerShell)", () => {
 		const result = generateScripts();
 
 		const expectedScripts = [
@@ -11,6 +11,11 @@ describe("generateScripts", () => {
 			"scripts/update.sh",
 			"scripts/backup.sh",
 			"scripts/status.sh",
+			"scripts/start.ps1",
+			"scripts/stop.ps1",
+			"scripts/update.ps1",
+			"scripts/backup.ps1",
+			"scripts/status.ps1",
 		];
 
 		for (const script of expectedScripts) {
@@ -50,11 +55,54 @@ describe("generateScripts", () => {
 		expect(result["scripts/status.sh"]).toContain("ps");
 	});
 
-	it("all scripts start with bash shebang", () => {
+	it("all bash scripts start with shebang", () => {
 		const result = generateScripts();
 
-		for (const [, content] of Object.entries(result)) {
-			expect(content.startsWith("#!/")).toBe(true);
+		for (const [path, content] of Object.entries(result)) {
+			if (path.endsWith(".sh")) {
+				expect(content.startsWith("#!/")).toBe(true);
+			}
 		}
 	});
+
+	it("all PowerShell scripts start with #Requires", () => {
+		const result = generateScripts();
+
+		for (const [path, content] of Object.entries(result)) {
+			if (path.endsWith(".ps1")) {
+				expect(content.startsWith("#Requires")).toBe(true);
+			}
+		}
+	});
+
+	it("start.ps1 calls docker compose up", () => {
+		const result = generateScripts();
+		expect(result["scripts/start.ps1"]).toContain("docker compose");
+		expect(result["scripts/start.ps1"]).toContain("up");
+	});
+
+	it("stop.ps1 calls docker compose down", () => {
+		const result = generateScripts();
+		expect(result["scripts/stop.ps1"]).toContain("docker compose");
+		expect(result["scripts/stop.ps1"]).toContain("down");
+	});
+
+	it("update.ps1 calls docker compose pull", () => {
+		const result = generateScripts();
+		expect(result["scripts/update.ps1"]).toContain("docker compose");
+		expect(result["scripts/update.ps1"]).toContain("pull");
+	});
+
+	it("backup.ps1 references volumes or backup", () => {
+		const result = generateScripts();
+		const backup = result["scripts/backup.ps1"]!;
+		expect(backup).toBeDefined();
+		expect(backup.length).toBeGreaterThan(50);
+	});
+
+	it("status.ps1 calls docker compose ps", () => {
+		const result = generateScripts();
+		expect(result["scripts/status.ps1"]).toContain("docker compose");
+		expect(result["scripts/status.ps1"]).toContain("ps");
+	});
 });