clawchef 0.1.8 → 0.1.9

package/README.md

@@ -15,10 +15,11 @@ Recipe-driven OpenClaw environment orchestrator.
 - Supports scoped execution via `--scope full|files|workspace`.
 - `full` scope runs factory reset first (with confirmation prompt unless `-s/--silent` is used).
 - If `openclaw` is missing, auto-installs the recipe version and skips factory reset.
-- Starts OpenClaw gateway service after each recipe execution.
+- Starts OpenClaw gateway after each recipe execution based on `--gateway-mode`.
 - Creates workspaces and agents (default workspace path: `~/.openclaw/workspace-<workspace-name>`).
 - Supports workspace-level assets copy via `workspaces[].assets`.
 - Materializes files into target workspaces.
+- Supports OpenClaw root-level assets/files via `openclaw.root` (default root path: `~/.openclaw`).
 - Installs skills.
 - Supports plugin preinstall via `openclaw.plugins[]` and runtime `--plugin` flags.
 - Configures channels with `openclaw channels add`.
@@ -90,6 +91,14 @@ Skip reset confirmation prompt:
 clawchef cook recipes/sample.yaml -s
 ```
 
+Control gateway startup mode:
+
+```bash
+clawchef cook recipes/sample.yaml --gateway-mode service
+clawchef cook recipes/sample.yaml --gateway-mode run
+clawchef cook recipes/sample.yaml --gateway-mode none
+```
+
 Warning: `-s/--silent` suppresses the factory-reset confirmation and auto-chooses force reinstall on version mismatch.
 Use it only in CI/non-interactive flows where destructive reset behavior is expected.
 
@@ -204,6 +213,7 @@ await scaffold("./my-recipe-project", {
 - `plugins`: plugin npm specs to preinstall for this run (`string[]`)
 - `scope`: `full | files | workspace` (default: `full`)
 - `workspaceName`: required when `scope: "workspace"`
+- `gatewayMode`: `service | run | none` (default: `service`)
 - `provider`: `command | remote | mock`
 - `remote`: remote provider config (same fields as CLI remote flags)
 - `envFile`: custom env file path/URL; when set, default cwd `.env` loading is skipped
@@ -307,6 +317,8 @@ Supported operation values sent by clawchef:
 - `configure_channel`, `bind_channel_agent`, `login_channel`
 - `run_agent`
 
+For `start_gateway`, clawchef sends `{ mode: "service" | "run" }` in payload when gateway mode is enabled.
+
 For `run_agent`, clawchef expects `output` in response for assertions.
 
 `command` provider now defaults to the current OpenClaw CLI shape (`openclaw 2026.x`), including:
@@ -352,6 +364,7 @@ For `command` provider, default command templates are:
 - `install_plugin`: `${bin} plugins install ${plugin_spec_q}`
 - `factory_reset`: `${bin} reset --scope full --yes --non-interactive`
 - `start_gateway`: `${bin} gateway start`
+- `run_gateway`: `${bin} gateway run`
 - `bind_channel_agent`: built-in `openclaw config get/set bindings` upsert (override with `openclaw.commands.bind_channel_agent`)
 - `login_channel`: `${bin} channels login --channel ${channel_q}${account_arg}`
 - `create_workspace`: generated from `openclaw.bootstrap` (override with `openclaw.commands.create_workspace`)
@@ -426,9 +439,31 @@ workspaces:
     assets: "./meetingbot-assets"
 ```
 
+## OpenClaw root files
+
+- `openclaw.root.path` is optional.
+- If omitted, clawchef uses `~/.openclaw`.
+- `openclaw.root.assets` is optional and recursively copied into the root directory.
+- `openclaw.root.files[]` runs after assets copy, so explicit file entries can override copied assets.
+- `openclaw.root.assets` is resolved relative to the recipe file path (unless absolute path is given).
+- Direct URL recipes do not support `openclaw.root.assets` (assets must resolve to a local directory).
+- `openclaw.root` currently supports `command` and `mock` providers; `remote` provider is not supported.
+
+Example:
+
+```yaml
+openclaw:
+  version: "2026.2.9"
+  root:
+    assets: "./openclaw-root-assets"
+    files:
+      - path: "AGENTS.md"
+        content_from: "./snippets/agents-template.md"
+```
+
 ## File content references
 
