clawchef 0.1.6 → 0.1.8

package/AGENTS.md

@@ -0,0 +1,159 @@
+# AGENTS Guide for `clawchef`
+
+This file is for coding agents operating in this repository.
+It documents the current build/test workflow and code conventions inferred from the codebase.
+
+## Scope and Source of Truth
+
+- Primary language: TypeScript (ESM, NodeNext).
+- Runtime target: Node.js `>=20`.
+- Package manager: npm (`package-lock.json` is present).
+- Compiler config: `tsconfig.json` with `strict: true` and `rootDir: src`, `outDir: dist`.
+- Public entry points: CLI (`src/index.ts`) and Node API (`src/api.ts`).
+
+## Repository Rules Discovery
+
+I checked for additional agent instruction files:
+
+- `.cursor/rules/`: not present
+- `.cursorrules`: not present
+- `.github/copilot-instructions.md`: not present
+
+So this `AGENTS.md` is the repo-local guidance file for agents.
+
+## Build, Lint, and Test Commands
+
+## Install
+
+- `npm install`
+
+## Build
+
+- `npm run build`
+  - Runs `tsc -p tsconfig.json`
+  - Emits JS + declarations into `dist/`
+
+## Type Check
+
+- `npm run typecheck`
+  - Runs `tsc --noEmit -p tsconfig.json`
+  - Use this as the closest thing to linting gate today
+
+## Lint
+
+- There is currently **no configured lint script** (`npm run lint` does not exist).
+- Do not assume ESLint/Prettier are configured.
+- Keep formatting and style aligned with existing files.
+
+## Tests
+
+- There is currently **no test script** in this repository’s `package.json`.
+- There is no committed `test/` directory in this repo at the moment.
+- For now, validation is typically: build + typecheck + targeted manual CLI/API smoke checks.
+
+## Running a single test (when test files exist)
+
+If you add Node test files (for example `*.test.mjs`), run one test file directly with:
+
+- `node --test path/to/file.test.mjs`
+
+Example:
+
+- `node --test test/recipe-smoke.test.mjs`
+
+Notes:
+
+- Scaffolded recipe projects generated by `clawchef scaffold` include `test/recipe-smoke.test.mjs`.
+- Those scaffolded projects also include `npm run test:recipe` and `npm test`, but this repo currently does not.
+
+## Coding Style Guidelines
+
+These conventions are based on current source in `src/`.
+
+## Formatting and syntax
+
+- Use 2-space indentation.
+- Use semicolons.
+- Use double quotes for strings.
+- Prefer trailing commas in multiline literals/calls.
+- Keep functions focused and relatively small unless complexity requires expansion.
+
+## Module system and imports
+
+- Use ESM imports/exports only.
+- For local imports, include `.js` extension in import specifiers (important for NodeNext output).
+- Use `import type` for type-only imports.
+- Prefer Node built-ins via `node:` prefix.
+- Import ordering is not rigidly enforced; keep it consistent within each edited file.
+
+## Types and strictness
+
+- Preserve strict TypeScript compatibility (`strict: true`).
+- Avoid `any`; use `unknown` when needed and narrow safely.
+- Prefer explicit interfaces/types for structured data (see `src/types.ts`).
+- Prefer narrow unions for finite modes/options (`RunScope`, provider names, etc.).
+- Keep runtime validation in sync with static types.
+  - If a recipe shape changes, update both `src/types.ts` and `src/schema.ts`.
+
+## Naming conventions
+
+- `camelCase` for variables/functions.
+- `PascalCase` for classes, interfaces, and type aliases intended as entities.
+- `UPPER_SNAKE_CASE` for top-level constants with fixed meaning.
+- Keep naming domain-oriented (`workspace`, `channel`, `agent`, `bootstrap`, `scope`).
+
+## Error handling conventions
+
+- Throw `ClawChefError` for expected/user-facing failures.
+- Include actionable, specific messages.
+- For caught unknown errors, convert to readable message:
+  - `err instanceof Error ? err.message : String(err)`
+- At CLI top-level, only `ClawChefError` should map to normal error output; unknown errors become fatal.
+
+## Logging and output
+
+- Use `Logger` (`info`, `warn`, `debug`) for orchestration flow messages.
+- `debug` logs should remain behind `--verbose`.
+- Keep logs concise and operationally useful.
+- Use `process.stdout.write` / `process.stderr.write` for CLI I/O (consistent with existing code).
+
+## Async and filesystem patterns
+
+- Use async/await with `node:fs/promises` APIs.
+- Prefer non-blocking I/O, except tiny startup reads where sync is already established (`readPackageVersion`).
+- Wrap external command execution and network operations with clear errors.
+- Preserve cleanup behavior for temp dirs/files via `try/finally`.
+
+## Recipe/schema evolution rules
+
+- Schema is strict (`zod` `.strict()` used heavily); unknown keys are rejected.
+- Enforce semantic constraints in `semanticValidate` (`src/recipe.ts`) after schema parse.
+- Keep secret-handling guardrails intact:
+  - Inline secrets should be rejected where required.
+  - Template placeholders (`${var}`) are expected for secrets.
+
+## CLI/API change guidelines
+
+- Keep CLI flags in `src/cli.ts` aligned with Node API options in `src/api.ts` when feature parity is intended.
+- Validate mutually dependent options early (for example, scope + workspace pairing).
+- Maintain provider parity (`command`, `remote`, `mock`) when adding operations.
+- If provider interface changes, update all provider implementations and factory wiring.
+
+## Suggested pre-commit checklist for agents
+
+- `npm run typecheck`
+- `npm run build`
+- If tests were added: run relevant Node tests, at least one targeted file
+- Verify README snippets if CLI flags/behavior changed
+- Confirm `src/types.ts` and `src/schema.ts` remain synchronized
+
+## Quick architecture map
+
+- `src/cli.ts`: command parsing + CLI runtime wiring
+- `src/api.ts`: Node API (`cook`, `validate`, `scaffold`)
+- `src/recipe.ts`: recipe loading, template resolution, semantic validation
+- `src/orchestrator.ts`: execution flow across workspaces/agents/channels/files
+- `src/openclaw/*.ts`: provider abstraction and implementations
+- `src/schema.ts` + `src/types.ts`: validation schema and TS domain model
+
+When in doubt, follow existing patterns in adjacent files and keep changes minimal, explicit, and type-safe.