-In `workspaces[].files[]`, set exactly one of:
+In `workspaces[].files[]` and `openclaw.root.files[]`, set exactly one of:
 
 - `content`: inline text in recipe
 - `content_from`: load text from another file/URL (loaded content supports `${var}` template rendering)

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { OpenClawProvider, OpenClawRemoteConfig, RunScope } from "./types.js";
+import type { GatewayMode, OpenClawProvider, OpenClawRemoteConfig, RunScope } from "./types.js";
 import type { ScaffoldOptions, ScaffoldResult } from "./scaffold.js";
 export interface CookOptions {
     vars?: Record<string, string>;
@@ -9,6 +9,7 @@ export interface CookOptions {
     silent?: boolean;
     scope?: RunScope;
     workspaceName?: string;
+    gatewayMode?: GatewayMode;
     provider?: OpenClawProvider;
     remote?: Partial<OpenClawRemoteConfig>;
     envFile?: string;

package/dist/api.js

@@ -21,6 +21,7 @@ function normalizeCookOptions(options) {
         plugins,
         scope,
         workspaceName,
+        gatewayMode: options.gatewayMode ?? "service",
         dryRun: Boolean(options.dryRun),
         allowMissing: Boolean(options.allowMissing),
         verbose: Boolean(options.verbose),

package/dist/cli.js

@@ -61,6 +61,12 @@ function parseScope(value) {
     }
     throw new ClawChefError(`Invalid --scope value: ${value}. Expected full, files, or workspace`);
 }
+function parseGatewayMode(value) {
+    if (value === "service" || value === "run" || value === "none") {
+        return value;
+    }
+    throw new ClawChefError(`Invalid --gateway-mode value: ${value}. Expected service, run, or none`);
+}
 function parseOptionalInt(value, fieldName) {
     if (value === undefined) {
         return undefined;
@@ -101,6 +107,7 @@ export function buildCli() {
         .option("-s, --silent", "Skip reset confirmation prompt", false)
         .option("--scope <scope>", "Run scope: full | files | workspace", "full")
         .option("--workspace <name>", "Workspace name (required when --scope workspace)")
+        .option("--gateway-mode <mode>", "Gateway mode: service | run | none", "service")
         .option("--dotenv-ref <path-or-url>", "Load env vars from local file or HTTP URL")
         .option("--provider <provider>", "Execution provider: command | remote | mock")
         .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p) => p.concat([v]), [])
@@ -119,6 +126,7 @@ export function buildCli() {
         }
         const provider = parseProvider(opts.provider ?? readEnv("CLAWCHEF_PROVIDER") ?? "command");
         const scope = parseScope(String(opts.scope ?? "full"));
+        const gatewayMode = parseGatewayMode(String(opts.gatewayMode ?? "service"));
         const workspaceName = opts.workspace?.trim() ? String(opts.workspace).trim() : undefined;
         if (scope === "workspace" && !workspaceName) {
             throw new ClawChefError("--scope workspace requires --workspace <name>");
@@ -131,6 +139,7 @@ export function buildCli() {
             plugins: parsePluginFlags(opts.plugin),
             scope,
             workspaceName,
+            gatewayMode,
             dryRun: Boolean(opts.dryRun),
             allowMissing: Boolean(opts.allowMissing),
             verbose: Boolean(opts.verbose),

package/dist/openclaw/command-provider.d.ts

@@ -1,11 +1,11 @@
-import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../types.js";
+import type { AgentDef, ChannelDef, ConversationDef, GatewayMode, OpenClawSection } from "../types.js";
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class CommandOpenClawProvider implements OpenClawProvider {
     private readonly stagedMessages;
     ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean, preserveExistingState: boolean): Promise<EnsureVersionResult>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
-    startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;
+    startGateway(config: OpenClawSection, mode: GatewayMode, dryRun: boolean): Promise<void>;
     createWorkspace(config: OpenClawSection, workspace: ResolvedWorkspaceDef, dryRun: boolean): Promise<void>;
     configureChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void>;
     bindChannelAgent(config: OpenClawSection, channel: ChannelDef, agent: string, dryRun: boolean): Promise<void>;

package/dist/openclaw/command-provider.js

@@ -13,6 +13,7 @@ const DEFAULT_COMMANDS = {
     install_plugin: "${bin} plugins install ${plugin_spec_q}",
     factory_reset: "${bin} reset --scope full --yes --non-interactive",
     start_gateway: "${bin} gateway start",
+    run_gateway: "${bin} gateway run",
     enable_plugin: "",
     bind_channel_agent: "",
     login_channel: "${bin} channels login --channel ${channel_q}${account_arg}",
@@ -362,9 +363,13 @@ export class CommandOpenClawProvider {
         }
         await runShell(cmd, dryRun);
     }
-    async startGateway(config, dryRun) {
+    async startGateway(config, mode, dryRun) {
+        if (mode === "none") {
+            return;
+        }
         const bin = config.bin ?? "openclaw";
-        const startCmd = commandFor(config, "start_gateway", { bin, version: config.version });
+        const key = mode === "run" ? "run_gateway" : "start_gateway";
+        const startCmd = commandFor(config, key, { bin, version: config.version });
         if (!startCmd.trim()) {
             return;
         }

package/dist/openclaw/mock-provider.d.ts

@@ -1,11 +1,11 @@
-import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../types.js";
+import type { AgentDef, ChannelDef, ConversationDef, GatewayMode, OpenClawSection } from "../types.js";
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class MockOpenClawProvider implements OpenClawProvider {
     private state;
     ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean, _preserveExistingState: boolean): Promise<EnsureVersionResult>;
     installPlugin(_config: OpenClawSection, _pluginSpec: string, _dryRun: boolean): Promise<void>;
     factoryReset(_config: OpenClawSection, _dryRun: boolean): Promise<void>;
-    startGateway(_config: OpenClawSection, _dryRun: boolean): Promise<void>;
+    startGateway(_config: OpenClawSection, _mode: GatewayMode, _dryRun: boolean): Promise<void>;
     createWorkspace(_config: OpenClawSection, workspace: ResolvedWorkspaceDef, _dryRun: boolean): Promise<void>;
     configureChannel(_config: OpenClawSection, channel: ChannelDef, _dryRun: boolean): Promise<void>;
     bindChannelAgent(_config: OpenClawSection, _channel: ChannelDef, _agent: string, _dryRun: boolean): Promise<void>;

package/dist/openclaw/mock-provider.js

@@ -35,7 +35,7 @@ export class MockOpenClawProvider {
         this.state.skills.clear();
         this.state.messages.clear();
     }
-    async startGateway(_config, _dryRun) {
+    async startGateway(_config, _mode, _dryRun) {
         return;
     }
     async createWorkspace(_config, workspace, _dryRun) {

package/dist/openclaw/provider.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection, WorkspaceDef } from "../types.js";
+import type { AgentDef, ChannelDef, ConversationDef, GatewayMode, OpenClawSection, WorkspaceDef } from "../types.js";
 export type ResolvedWorkspaceDef = WorkspaceDef & {
     path: string;
 };
@@ -9,7 +9,7 @@ export interface OpenClawProvider {
     ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean, preserveExistingState: boolean): Promise<EnsureVersionResult>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
-    startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;
+    startGateway(config: OpenClawSection, mode: GatewayMode, dryRun: boolean): Promise<void>;
     createWorkspace(config: OpenClawSection, workspace: ResolvedWorkspaceDef, dryRun: boolean): Promise<void>;
     configureChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void>;
     bindChannelAgent(config: OpenClawSection, channel: ChannelDef, agent: string, dryRun: boolean): Promise<void>;

package/dist/openclaw/remote-provider.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDef, ChannelDef, ConversationDef, OpenClawRemoteConfig, OpenClawSection } from "../types.js";
+import type { AgentDef, ChannelDef, ConversationDef, GatewayMode, OpenClawRemoteConfig, OpenClawSection } from "../types.js";
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class RemoteOpenClawProvider implements OpenClawProvider {
     private readonly stagedMessages;
@@ -8,7 +8,7 @@ export declare class RemoteOpenClawProvider implements OpenClawProvider {
     ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean, _preserveExistingState: boolean): Promise<EnsureVersionResult>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
-    startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;
+    startGateway(config: OpenClawSection, mode: GatewayMode, dryRun: boolean): Promise<void>;
     createWorkspace(config: OpenClawSection, workspace: ResolvedWorkspaceDef, dryRun: boolean): Promise<void>;
     configureChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void>;
     bindChannelAgent(config: OpenClawSection, channel: ChannelDef, agent: string, dryRun: boolean): Promise<void>;

package/dist/openclaw/remote-provider.js

@@ -110,8 +110,11 @@ export class RemoteOpenClawProvider {
     async factoryReset(config, dryRun) {
         await this.perform(config, "factory_reset", undefined, dryRun);
     }
-    async startGateway(config, dryRun) {
-        await this.perform(config, "start_gateway", undefined, dryRun);
+    async startGateway(config, mode, dryRun) {
+        if (mode === "none") {
+            return;
+        }
+        await this.perform(config, "start_gateway", { mode }, dryRun);
     }
     async createWorkspace(config, workspace, dryRun) {
         await this.perform(config, "create_workspace", { workspace }, dryRun);

package/dist/orchestrator.js

@@ -55,6 +55,18 @@ function resolveWorkspacePath(recipeOrigin, name, configuredPath) {
     const workspaceName = trimmedName.startsWith("workspace-") ? trimmedName : `workspace-${trimmedName}`;
     return path.join(homedir(), ".openclaw", workspaceName);
 }
+function resolveOpenClawRootPath(recipeOrigin, configuredPath) {
+    if (configuredPath?.trim()) {
+        if (path.isAbsolute(configuredPath)) {
+            return configuredPath;
+        }
+        if (recipeOrigin.kind === "local") {
+            return path.resolve(recipeOrigin.recipeDir, configuredPath);
+        }
+        return path.resolve(configuredPath);
+    }
+    return path.join(homedir(), ".openclaw");
+}
 function isHttpUrl(value) {
     try {
         const url = new URL(value);
@@ -164,6 +176,72 @@ export async function runRecipe(recipe, recipeOrigin, options, logger) {
         await provider.installPlugin(recipe.openclaw, pluginSpec, options.dryRun);
         logger.info(`Plugin preinstalled: ${pluginSpec}`);
     }
+    const root = recipe.openclaw.root;
+    if (root && (root.assets?.trim() || (root.files?.length ?? 0) > 0)) {
+        if (remoteMode) {
+            throw new ClawChefError("openclaw.root assets/files are not supported with --provider remote");
+        }
+        const openclawRootPath = resolveOpenClawRootPath(recipeOrigin, root.path);
+        if (!options.dryRun) {
+            await mkdir(openclawRootPath, { recursive: true });
+        }
+        if (root.assets?.trim()) {
+            const resolvedAssets = resolveFileRef(recipeOrigin, root.assets);
+            if (resolvedAssets.kind !== "local") {
+                throw new ClawChefError(`openclaw.root.assets must resolve to a local directory: ${root.assets}. Direct URL recipes cannot use openclaw.root.assets.`);
+            }
+            let assetDirStat;
+            try {
+                assetDirStat = await stat(resolvedAssets.value);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new ClawChefError(`openclaw.root.assets path is not accessible: ${resolvedAssets.value} (${message})`);
+            }
+            if (!assetDirStat.isDirectory()) {
+                throw new ClawChefError(`openclaw.root.assets must be a directory: ${resolvedAssets.value}`);
+            }
+            const assetFiles = await collectLocalAssetFiles(resolvedAssets.value);
+            for (const assetFile of assetFiles) {
+                const target = path.resolve(openclawRootPath, assetFile.relativePath);
+                if (!options.dryRun) {
+                    await mkdir(path.dirname(target), { recursive: true });
+                    await copyFile(assetFile.absolutePath, target);
+                }
+                logger.info(`OpenClaw root asset copied: ${assetFile.relativePath}`);
+            }
+        }
+        for (const file of root.files ?? []) {
+            const target = path.resolve(openclawRootPath, file.path);
+            const targetDir = path.dirname(target);
+            if (!options.dryRun) {
+                await mkdir(targetDir, { recursive: true });
+                const alreadyExists = await exists(target);
+                if (alreadyExists && file.overwrite === false) {
+                    logger.warn(`Skipping existing file: ${target}`);
+                }
+                else if (file.content !== undefined) {
+                    await writeFile(target, file.content, "utf8");
+                }
+                else if (file.content_from) {
+                    const rawContent = await readTextFromRef(recipeOrigin, file.content_from);
+                    const content = renderTemplateString(rawContent, options.vars, options.allowMissing);
+                    await writeFile(target, content, "utf8");
+                }
+                else if (file.source) {
+                    const resolved = resolveFileRef(recipeOrigin, file.source);
+                    if (resolved.kind === "local") {
+                        await copyFile(resolved.value, target);
+                    }
+                    else {
+                        const content = await readBinaryFromRef(recipeOrigin, file.source);
+                        await writeFile(target, content);
+                    }
+                }
+            }
+            logger.info(`OpenClaw root file materialized: ${file.path}`);
+        }
+    }
     for (const ws of recipe.workspaces ?? []) {
         const absPath = resolveWorkspacePath(recipeOrigin, ws.name, ws.path);
         workspacePaths.set(ws.name, absPath);
@@ -323,8 +401,13 @@ export async function runRecipe(recipe, recipeOrigin, options, logger) {
         }
         logger.info(`Preset messages sent: ${conv.workspace}/${conv.agent}`);
     }
-    await provider.startGateway(recipe.openclaw, options.dryRun);
-    logger.info("Gateway started");
+    await provider.startGateway(recipe.openclaw, options.gatewayMode, options.dryRun);
+    if (options.gatewayMode === "none") {
+        logger.info("Gateway start skipped by gateway mode: none");
+    }
+    else {
+        logger.info(`Gateway started (${options.gatewayMode})`);
+    }
     for (const channel of recipe.channels ?? []) {
         const effectiveChannel = channel.agent?.trim() && !channel.account?.trim()
             ? { ...channel, account: channel.agent.trim() }

package/dist/recipe.js

@@ -146,6 +146,18 @@ function filterRecipeByWorkspaceName(recipe, workspaceName) {
 function semanticValidate(recipe) {
     const ws = new Set((recipe.workspaces ?? []).map((w) => w.name));
     const agentNameCounts = new Map();
+    const root = recipe.openclaw.root;
+    if (root?.path !== undefined && !root.path.trim()) {
+        throw new ClawChefError("openclaw.root.path cannot be empty");
+    }
+    if (root?.assets !== undefined && !root.assets.trim()) {
+        throw new ClawChefError("openclaw.root.assets cannot be empty");
+    }
+    for (const file of root?.files ?? []) {
+        if (!file.path.trim()) {
+            throw new ClawChefError("openclaw.root.files[] has file with empty path");
+        }
+    }
     for (const workspace of recipe.workspaces ?? []) {
         if (workspace.assets !== undefined && !workspace.assets.trim()) {
             throw new ClawChefError(`Workspace ${workspace.name} has empty assets path`);

package/dist/schema.d.ts

@@ -20,6 +20,61 @@ export declare const recipeSchema: z.ZodObject<{
         version: z.ZodString;
         install: z.ZodOptional<z.ZodEnum<["auto", "always", "never"]>>;
         plugins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        root: z.ZodOptional<z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            assets: z.ZodOptional<z.ZodString>;
+            files: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+                path: z.ZodString;
+                content: z.ZodOptional<z.ZodString>;
+                content_from: z.ZodOptional<z.ZodString>;
+                source: z.ZodOptional<z.ZodString>;
+                overwrite: z.ZodOptional<z.ZodBoolean>;
+            }, "strict", z.ZodTypeAny, {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }, {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }>, {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }, {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }>, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            path?: string | undefined;
+            files?: {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }[] | undefined;
+            assets?: string | undefined;
+        }, {
+            path?: string | undefined;
+            files?: {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }[] | undefined;
+            assets?: string | undefined;
+        }>>;
         bootstrap: z.ZodOptional<z.ZodObject<{
             non_interactive: z.ZodOptional<z.ZodBoolean>;
             accept_risk: z.ZodOptional<z.ZodBoolean>;
@@ -48,9 +103,9 @@ export declare const recipeSchema: z.ZodObject<{
             token_provider?: string | undefined;
             token_profile_id?: string | undefined;
             llm_api_key?: string | undefined;
+            mode?: "remote" | "local" | undefined;
             non_interactive?: boolean | undefined;
             accept_risk?: boolean | undefined;
-            mode?: "remote" | "local" | undefined;
             flow?: "quickstart" | "advanced" | "manual" | undefined;
             auth_choice?: string | undefined;
             reset?: boolean | undefined;
@@ -68,9 +123,9 @@ export declare const recipeSchema: z.ZodObject<{
             token_provider?: string | undefined;
             token_profile_id?: string | undefined;
             llm_api_key?: string | undefined;
+            mode?: "remote" | "local" | undefined;
             non_interactive?: boolean | undefined;
             accept_risk?: boolean | undefined;
-            mode?: "remote" | "local" | undefined;
             flow?: "quickstart" | "advanced" | "manual" | undefined;
             auth_choice?: string | undefined;
             reset?: boolean | undefined;
@@ -88,6 +143,7 @@ export declare const recipeSchema: z.ZodObject<{
             install_plugin: z.ZodOptional<z.ZodString>;
             factory_reset: z.ZodOptional<z.ZodString>;
             start_gateway: z.ZodOptional<z.ZodString>;
+            run_gateway: z.ZodOptional<z.ZodString>;
             enable_plugin: z.ZodOptional<z.ZodString>;
             bind_channel_agent: z.ZodOptional<z.ZodString>;
             login_channel: z.ZodOptional<z.ZodString>;
@@ -103,6 +159,7 @@ export declare const recipeSchema: z.ZodObject<{
             install_plugin?: string | undefined;
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
+            run_gateway?: string | undefined;
             enable_plugin?: string | undefined;
             bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
@@ -118,6 +175,7 @@ export declare const recipeSchema: z.ZodObject<{
             install_plugin?: string | undefined;
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
+            run_gateway?: string | undefined;
             enable_plugin?: string | undefined;
             bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
@@ -132,6 +190,17 @@ export declare const recipeSchema: z.ZodObject<{
         bin?: string | undefined;
         install?: "auto" | "always" | "never" | undefined;
         plugins?: string[] | undefined;
+        root?: {
+            path?: string | undefined;
+            files?: {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }[] | undefined;
+            assets?: string | undefined;
+        } | undefined;
         bootstrap?: {
             workspace?: string | undefined;
             cloudflare_ai_gateway_account_id?: string | undefined;
@@ -140,9 +209,9 @@ export declare const recipeSchema: z.ZodObject<{
             token_provider?: string | undefined;
             token_profile_id?: string | undefined;
             llm_api_key?: string | undefined;
+            mode?: "remote" | "local" | undefined;
             non_interactive?: boolean | undefined;
             accept_risk?: boolean | undefined;
-            mode?: "remote" | "local" | undefined;
             flow?: "quickstart" | "advanced" | "manual" | undefined;
             auth_choice?: string | undefined;
             reset?: boolean | undefined;
@@ -160,6 +229,7 @@ export declare const recipeSchema: z.ZodObject<{
             install_plugin?: string | undefined;
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
+            run_gateway?: string | undefined;
             enable_plugin?: string | undefined;
             bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
@@ -174,6 +244,17 @@ export declare const recipeSchema: z.ZodObject<{
         bin?: string | undefined;
         install?: "auto" | "always" | "never" | undefined;
         plugins?: string[] | undefined;
+        root?: {
+            path?: string | undefined;
+            files?: {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }[] | undefined;
+            assets?: string | undefined;
+        } | undefined;
         bootstrap?: {
             workspace?: string | undefined;
             cloudflare_ai_gateway_account_id?: string | undefined;
@@ -182,9 +263,9 @@ export declare const recipeSchema: z.ZodObject<{
             token_provider?: string | undefined;
             token_profile_id?: string | undefined;
             llm_api_key?: string | undefined;
+            mode?: "remote" | "local" | undefined;
             non_interactive?: boolean | undefined;
             accept_risk?: boolean | undefined;
-            mode?: "remote" | "local" | undefined;
             flow?: "quickstart" | "advanced" | "manual" | undefined;
             auth_choice?: string | undefined;
             reset?: boolean | undefined;
@@ -202,6 +283,7 @@ export declare const recipeSchema: z.ZodObject<{
             install_plugin?: string | undefined;
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
+            run_gateway?: string | undefined;
             enable_plugin?: string | undefined;
             bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
@@ -416,6 +498,17 @@ export declare const recipeSchema: z.ZodObject<{
         bin?: string | undefined;
         install?: "auto" | "always" | "never" | undefined;
         plugins?: string[] | undefined;
+        root?: {
+            path?: string | undefined;
+            files?: {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }[] | undefined;
+            assets?: string | undefined;
+        } | undefined;
         bootstrap?: {
             workspace?: string | undefined;
             cloudflare_ai_gateway_account_id?: string | undefined;
@@ -424,9 +517,9 @@ export declare const recipeSchema: z.ZodObject<{
             token_provider?: string | undefined;
             token_profile_id?: string | undefined;
             llm_api_key?: string | undefined;
+            mode?: "remote" | "local" | undefined;
             non_interactive?: boolean | undefined;
             accept_risk?: boolean | undefined;
-            mode?: "remote" | "local" | undefined;
             flow?: "quickstart" | "advanced" | "manual" | undefined;
             auth_choice?: string | undefined;
             reset?: boolean | undefined;
@@ -444,6 +537,7 @@ export declare const recipeSchema: z.ZodObject<{
             install_plugin?: string | undefined;
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
+            run_gateway?: string | undefined;
             enable_plugin?: string | undefined;
             bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
@@ -519,6 +613,17 @@ export declare const recipeSchema: z.ZodObject<{
         bin?: string | undefined;
         install?: "auto" | "always" | "never" | undefined;
         plugins?: string[] | undefined;
+        root?: {
+            path?: string | undefined;
+            files?: {
+                path: string;
+                content?: string | undefined;
+                overwrite?: boolean | undefined;
+                content_from?: string | undefined;
+                source?: string | undefined;
+            }[] | undefined;
+            assets?: string | undefined;
+        } | undefined;
         bootstrap?: {
             workspace?: string | undefined;
             cloudflare_ai_gateway_account_id?: string | undefined;
@@ -527,9 +632,9 @@ export declare const recipeSchema: z.ZodObject<{
             token_provider?: string | undefined;
             token_profile_id?: string | undefined;
             llm_api_key?: string | undefined;
+            mode?: "remote" | "local" | undefined;
             non_interactive?: boolean | undefined;
             accept_risk?: boolean | undefined;
-            mode?: "remote" | "local" | undefined;
             flow?: "quickstart" | "advanced" | "manual" | undefined;
             auth_choice?: string | undefined;
             reset?: boolean | undefined;
@@ -547,6 +652,7 @@ export declare const recipeSchema: z.ZodObject<{
             install_plugin?: string | undefined;
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
+            run_gateway?: string | undefined;
             enable_plugin?: string | undefined;
             bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;

package/dist/schema.js

@@ -12,6 +12,7 @@ const openClawCommandsSchema = z
     install_plugin: z.string().optional(),
     factory_reset: z.string().optional(),
     start_gateway: z.string().optional(),
+    run_gateway: z.string().optional(),
     enable_plugin: z.string().optional(),
     bind_channel_agent: z.string().optional(),
     login_channel: z.string().optional(),
@@ -45,12 +46,32 @@ const openClawBootstrapSchema = z
     token_profile_id: z.string().optional(),
 })
     .strict();
+const rootFileSchema = z
+    .object({
+    path: z.string().min(1),
+    content: z.string().optional(),
+    content_from: z.string().min(1).optional(),
+    source: z.string().optional(),
+    overwrite: z.boolean().optional(),
+})
+    .strict()
+    .refine((v) => [v.content, v.content_from, v.source].filter((item) => item !== undefined).length === 1, {
+    message: "openclaw.root.files[] requires exactly one of content, content_from, or source",
+});
+const openClawRootSchema = z
+    .object({
+    path: z.string().min(1).optional(),
+    assets: z.string().min(1).optional(),
+    files: z.array(rootFileSchema).optional(),
+})
+    .strict();
 const openClawSchema = z
     .object({
     bin: z.string().optional(),
     version: z.string(),
     install: z.enum(["auto", "always", "never"]).optional(),
     plugins: z.array(z.string().min(1)).optional(),
+    root: openClawRootSchema.optional(),
     bootstrap: openClawBootstrapSchema.optional(),
     commands: openClawCommandsSchema.optional(),
 })

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 export type InstallPolicy = "auto" | "always" | "never";
 export type OpenClawProvider = "command" | "mock" | "remote";
 export type RunScope = "full" | "files" | "workspace";
+export type GatewayMode = "service" | "run" | "none";
 export interface OpenClawRemoteConfig {
     base_url: string;
     api_key?: string;
@@ -21,6 +22,7 @@ export interface OpenClawCommandOverrides {
     install_plugin?: string;
     factory_reset?: string;
     start_gateway?: string;
+    run_gateway?: string;
     enable_plugin?: string;
     bind_channel_agent?: string;
     login_channel?: string;
@@ -56,9 +58,15 @@ export interface OpenClawSection {
     version: string;
     install?: InstallPolicy;
     plugins?: string[];
+    root?: OpenClawRootDef;
     bootstrap?: OpenClawBootstrap;
     commands?: OpenClawCommandOverrides;
 }
+export interface OpenClawRootDef {
+    path?: string;
+    assets?: string;
+    files?: WorkspaceFileDef[];
+}
 export interface WorkspaceDef {
     name: string;
     path?: string;
@@ -129,6 +137,7 @@ export interface RunOptions {
     plugins: string[];
     scope: RunScope;
     workspaceName?: string;
+    gatewayMode: GatewayMode;
     dryRun: boolean;
     allowMissing: boolean;
     verbose: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawchef",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Recipe-driven OpenClaw environment orchestrator",
   "homepage": "https://renorzr.github.io/clawchef",
   "repository": {

package/recipes/sample.yaml

@@ -12,6 +12,13 @@ params:
 openclaw:
   version: "${openclaw_version}"
   install: "auto"
+  root:
+    files:
+      - path: "AGENTS.md"
+        overwrite: true
+        content: |
+          # OpenClaw Root
+          Project: ${project_name}
 
 workspaces:
   - name: "${project_name}"

package/src/api.ts

@@ -6,7 +6,7 @@ import { runRecipe } from "./orchestrator.js";
 import { loadRecipe, loadRecipeText } from "./recipe.js";
 import { scaffoldProject } from "./scaffold.js";
 import { recipeSchema } from "./schema.js";
-import type { OpenClawProvider, OpenClawRemoteConfig, RunOptions, RunScope } from "./types.js";
+import type { GatewayMode, OpenClawProvider, OpenClawRemoteConfig, RunOptions, RunScope } from "./types.js";
 import type { ScaffoldOptions, ScaffoldResult } from "./scaffold.js";
 
 export interface CookOptions {
@@ -18,6 +18,7 @@ export interface CookOptions {
   silent?: boolean;
   scope?: RunScope;
   workspaceName?: string;
+  gatewayMode?: GatewayMode;
   provider?: OpenClawProvider;
   remote?: Partial<OpenClawRemoteConfig>;
   envFile?: string;
@@ -39,6 +40,7 @@ function normalizeCookOptions(options: CookOptions): RunOptions {
     plugins,
     scope,
     workspaceName,
+    gatewayMode: options.gatewayMode ?? "service",
     dryRun: Boolean(options.dryRun),
     allowMissing: Boolean(options.allowMissing),
     verbose: Boolean(options.verbose),

package/src/cli.ts

@@ -6,7 +6,7 @@ import { runRecipe } from "./orchestrator.js";
 import { loadRecipe, loadRecipeText } from "./recipe.js";
 import { recipeSchema } from "./schema.js";
 import { scaffoldProject } from "./scaffold.js";
-import type { RunOptions, RunScope } from "./types.js";
+import type { GatewayMode, RunOptions, RunScope } from "./types.js";
 import YAML from "js-yaml";
 import path from "node:path";
 import { readFileSync } from "node:fs";
@@ -68,6 +68,13 @@ function parseScope(value: string): RunScope {
   throw new ClawChefError(`Invalid --scope value: ${value}. Expected full, files, or workspace`);
 }
 
+function parseGatewayMode(value: string): GatewayMode {
+  if (value === "service" || value === "run" || value === "none") {
+    return value;
+  }
+  throw new ClawChefError(`Invalid --gateway-mode value: ${value}. Expected service, run, or none`);
+}
+
 function parseOptionalInt(value: string | undefined, fieldName: string): number | undefined {
   if (value === undefined) {
     return undefined;
@@ -112,6 +119,7 @@ export function buildCli(): Command {
     .option("-s, --silent", "Skip reset confirmation prompt", false)
     .option("--scope <scope>", "Run scope: full | files | workspace", "full")
     .option("--workspace <name>", "Workspace name (required when --scope workspace)")
+    .option("--gateway-mode <mode>", "Gateway mode: service | run | none", "service")
     .option("--dotenv-ref <path-or-url>", "Load env vars from local file or HTTP URL")
     .option("--provider <provider>", "Execution provider: command | remote | mock")
     .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p: string[]) => p.concat([v]), [])
@@ -130,6 +138,7 @@ export function buildCli(): Command {
 
       const provider = parseProvider(opts.provider ?? readEnv("CLAWCHEF_PROVIDER") ?? "command");
       const scope = parseScope(String(opts.scope ?? "full"));
+      const gatewayMode = parseGatewayMode(String(opts.gatewayMode ?? "service"));
       const workspaceName = opts.workspace?.trim() ? String(opts.workspace).trim() : undefined;
       if (scope === "workspace" && !workspaceName) {
         throw new ClawChefError("--scope workspace requires --workspace <name>");
@@ -142,6 +151,7 @@ export function buildCli(): Command {
         plugins: parsePluginFlags(opts.plugin),
         scope,
         workspaceName,
+        gatewayMode,
         dryRun: Boolean(opts.dryRun),
         allowMissing: Boolean(opts.allowMissing),
         verbose: Boolean(opts.verbose),

package/src/openclaw/command-provider.ts

@@ -6,7 +6,7 @@ import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { ClawChefError } from "../errors.js";
-import type { AgentDef, ChannelDef, ConversationDef, OpenClawBootstrap, OpenClawSection } from "../types.js";
+import type { AgentDef, ChannelDef, ConversationDef, GatewayMode, OpenClawBootstrap, OpenClawSection } from "../types.js";
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 
 const DEFAULT_COMMANDS = {
@@ -16,6 +16,7 @@ const DEFAULT_COMMANDS = {
   install_plugin: "${bin} plugins install ${plugin_spec_q}",
   factory_reset: "${bin} reset --scope full --yes --non-interactive",
   start_gateway: "${bin} gateway start",
+  run_gateway: "${bin} gateway run",
   enable_plugin: "",
   bind_channel_agent: "",
   login_channel: "${bin} channels login --channel ${channel_q}${account_arg}",
@@ -464,9 +465,14 @@ export class CommandOpenClawProvider implements OpenClawProvider {
     await runShell(cmd, dryRun);
   }
 
-  async startGateway(config: OpenClawSection, dryRun: boolean): Promise<void> {
+  async startGateway(config: OpenClawSection, mode: GatewayMode, dryRun: boolean): Promise<void> {
+    if (mode === "none") {
+      return;
+    }
+
     const bin = config.bin ?? "openclaw";
-    const startCmd = commandFor(config, "start_gateway", { bin, version: config.version });
+    const key = mode === "run" ? "run_gateway" : "start_gateway";
+    const startCmd = commandFor(config, key, { bin, version: config.version });
     if (!startCmd.trim()) {
       return;
     }

package/src/openclaw/mock-provider.ts

@@ -1,4 +1,4 @@
-import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../types.js";
+import type { AgentDef, ChannelDef, ConversationDef, GatewayMode, OpenClawSection } from "../types.js";
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 
 interface MockState {
@@ -57,7 +57,7 @@ export class MockOpenClawProvider implements OpenClawProvider {
     this.state.messages.clear();
   }
 
-  async startGateway(_config: OpenClawSection, _dryRun: boolean): Promise<void> {
+  async startGateway(_config: OpenClawSection, _mode: GatewayMode, _dryRun: boolean): Promise<void> {
     return;
   }
 

package/src/openclaw/provider.ts

@@ -1,4 +1,4 @@
-import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection, WorkspaceDef } from "../types.js";
+import type { AgentDef, ChannelDef, ConversationDef, GatewayMode, OpenClawSection, WorkspaceDef } from "../types.js";
 
 export type ResolvedWorkspaceDef = WorkspaceDef & { path: string };
 
@@ -15,7 +15,7 @@ export interface OpenClawProvider {
   ): Promise<EnsureVersionResult>;
   installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
   factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
-  startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;
+  startGateway(config: OpenClawSection, mode: GatewayMode, dryRun: boolean): Promise<void>;
   createWorkspace(config: OpenClawSection, workspace: ResolvedWorkspaceDef, dryRun: boolean): Promise<void>;
   configureChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void>;
   bindChannelAgent(config: OpenClawSection, channel: ChannelDef, agent: string, dryRun: boolean): Promise<void>;

package/src/openclaw/remote-provider.ts

@@ -3,6 +3,7 @@ import type {
   AgentDef,
   ChannelDef,
   ConversationDef,
+  GatewayMode,
   OpenClawRemoteConfig,
   OpenClawSection,
 } from "../types.js";
@@ -176,8 +177,11 @@ export class RemoteOpenClawProvider implements OpenClawProvider {
     await this.perform(config, "factory_reset", undefined, dryRun);
   }
 
-  async startGateway(config: OpenClawSection, dryRun: boolean): Promise<void> {
-    await this.perform(config, "start_gateway", undefined, dryRun);
+  async startGateway(config: OpenClawSection, mode: GatewayMode, dryRun: boolean): Promise<void> {
+    if (mode === "none") {
+      return;
+    }
+    await this.perform(config, "start_gateway", { mode }, dryRun);
   }
 
   async createWorkspace(config: OpenClawSection, workspace: ResolvedWorkspaceDef, dryRun: boolean): Promise<void> {

package/src/orchestrator.ts

@@ -62,6 +62,19 @@ function resolveWorkspacePath(recipeOrigin: RecipeOrigin, name: string, configur
   return path.join(homedir(), ".openclaw", workspaceName);
 }
 
+function resolveOpenClawRootPath(recipeOrigin: RecipeOrigin, configuredPath?: string): string {
+  if (configuredPath?.trim()) {
+    if (path.isAbsolute(configuredPath)) {
+      return configuredPath;
+    }
+    if (recipeOrigin.kind === "local") {
+      return path.resolve(recipeOrigin.recipeDir, configuredPath);
+    }
+    return path.resolve(configuredPath);
+  }
+  return path.join(homedir(), ".openclaw");
+}
+
 function isHttpUrl(value: string): boolean {
   try {
     const url = new URL(value);
@@ -197,6 +210,76 @@ export async function runRecipe(
     logger.info(`Plugin preinstalled: ${pluginSpec}`);
   }
 
+  const root = recipe.openclaw.root;
+  if (root && (root.assets?.trim() || (root.files?.length ?? 0) > 0)) {
+    if (remoteMode) {
+      throw new ClawChefError("openclaw.root assets/files are not supported with --provider remote");
+    }
+
+    const openclawRootPath = resolveOpenClawRootPath(recipeOrigin, root.path);
+    if (!options.dryRun) {
+      await mkdir(openclawRootPath, { recursive: true });
+    }
+
+    if (root.assets?.trim()) {
+      const resolvedAssets = resolveFileRef(recipeOrigin, root.assets);
+      if (resolvedAssets.kind !== "local") {
+        throw new ClawChefError(
+          `openclaw.root.assets must resolve to a local directory: ${root.assets}. Direct URL recipes cannot use openclaw.root.assets.`,
+        );
+      }
+
+      let assetDirStat;
+      try {
+        assetDirStat = await stat(resolvedAssets.value);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ClawChefError(`openclaw.root.assets path is not accessible: ${resolvedAssets.value} (${message})`);
+      }
+      if (!assetDirStat.isDirectory()) {
+        throw new ClawChefError(`openclaw.root.assets must be a directory: ${resolvedAssets.value}`);
+      }
+
+      const assetFiles = await collectLocalAssetFiles(resolvedAssets.value);
+      for (const assetFile of assetFiles) {
+        const target = path.resolve(openclawRootPath, assetFile.relativePath);
+        if (!options.dryRun) {
+          await mkdir(path.dirname(target), { recursive: true });
+          await copyFile(assetFile.absolutePath, target);
+        }
+        logger.info(`OpenClaw root asset copied: ${assetFile.relativePath}`);
+      }
+    }
+
+    for (const file of root.files ?? []) {
+      const target = path.resolve(openclawRootPath, file.path);
+      const targetDir = path.dirname(target);
+
+      if (!options.dryRun) {
+        await mkdir(targetDir, { recursive: true });
+        const alreadyExists = await exists(target);
+        if (alreadyExists && file.overwrite === false) {
+          logger.warn(`Skipping existing file: ${target}`);
+        } else if (file.content !== undefined) {
+          await writeFile(target, file.content, "utf8");
+        } else if (file.content_from) {
+          const rawContent = await readTextFromRef(recipeOrigin, file.content_from);
+          const content = renderTemplateString(rawContent, options.vars, options.allowMissing);
+          await writeFile(target, content, "utf8");
+        } else if (file.source) {
+          const resolved = resolveFileRef(recipeOrigin, file.source);
+          if (resolved.kind === "local") {
+            await copyFile(resolved.value, target);
+          } else {
+            const content = await readBinaryFromRef(recipeOrigin, file.source);
+            await writeFile(target, content);
+          }
+        }
+      }
+      logger.info(`OpenClaw root file materialized: ${file.path}`);
+    }
+  }
+
   for (const ws of recipe.workspaces ?? []) {
     const absPath = resolveWorkspacePath(recipeOrigin, ws.name, ws.path);
     workspacePaths.set(ws.name, absPath);
@@ -375,8 +458,12 @@ export async function runRecipe(
     logger.info(`Preset messages sent: ${conv.workspace}/${conv.agent}`);
   }
 
-  await provider.startGateway(recipe.openclaw, options.dryRun);
-  logger.info("Gateway started");
+  await provider.startGateway(recipe.openclaw, options.gatewayMode, options.dryRun);
+  if (options.gatewayMode === "none") {
+    logger.info("Gateway start skipped by gateway mode: none");
+  } else {
+    logger.info(`Gateway started (${options.gatewayMode})`);
+  }
 
   for (const channel of recipe.channels ?? []) {
     const effectiveChannel = channel.agent?.trim() && !channel.account?.trim()

package/src/recipe.ts

@@ -194,6 +194,18 @@ function filterRecipeByWorkspaceName(recipe: Recipe, workspaceName: string): Rec
 function semanticValidate(recipe: Recipe): void {
   const ws = new Set((recipe.workspaces ?? []).map((w) => w.name));
   const agentNameCounts = new Map<string, number>();
+  const root = recipe.openclaw.root;
+  if (root?.path !== undefined && !root.path.trim()) {
+    throw new ClawChefError("openclaw.root.path cannot be empty");
+  }
+  if (root?.assets !== undefined && !root.assets.trim()) {
+    throw new ClawChefError("openclaw.root.assets cannot be empty");
+  }
+  for (const file of root?.files ?? []) {
+    if (!file.path.trim()) {
+      throw new ClawChefError("openclaw.root.files[] has file with empty path");
+    }
+  }
   for (const workspace of recipe.workspaces ?? []) {
     if (workspace.assets !== undefined && !workspace.assets.trim()) {
       throw new ClawChefError(`Workspace ${workspace.name} has empty assets path`);

package/src/schema.ts

@@ -14,6 +14,7 @@ const openClawCommandsSchema = z
     install_plugin: z.string().optional(),
     factory_reset: z.string().optional(),
     start_gateway: z.string().optional(),
+    run_gateway: z.string().optional(),
     enable_plugin: z.string().optional(),
     bind_channel_agent: z.string().optional(),
     login_channel: z.string().optional(),
@@ -49,12 +50,34 @@ const openClawBootstrapSchema = z
   })
   .strict();
 
+const rootFileSchema = z
+  .object({
+    path: z.string().min(1),
+    content: z.string().optional(),
+    content_from: z.string().min(1).optional(),
+    source: z.string().optional(),
+    overwrite: z.boolean().optional(),
+  })
+  .strict()
+  .refine((v) => [v.content, v.content_from, v.source].filter((item) => item !== undefined).length === 1, {
+    message: "openclaw.root.files[] requires exactly one of content, content_from, or source",
+  });
+
+const openClawRootSchema = z
+  .object({
+    path: z.string().min(1).optional(),
+    assets: z.string().min(1).optional(),
+    files: z.array(rootFileSchema).optional(),
+  })
+  .strict();
+
 const openClawSchema = z
   .object({
     bin: z.string().optional(),
     version: z.string(),
     install: z.enum(["auto", "always", "never"]).optional(),
     plugins: z.array(z.string().min(1)).optional(),
+    root: openClawRootSchema.optional(),
     bootstrap: openClawBootstrapSchema.optional(),
     commands: openClawCommandsSchema.optional(),
   })

package/src/types.ts

@@ -1,6 +1,7 @@
 export type InstallPolicy = "auto" | "always" | "never";
 export type OpenClawProvider = "command" | "mock" | "remote";
 export type RunScope = "full" | "files" | "workspace";
+export type GatewayMode = "service" | "run" | "none";
 
 export interface OpenClawRemoteConfig {
   base_url: string;
@@ -24,6 +25,7 @@ export interface OpenClawCommandOverrides {
   install_plugin?: string;
   factory_reset?: string;
   start_gateway?: string;
+  run_gateway?: string;
   enable_plugin?: string;
   bind_channel_agent?: string;
   login_channel?: string;
@@ -61,10 +63,17 @@ export interface OpenClawSection {
   version: string;
   install?: InstallPolicy;
   plugins?: string[];
+  root?: OpenClawRootDef;
   bootstrap?: OpenClawBootstrap;
   commands?: OpenClawCommandOverrides;
 }
 
+export interface OpenClawRootDef {
+  path?: string;
+  assets?: string;
+  files?: WorkspaceFileDef[];
+}
+
 export interface WorkspaceDef {
   name: string;
   path?: string;
@@ -143,6 +152,7 @@ export interface RunOptions {
   plugins: string[];
   scope: RunScope;
   workspaceName?: string;
+  gatewayMode: GatewayMode;
   dryRun: boolean;
   allowMissing: boolean;
   verbose: boolean;