package/README.md

@@ -12,7 +12,8 @@ Recipe-driven OpenClaw environment orchestrator.
 - Requires secrets to be injected via `--var` / `CLAWCHEF_VAR_*` (no inline secrets in recipe).
 - Prepares OpenClaw version (install or reuse).
 - When installed OpenClaw version mismatches recipe version, prompts: ignore / abort / force reinstall (silent mode auto-picks force reinstall).
-- Always runs factory reset first (with confirmation prompt unless `-s/--silent` is used).
+- 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.
 - Creates workspaces and agents (default workspace path: `~/.openclaw/workspace-<workspace-name>`).
@@ -20,7 +21,6 @@ Recipe-driven OpenClaw environment orchestrator.
 - Materializes files into target workspaces.
 - Installs skills.
 - Supports plugin preinstall via `openclaw.plugins[]` and runtime `--plugin` flags.
-- Supports preserving existing OpenClaw state via `--keep-openclaw-state` (skip factory reset).
 - Configures channels with `openclaw channels add`.
 - Supports interactive channel login at the end of execution (`channels[].login: true`) for channels that expose login.
 - Supports remote HTTP orchestration via runtime flags (`--provider remote`) when OpenClaw is reachable via API.
@@ -96,13 +96,19 @@ Use it only in CI/non-interactive flows where destructive reset behavior is expe
 Keep existing OpenClaw state (skip reset and keep current version on mismatch):
 
 ```bash
-clawchef cook recipes/sample.yaml --keep-openclaw-state
+clawchef cook recipes/sample.yaml --scope files
+```
+
+Update only one workspace:
+
+```bash
+clawchef cook recipes/sample.yaml --scope workspace --workspace workspace-meeting
 ```
 
 From-zero OpenClaw bootstrap (recommended):
 
 ```bash
-CLAWCHEF_VAR_OPENAI_API_KEY=sk-... clawchef cook recipes/openclaw-from-zero.yaml --verbose
+CLAWCHEF_VAR_LLM_API_KEY=sk-... clawchef cook recipes/openclaw-from-zero.yaml --verbose
 ```
 
 Telegram channel setup only:
@@ -183,7 +189,7 @@ await cook("recipes/sample.yaml", {
   provider: "command",
   silent: true,
   vars: {
-    openai_api_key: process.env.OPENAI_API_KEY ?? "",
+    llm_api_key: process.env.OPENAI_API_KEY ?? "",
   },
 });
 
@@ -196,6 +202,8 @@ await scaffold("./my-recipe-project", {
 
 - `vars`: template variables (`Record<string, string>`)
 - `plugins`: plugin npm specs to preinstall for this run (`string[]`)
+- `scope`: `full | files | workspace` (default: `full`)
+- `workspaceName`: required when `scope: "workspace"`
 - `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
@@ -296,7 +304,7 @@ Supported operation values sent by clawchef:
 - `ensure_version`, `factory_reset`, `start_gateway`
 - `install_plugin`
 - `create_workspace`, `create_agent`, `materialize_file`, `install_skill`
-- `configure_channel`, `login_channel`
+- `configure_channel`, `bind_channel_agent`, `login_channel`
 - `run_agent`
 
 For `run_agent`, clawchef expects `output` in response for assertions.
@@ -318,7 +326,7 @@ Supported fields include:
 
 - onboarding: `mode`, `flow`, `non_interactive`, `accept_risk`, `reset`
 - setup toggles: `skip_channels`, `skip_skills`, `skip_health`, `skip_ui`, `skip_daemon`, `install_daemon`
-- auth/provider: `auth_choice`, `openai_api_key`, `anthropic_api_key`, `openrouter_api_key`, `xai_api_key`, `gemini_api_key`, `ai_gateway_api_key`, `cloudflare_ai_gateway_api_key`, `token`, `token_provider`, `token_profile_id`
+- auth/provider: `auth_choice`, `llm_api_key`, `token`, `token_provider`, `token_profile_id`
 
 ### Plugin preinstall
 
@@ -334,7 +342,7 @@ openclaw:
     - "@scope/custom-channel-plugin@1.2.3"
 ```
 
-When `openclaw.bootstrap` contains provider keys, `clawchef` also injects them into runtime env for `openclaw agent --local`.
+When `openclaw.bootstrap` contains `llm_api_key`, clawchef maps it to the provider-specific runtime env by `auth_choice` for `openclaw agent --local`.
 
 For `command` provider, default command templates are:
 
@@ -344,6 +352,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`
+- `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`)
 - `create_agent`: `${bin} agents add ${agent} --workspace ${workspace_path} --model ${model} --non-interactive --json`
@@ -369,6 +378,12 @@ channels:
   - channel: "telegram"
     token: "${telegram_bot_token}"
     account: "default"
+    agent: "main"
+
+  - channel: "telegram"
+    token: "${alerts_bot_token}"
+    account: "alerts"
+    agent: "alerts"
 
   - channel: "slack"
     bot_token: "${slack_bot_token}"
@@ -384,9 +399,12 @@ channels:
 Supported common fields:
 
 - required: `channel`
-- optional: `account`, `name`, `token`, `token_file`, `use_env`, `bot_token`, `access_token`, `app_token`, `webhook_url`, `webhook_path`, `signal_number`, `password`, `login`, `login_mode`, `login_account`
+- optional: `account`, `agent`, `name`, `token`, `token_file`, `use_env`, `bot_token`, `access_token`, `app_token`, `webhook_url`, `webhook_path`, `signal_number`, `password`, `login`, `login_mode`, `login_account`
 - advanced passthrough: `extra_flags` (`snake_case` keys become `--kebab-case` CLI flags)
 
+`channels[].agent` currently supports `channel: "telegram"` only.
+If `agent` is set and `account` is omitted, clawchef defaults `account` to the same value as `agent`.
+
 ## Workspace path behavior
 
 - `workspaces[].path` is optional.
@@ -394,7 +412,7 @@ Supported common fields:
 - `workspaces[].assets` is optional.
 - If `assets` is set, clawchef recursively copies files from that directory into the workspace root.
 - `assets` is resolved relative to the recipe file path (unless absolute path is given).
-- `files[]` runs after assets copy, so `files[]` can override copied asset files.
+- `workspaces[].files[]` runs after assets copy, so explicit file entries can override copied asset files.
 - Direct URL recipes do not support `workspaces[].assets` (assets must resolve to a local directory).
 - If provided, relative paths are resolved from the recipe file directory.
 - For direct URL recipe files, relative workspace paths are resolved from the current working directory.
@@ -410,10 +428,10 @@ workspaces:
 
 ## File content references
 
-In `files[]`, set exactly one of:
+In `workspaces[].files[]`, set exactly one of:
 
 - `content`: inline text in recipe
-- `content_from`: load text from another file/URL
+- `content_from`: load text from another file/URL (loaded content supports `${var}` template rendering)
 - `source`: copy raw file bytes from another file/URL
 
 `content_from` and `source` accept:
@@ -433,8 +451,8 @@ Useful placeholders when overriding commands:
 
 - Do not put plaintext API keys/tokens in recipe files.
 - Use `${var}` placeholders in recipe and pass values via:
-  - `--var openai_api_key=...`
-  - `CLAWCHEF_VAR_OPENAI_API_KEY=...`
+  - `--var llm_api_key=...`
+  - `CLAWCHEF_VAR_LLM_API_KEY=...`
 - Inline secrets in `openclaw.bootstrap.*` are rejected by validation.
 
 ## Conversation message format

package/dist/api.d.ts

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

package/dist/api.js

@@ -8,14 +8,23 @@ import { scaffoldProject } from "./scaffold.js";
 import { recipeSchema } from "./schema.js";
 function normalizeCookOptions(options) {
     const plugins = Array.from(new Set((options.plugins ?? []).map((value) => value.trim()).filter((value) => value.length > 0)));
+    const scope = options.scope ?? "full";
+    const workspaceName = options.workspaceName?.trim() || undefined;
+    if (scope === "workspace" && !workspaceName) {
+        throw new ClawChefError("scope=workspace requires workspaceName");
+    }
+    if (scope !== "workspace" && workspaceName) {
+        throw new ClawChefError("workspaceName is only allowed when scope=workspace");
+    }
     return {
         vars: options.vars ?? {},
         plugins,
+        scope,
+        workspaceName,
         dryRun: Boolean(options.dryRun),
         allowMissing: Boolean(options.allowMissing),
         verbose: Boolean(options.verbose),
         silent: options.silent ?? true,
-        keepOpenClawState: false,
         provider: options.provider ?? "command",
         remote: options.remote ?? {},
     };

package/dist/cli.js

@@ -8,8 +8,23 @@ import { recipeSchema } from "./schema.js";
 import { scaffoldProject } from "./scaffold.js";
 import YAML from "js-yaml";
 import path from "node:path";
+import { readFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+function readPackageVersion() {
+    try {
+        const pkgPath = new URL("../package.json", import.meta.url);
+        const content = readFileSync(pkgPath, "utf8");
+        const parsed = JSON.parse(content);
+        if (parsed.version?.trim()) {
+            return parsed.version;
+        }
+    }
+    catch {
+        // ignore and use fallback
+    }
+    return "0.0.0";
+}
 function parseVarFlags(values) {
     const out = {};
     for (const item of values) {
@@ -40,6 +55,12 @@ function parseProvider(value) {
     }
     throw new ClawChefError(`Invalid --provider value: ${value}. Expected command, remote, or mock`);
 }
+function parseScope(value) {
+    if (value === "full" || value === "files" || value === "workspace") {
+        return value;
+    }
+    throw new ClawChefError(`Invalid --scope value: ${value}. Expected full, files, or workspace`);
+}
 function parseOptionalInt(value, fieldName) {
     if (value === undefined) {
         return undefined;
@@ -69,7 +90,7 @@ export function buildCli() {
     program
         .name("clawchef")
         .description("Run OpenClaw environment recipes")
-        .version("0.1.6");
+        .version(readPackageVersion());
     program
         .command("cook")
         .argument("<recipe>", "Recipe path/URL/dir/archive[:file]")
@@ -78,7 +99,8 @@ export function buildCli() {
         .option("--allow-missing", "Allow unresolved template variables", false)
         .option("--verbose", "Verbose logging", false)
         .option("-s, --silent", "Skip reset confirmation prompt", false)
-        .option("--keep-openclaw-state", "Preserve existing OpenClaw state (skip factory reset)", false)
+        .option("--scope <scope>", "Run scope: full | files | workspace", "full")
+        .option("--workspace <name>", "Workspace name (required when --scope workspace)")
         .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]), [])
@@ -96,14 +118,23 @@ export function buildCli() {
             importDotEnvFromCwd();
         }
         const provider = parseProvider(opts.provider ?? readEnv("CLAWCHEF_PROVIDER") ?? "command");
+        const scope = parseScope(String(opts.scope ?? "full"));
+        const workspaceName = opts.workspace?.trim() ? String(opts.workspace).trim() : undefined;
+        if (scope === "workspace" && !workspaceName) {
+            throw new ClawChefError("--scope workspace requires --workspace <name>");
+        }
+        if (scope !== "workspace" && workspaceName) {
+            throw new ClawChefError("--workspace is only allowed when --scope workspace");
+        }
         const options = {
             vars: parseVarFlags(opts.var),
             plugins: parsePluginFlags(opts.plugin),
+            scope,
+            workspaceName,
             dryRun: Boolean(opts.dryRun),
             allowMissing: Boolean(opts.allowMissing),
             verbose: Boolean(opts.verbose),
             silent: Boolean(opts.silent),
-            keepOpenClawState: Boolean(opts.keepOpenclawState),
             provider,
             remote: {
                 base_url: opts.remoteBaseUrl ?? readEnv("CLAWCHEF_REMOTE_BASE_URL"),

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

@@ -2,12 +2,13 @@ import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class CommandOpenClawProvider implements OpenClawProvider {
     private readonly stagedMessages;
-    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean, keepOpenClawState: boolean): Promise<EnsureVersionResult>;
+    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>;
     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>;
     loginChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void>;
     createAgent(config: OpenClawSection, agent: AgentDef, workspacePath: string, dryRun: boolean): Promise<void>;
     installSkill(config: OpenClawSection, workspace: string, agent: string, skill: string, dryRun: boolean): Promise<void>;

package/dist/openclaw/command-provider.js

@@ -14,6 +14,7 @@ const DEFAULT_COMMANDS = {
     factory_reset: "${bin} reset --scope full --yes --non-interactive",
     start_gateway: "${bin} gateway start",
     enable_plugin: "",
+    bind_channel_agent: "",
     login_channel: "${bin} channels login --channel ${channel_q}${account_arg}",
     create_agent: "${bin} agents add ${agent} --workspace ${workspace_path} --model ${model} --non-interactive --json",
     install_skill: "${bin} skills check",
@@ -21,14 +22,25 @@ const DEFAULT_COMMANDS = {
     run_agent: "${bin} agent --local --agent ${agent} --message ${prompt_q} --json",
 };
 const SECRET_FLAG_RE = /(--[A-Za-z0-9-]*(?:api-key|token|password|secret)[A-Za-z0-9-]*\s+)(?:'[^']*'|"[^"]*"|\S+)/g;
+const AUTH_CHOICE_TO_LLM_FLAG = {
+    "openai-api-key": "--openai-api-key",
+    "anthropic-api-key": "--anthropic-api-key",
+    "openrouter-api-key": "--openrouter-api-key",
+    "xai-api-key": "--xai-api-key",
+    "gemini-api-key": "--gemini-api-key",
+    "ai-gateway-api-key": "--ai-gateway-api-key",
+    "cloudflare-ai-gateway-api-key": "--cloudflare-ai-gateway-api-key",
+};
+const AUTH_CHOICE_TO_LLM_ENV = {
+    "openai-api-key": "OPENAI_API_KEY",
+    "anthropic-api-key": "ANTHROPIC_API_KEY",
+    "openrouter-api-key": "OPENROUTER_API_KEY",
+    "xai-api-key": "XAI_API_KEY",
+    "gemini-api-key": "GEMINI_API_KEY",
+    "ai-gateway-api-key": "AI_GATEWAY_API_KEY",
+    "cloudflare-ai-gateway-api-key": "CLOUDFLARE_AI_GATEWAY_API_KEY",
+};
 const BOOTSTRAP_STRING_FLAGS = [
-    ["openai_api_key", "--openai-api-key"],
-    ["anthropic_api_key", "--anthropic-api-key"],
-    ["openrouter_api_key", "--openrouter-api-key"],
-    ["xai_api_key", "--xai-api-key"],
-    ["gemini_api_key", "--gemini-api-key"],
-    ["ai_gateway_api_key", "--ai-gateway-api-key"],
-    ["cloudflare_ai_gateway_api_key", "--cloudflare-ai-gateway-api-key"],
     ["cloudflare_ai_gateway_account_id", "--cloudflare-ai-gateway-account-id"],
     ["cloudflare_ai_gateway_gateway_id", "--cloudflare-ai-gateway-gateway-id"],
     ["token", "--token"],
@@ -187,6 +199,12 @@ function buildBootstrapCommand(bin, bootstrap, workspacePath) {
     else if (cfg.install_daemon === false) {
         flags.push("--no-install-daemon");
     }
+    if (cfg.llm_api_key?.trim()) {
+        const llmFlag = AUTH_CHOICE_TO_LLM_FLAG[cfg.auth_choice ?? ""];
+        if (llmFlag) {
+            flags.push(`${llmFlag} ${shellQuote(cfg.llm_api_key)}`);
+        }
+    }
     for (const [field, flag] of BOOTSTRAP_STRING_FLAGS) {
         const value = cfg[field];
         if (value && value.trim()) {
@@ -202,26 +220,47 @@ function bootstrapRuntimeEnv(bootstrap) {
         return {};
     }
     const env = {};
-    if (bootstrap.openai_api_key)
-        env.OPENAI_API_KEY = bootstrap.openai_api_key;
-    if (bootstrap.anthropic_api_key)
-        env.ANTHROPIC_API_KEY = bootstrap.anthropic_api_key;
-    if (bootstrap.openrouter_api_key)
-        env.OPENROUTER_API_KEY = bootstrap.openrouter_api_key;
-    if (bootstrap.xai_api_key)
-        env.XAI_API_KEY = bootstrap.xai_api_key;
-    if (bootstrap.gemini_api_key)
-        env.GEMINI_API_KEY = bootstrap.gemini_api_key;
-    if (bootstrap.ai_gateway_api_key)
-        env.AI_GATEWAY_API_KEY = bootstrap.ai_gateway_api_key;
-    if (bootstrap.cloudflare_ai_gateway_api_key) {
-        env.CLOUDFLARE_AI_GATEWAY_API_KEY = bootstrap.cloudflare_ai_gateway_api_key;
+    if (bootstrap.llm_api_key?.trim()) {
+        const envKey = AUTH_CHOICE_TO_LLM_ENV[bootstrap.auth_choice ?? ""];
+        if (envKey) {
+            env[envKey] = bootstrap.llm_api_key;
+        }
     }
     return env;
 }
+function isAccountLevelBinding(item, channel, account) {
+    const match = item.match;
+    if (!match || typeof match !== "object") {
+        return false;
+    }
+    if (match.channel !== channel || match.accountId !== account) {
+        return false;
+    }
+    return (match.peer === undefined
+        && match.parentPeer === undefined
+        && match.guildId === undefined
+        && match.teamId === undefined
+        && match.roles === undefined);
+}
+function parseBindingsJson(raw) {
+    if (!raw.trim()) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            throw new ClawChefError("openclaw config bindings is not an array");
+        }
+        return parsed;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ClawChefError(`Failed to parse openclaw bindings JSON: ${message}`);
+    }
+}
 export class CommandOpenClawProvider {
     stagedMessages = new Map();
-    async ensureVersion(config, dryRun, silent, keepOpenClawState) {
+    async ensureVersion(config, dryRun, silent, preserveExistingState) {
         const bin = config.bin ?? "openclaw";
         const installPolicy = config.install ?? "auto";
         const useCmd = commandFor(config, "use_version", { bin, version: config.version });
@@ -272,7 +311,7 @@ export class CommandOpenClawProvider {
         if (installedThisRun) {
             throw new ClawChefError(`OpenClaw version mismatch after install: current ${currentVersion}, expected ${config.version}`);
         }
-        if (keepOpenClawState) {
+        if (preserveExistingState) {
             return { installedThisRun: false };
         }
         const choice = await chooseVersionMismatchAction(currentVersion, config.version, silent);
@@ -400,6 +439,53 @@ export class CommandOpenClawProvider {
         const cmd = `${bin} channels add ${flags.join(" ")}`;
         await runShell(cmd, dryRun);
     }
+    async bindChannelAgent(config, channel, agent, dryRun) {
+        const account = channel.account?.trim();
+        if (!account) {
+            throw new ClawChefError(`Channel ${channel.channel} requires account for agent binding`);
+        }
+        const bin = config.bin ?? "openclaw";
+        const customTemplate = config.commands?.bind_channel_agent;
+        if (customTemplate?.trim()) {
+            const customCmd = fillTemplate(customTemplate, {
+                bin,
+                version: config.version,
+                channel: channel.channel,
+                channel_q: shellQuote(channel.channel),
+                account,
+                account_q: shellQuote(account),
+                agent,
+                agent_q: shellQuote(agent),
+            });
+            if (customCmd.trim()) {
+                await runShell(customCmd, dryRun);
+            }
+            return;
+        }
+        if (dryRun) {
+            return;
+        }
+        const getCmd = `${bin} config get bindings --json 2>/dev/null || printf '[]'`;
+        const rawBindings = await runShell(getCmd, false);
+        const bindings = parseBindingsJson(rawBindings);
+        const nextBinding = {
+            agentId: agent,
+            match: {
+                channel: channel.channel,
+                accountId: account,
+            },
+        };
+        const index = bindings.findIndex((item) => isAccountLevelBinding(item, channel.channel, account));
+        if (index >= 0) {
+            bindings[index] = nextBinding;
+        }
+        else {
+            bindings.push(nextBinding);
+        }
+        const json = JSON.stringify(bindings);
+        const setCmd = `${bin} config set bindings ${shellQuote(json)} --json`;
+        await runShell(setCmd, false);
+    }
     async loginChannel(config, channel, dryRun) {
         if (!channel.login) {
             return;

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

@@ -2,12 +2,13 @@ import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class MockOpenClawProvider implements OpenClawProvider {
     private state;
-    ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean, _keepOpenClawState: boolean): Promise<EnsureVersionResult>;
+    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>;
     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>;
     loginChannel(_config: OpenClawSection, _channel: ChannelDef, _dryRun: boolean): Promise<void>;
     createAgent(_config: OpenClawSection, agent: AgentDef, _workspacePath: string, _dryRun: boolean): Promise<void>;
     installSkill(_config: OpenClawSection, workspace: string, agent: string, skill: string, _dryRun: boolean): Promise<void>;

package/dist/openclaw/mock-provider.js

@@ -7,7 +7,7 @@ export class MockOpenClawProvider {
         skills: new Set(),
         messages: new Map(),
     };
-    async ensureVersion(config, _dryRun, _silent, _keepOpenClawState) {
+    async ensureVersion(config, _dryRun, _silent, _preserveExistingState) {
         const policy = config.install ?? "auto";
         const installed = this.state.installedVersions.has(config.version);
         let installedThisRun = false;
@@ -44,6 +44,9 @@ export class MockOpenClawProvider {
     async configureChannel(_config, channel, _dryRun) {
         this.state.channels.add(`${channel.channel}::${channel.account ?? "default"}`);
     }
+    async bindChannelAgent(_config, _channel, _agent, _dryRun) {
+        return;
+    }
     async loginChannel(_config, _channel, _dryRun) {
         return;
     }