clawchef 0.1.7 → 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

@@ -304,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.
@@ -352,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`
@@ -377,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}"
@@ -392,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.

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

@@ -8,6 +8,7 @@ export declare class CommandOpenClawProvider implements OpenClawProvider {
     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",
@@ -227,6 +228,36 @@ function bootstrapRuntimeEnv(bootstrap) {
     }
     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, preserveExistingState) {
@@ -408,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

@@ -8,6 +8,7 @@ export declare class MockOpenClawProvider implements OpenClawProvider {
     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

@@ -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;
     }

package/dist/openclaw/provider.d.ts

@@ -12,6 +12,7 @@ export interface OpenClawProvider {
     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>;
     materializeFile?(config: OpenClawSection, workspace: string, filePath: string, content: string, overwrite: boolean | undefined, dryRun: boolean): Promise<void>;
     createAgent(config: OpenClawSection, agent: AgentDef, workspacePath: string, dryRun: boolean): Promise<void>;

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

@@ -11,6 +11,7 @@ export declare class RemoteOpenClawProvider implements OpenClawProvider {
     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>;
     materializeFile(config: OpenClawSection, workspace: string, filePath: string, content: string, overwrite: boolean | undefined, dryRun: boolean): Promise<void>;
     createAgent(config: OpenClawSection, agent: AgentDef, workspacePath: string, dryRun: boolean): Promise<void>;

package/dist/openclaw/remote-provider.js

@@ -119,6 +119,13 @@ export class RemoteOpenClawProvider {
     async configureChannel(config, channel, dryRun) {
         await this.perform(config, "configure_channel", { channel }, dryRun);
     }
+    async bindChannelAgent(config, channel, agent, dryRun) {
+        await this.perform(config, "bind_channel_agent", {
+            channel: channel.channel,
+            account: channel.account,
+            agent,
+        }, dryRun);
+    }
     async loginChannel(config, channel, dryRun) {
         await this.perform(config, "login_channel", { channel }, dryRun);
     }

package/dist/orchestrator.js

@@ -215,8 +215,15 @@ export async function runRecipe(recipe, recipeOrigin, options, logger) {
         logger.info(`Agent created: ${agent.workspace}/${agent.name}`);
     }
     for (const channel of recipe.channels ?? []) {
-        await provider.configureChannel(recipe.openclaw, channel, options.dryRun);
-        logger.info(`Channel configured: ${channel.channel}${channel.account ? `/${channel.account}` : ""}`);
+        const effectiveChannel = channel.agent?.trim() && !channel.account?.trim()
+            ? { ...channel, account: channel.agent.trim() }
+            : channel;
+        await provider.configureChannel(recipe.openclaw, effectiveChannel, options.dryRun);
+        logger.info(`Channel configured: ${effectiveChannel.channel}${effectiveChannel.account ? `/${effectiveChannel.account}` : ""}`);
+        if (effectiveChannel.agent?.trim()) {
+            await provider.bindChannelAgent(recipe.openclaw, effectiveChannel, effectiveChannel.agent, options.dryRun);
+            logger.info(`Channel bound to agent: ${effectiveChannel.channel}${effectiveChannel.account ? `/${effectiveChannel.account}` : ""} -> ${effectiveChannel.agent}`);
+        }
     }
     for (const workspace of recipe.workspaces ?? []) {
         const wsPath = workspacePaths.get(workspace.name);
@@ -319,14 +326,17 @@ export async function runRecipe(recipe, recipeOrigin, options, logger) {
     await provider.startGateway(recipe.openclaw, options.dryRun);
     logger.info("Gateway started");
     for (const channel of recipe.channels ?? []) {
-        if (!channel.login) {
+        const effectiveChannel = channel.agent?.trim() && !channel.account?.trim()
+            ? { ...channel, account: channel.agent.trim() }
+            : channel;
+        if (!effectiveChannel.login) {
             continue;
         }
         if (!options.dryRun && !input.isTTY) {
-            throw new ClawChefError(`Channel login for ${channel.channel} requires an interactive terminal session`);
+            throw new ClawChefError(`Channel login for ${effectiveChannel.channel} requires an interactive terminal session`);
         }
-        await provider.loginChannel(recipe.openclaw, channel, options.dryRun);
-        logger.info(`Channel login completed: ${channel.channel}${channel.account ? `/${channel.account}` : ""}`);
+        await provider.loginChannel(recipe.openclaw, effectiveChannel, options.dryRun);
+        logger.info(`Channel login completed: ${effectiveChannel.channel}${effectiveChannel.account ? `/${effectiveChannel.account}` : ""}`);
     }
     logger.info("Recipe execution completed");
 }

package/dist/recipe.js

@@ -145,12 +145,14 @@ function filterRecipeByWorkspaceName(recipe, workspaceName) {
 }
 function semanticValidate(recipe) {
     const ws = new Set((recipe.workspaces ?? []).map((w) => w.name));
+    const agentNameCounts = new Map();
     for (const workspace of recipe.workspaces ?? []) {
         if (workspace.assets !== undefined && !workspace.assets.trim()) {
             throw new ClawChefError(`Workspace ${workspace.name} has empty assets path`);
         }
     }
     for (const agent of recipe.agents ?? []) {
+        agentNameCounts.set(agent.name, (agentNameCounts.get(agent.name) ?? 0) + 1);
         if (!ws.has(agent.workspace)) {
             throw new ClawChefError(`Agent ${agent.name} references missing workspace: ${agent.workspace}`);
         }
@@ -179,6 +181,18 @@ function semanticValidate(recipe) {
             (channel.login || channel.login_mode !== undefined || channel.login_account !== undefined)) {
             throw new ClawChefError("channels[] entry for telegram does not support login/login_mode/login_account. Configure token (or use_env/token_file), then start gateway.");
         }
+        if (channel.agent?.trim()) {
+            if (channel.channel !== "telegram") {
+                throw new ClawChefError(`channels[] entry for ${channel.channel} does not support agent binding. Use channel: telegram with agent.`);
+            }
+            const matched = agentNameCounts.get(channel.agent) ?? 0;
+            if (matched === 0) {
+                throw new ClawChefError(`channels[] entry references missing agent by name: ${channel.agent}`);
+            }
+            if (matched > 1) {
+                throw new ClawChefError(`channels[] entry references duplicate agent name: ${channel.agent}. Agent names must be unique for channel binding.`);
+            }
+        }
         const hasAuth = Boolean(channel.use_env) ||
             Boolean(channel.token?.trim()) ||
             Boolean(channel.token_file?.trim()) ||

package/dist/schema.d.ts

@@ -89,6 +89,7 @@ export declare const recipeSchema: z.ZodObject<{
             factory_reset: z.ZodOptional<z.ZodString>;
             start_gateway: z.ZodOptional<z.ZodString>;
             enable_plugin: z.ZodOptional<z.ZodString>;
+            bind_channel_agent: z.ZodOptional<z.ZodString>;
             login_channel: z.ZodOptional<z.ZodString>;
             create_workspace: z.ZodOptional<z.ZodString>;
             create_agent: z.ZodOptional<z.ZodString>;
@@ -103,6 +104,7 @@ export declare const recipeSchema: z.ZodObject<{
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
             enable_plugin?: string | undefined;
+            bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
             create_agent?: string | undefined;
             install_skill?: string | undefined;
@@ -117,6 +119,7 @@ export declare const recipeSchema: z.ZodObject<{
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
             enable_plugin?: string | undefined;
+            bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
             create_agent?: string | undefined;
             install_skill?: string | undefined;
@@ -158,6 +161,7 @@ export declare const recipeSchema: z.ZodObject<{
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
             enable_plugin?: string | undefined;
+            bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
             create_agent?: string | undefined;
             install_skill?: string | undefined;
@@ -199,6 +203,7 @@ export declare const recipeSchema: z.ZodObject<{
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
             enable_plugin?: string | undefined;
+            bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
             create_agent?: string | undefined;
             install_skill?: string | undefined;
@@ -268,6 +273,7 @@ export declare const recipeSchema: z.ZodObject<{
     channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
         channel: z.ZodString;
         account: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
         login: z.ZodOptional<z.ZodBoolean>;
         login_mode: z.ZodOptional<z.ZodEnum<["interactive"]>>;
         login_account: z.ZodOptional<z.ZodString>;
@@ -287,6 +293,7 @@ export declare const recipeSchema: z.ZodObject<{
         channel: string;
         token?: string | undefined;
         account?: string | undefined;
+        agent?: string | undefined;
         login?: boolean | undefined;
         login_mode?: "interactive" | undefined;
         login_account?: string | undefined;
@@ -305,6 +312,7 @@ export declare const recipeSchema: z.ZodObject<{
         channel: string;
         token?: string | undefined;
         account?: string | undefined;
+        agent?: string | undefined;
         login?: boolean | undefined;
         login_mode?: "interactive" | undefined;
         login_account?: string | undefined;
@@ -437,6 +445,7 @@ export declare const recipeSchema: z.ZodObject<{
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
             enable_plugin?: string | undefined;
+            bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
             create_agent?: string | undefined;
             install_skill?: string | undefined;
@@ -468,6 +477,7 @@ export declare const recipeSchema: z.ZodObject<{
         channel: string;
         token?: string | undefined;
         account?: string | undefined;
+        agent?: string | undefined;
         login?: boolean | undefined;
         login_mode?: "interactive" | undefined;
         login_account?: string | undefined;
@@ -538,6 +548,7 @@ export declare const recipeSchema: z.ZodObject<{
             factory_reset?: string | undefined;
             start_gateway?: string | undefined;
             enable_plugin?: string | undefined;
+            bind_channel_agent?: string | undefined;
             login_channel?: string | undefined;
             create_agent?: string | undefined;
             install_skill?: string | undefined;
@@ -569,6 +580,7 @@ export declare const recipeSchema: z.ZodObject<{
         channel: string;
         token?: string | undefined;
         account?: string | undefined;
+        agent?: string | undefined;
         login?: boolean | undefined;
         login_mode?: "interactive" | undefined;
         login_account?: string | undefined;

package/dist/schema.js

@@ -13,6 +13,7 @@ const openClawCommandsSchema = z
     factory_reset: z.string().optional(),
     start_gateway: z.string().optional(),
     enable_plugin: z.string().optional(),
+    bind_channel_agent: z.string().optional(),
     login_channel: z.string().optional(),
     create_workspace: z.string().optional(),
     create_agent: z.string().optional(),
@@ -79,6 +80,7 @@ const channelSchema = z
     .object({
     channel: z.string().min(1),
     account: z.string().min(1).optional(),
+    agent: z.string().min(1).optional(),
     login: z.boolean().optional(),
     login_mode: z.enum(["interactive"]).optional(),
     login_account: z.string().min(1).optional(),

package/dist/types.d.ts

@@ -22,6 +22,7 @@ export interface OpenClawCommandOverrides {
     factory_reset?: string;
     start_gateway?: string;
     enable_plugin?: string;
+    bind_channel_agent?: string;
     login_channel?: string;
     create_workspace?: string;
     create_agent?: string;
@@ -67,6 +68,7 @@ export interface WorkspaceDef {
 export interface ChannelDef {
     channel: string;
     account?: string;
+    agent?: string;
     login?: boolean;
     login_mode?: "interactive";
     login_account?: string;

package/package.json

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

package/src/openclaw/command-provider.ts

@@ -17,6 +17,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",
@@ -31,6 +32,20 @@ interface StagedMessage {
   content: string;
 }
 
+interface BindingItem {
+  agentId?: unknown;
+  match?: {
+    channel?: unknown;
+    accountId?: unknown;
+    peer?: unknown;
+    parentPeer?: unknown;
+    guildId?: unknown;
+    teamId?: unknown;
+    roles?: unknown;
+  };
+  [key: string]: unknown;
+}
+
 const SECRET_FLAG_RE =
   /(--[A-Za-z0-9-]*(?:api-key|token|password|secret)[A-Za-z0-9-]*\s+)(?:'[^']*'|"[^"]*"|\S+)/g;
 
@@ -280,6 +295,39 @@ function bootstrapRuntimeEnv(bootstrap: OpenClawBootstrap | undefined): Record<s
   return env;
 }
 
+function isAccountLevelBinding(item: BindingItem, channel: string, account: string): boolean {
+  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: string): BindingItem[] {
+  if (!raw.trim()) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+      throw new ClawChefError("openclaw config bindings is not an array");
+    }
+    return parsed as BindingItem[];
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ClawChefError(`Failed to parse openclaw bindings JSON: ${message}`);
+  }
+}
+
 export class CommandOpenClawProvider implements OpenClawProvider {
   private readonly stagedMessages = new Map<string, StagedMessage[]>();
 
@@ -502,6 +550,58 @@ export class CommandOpenClawProvider implements OpenClawProvider {
     await runShell(cmd, dryRun);
   }
 
+  async bindChannelAgent(config: OpenClawSection, channel: ChannelDef, agent: string, dryRun: boolean): Promise<void> {
+    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: BindingItem = {
+      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: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void> {
     if (!channel.login) {
       return;

package/src/openclaw/mock-provider.ts

@@ -69,6 +69,15 @@ export class MockOpenClawProvider implements OpenClawProvider {
     this.state.channels.add(`${channel.channel}::${channel.account ?? "default"}`);
   }
 
+  async bindChannelAgent(
+    _config: OpenClawSection,
+    _channel: ChannelDef,
+    _agent: string,
+    _dryRun: boolean,
+  ): Promise<void> {
+    return;
+  }
+
   async loginChannel(_config: OpenClawSection, _channel: ChannelDef, _dryRun: boolean): Promise<void> {
     return;
   }

package/src/openclaw/provider.ts

@@ -18,6 +18,7 @@ export interface OpenClawProvider {
   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>;
   materializeFile?(
     config: OpenClawSection,

package/src/openclaw/remote-provider.ts

@@ -188,6 +188,19 @@ export class RemoteOpenClawProvider implements OpenClawProvider {
     await this.perform(config, "configure_channel", { channel }, dryRun);
   }
 
+  async bindChannelAgent(config: OpenClawSection, channel: ChannelDef, agent: string, dryRun: boolean): Promise<void> {
+    await this.perform(
+      config,
+      "bind_channel_agent",
+      {
+        channel: channel.channel,
+        account: channel.account,
+        agent,
+      },
+      dryRun,
+    );
+  }
+
   async loginChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void> {
     await this.perform(config, "login_channel", { channel }, dryRun);
   }

package/src/orchestrator.ts

@@ -261,8 +261,18 @@ export async function runRecipe(
   }
 
   for (const channel of recipe.channels ?? []) {
-    await provider.configureChannel(recipe.openclaw, channel, options.dryRun);
-    logger.info(`Channel configured: ${channel.channel}${channel.account ? `/${channel.account}` : ""}`);
+    const effectiveChannel = channel.agent?.trim() && !channel.account?.trim()
+      ? { ...channel, account: channel.agent.trim() }
+      : channel;
+
+    await provider.configureChannel(recipe.openclaw, effectiveChannel, options.dryRun);
+    logger.info(`Channel configured: ${effectiveChannel.channel}${effectiveChannel.account ? `/${effectiveChannel.account}` : ""}`);
+    if (effectiveChannel.agent?.trim()) {
+      await provider.bindChannelAgent(recipe.openclaw, effectiveChannel, effectiveChannel.agent, options.dryRun);
+      logger.info(
+        `Channel bound to agent: ${effectiveChannel.channel}${effectiveChannel.account ? `/${effectiveChannel.account}` : ""} -> ${effectiveChannel.agent}`,
+      );
+    }
   }
 
   for (const workspace of recipe.workspaces ?? []) {
@@ -369,16 +379,19 @@ export async function runRecipe(
   logger.info("Gateway started");
 
   for (const channel of recipe.channels ?? []) {
-    if (!channel.login) {
+    const effectiveChannel = channel.agent?.trim() && !channel.account?.trim()
+      ? { ...channel, account: channel.agent.trim() }
+      : channel;
+    if (!effectiveChannel.login) {
       continue;
     }
     if (!options.dryRun && !input.isTTY) {
       throw new ClawChefError(
-        `Channel login for ${channel.channel} requires an interactive terminal session`,
+        `Channel login for ${effectiveChannel.channel} requires an interactive terminal session`,
       );
     }
-    await provider.loginChannel(recipe.openclaw, channel, options.dryRun);
-    logger.info(`Channel login completed: ${channel.channel}${channel.account ? `/${channel.account}` : ""}`);
+    await provider.loginChannel(recipe.openclaw, effectiveChannel, options.dryRun);
+    logger.info(`Channel login completed: ${effectiveChannel.channel}${effectiveChannel.account ? `/${effectiveChannel.account}` : ""}`);
   }
 
   logger.info("Recipe execution completed");

package/src/recipe.ts

@@ -193,12 +193,14 @@ 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>();
   for (const workspace of recipe.workspaces ?? []) {
     if (workspace.assets !== undefined && !workspace.assets.trim()) {
       throw new ClawChefError(`Workspace ${workspace.name} has empty assets path`);
     }
   }
   for (const agent of recipe.agents ?? []) {
+    agentNameCounts.set(agent.name, (agentNameCounts.get(agent.name) ?? 0) + 1);
     if (!ws.has(agent.workspace)) {
       throw new ClawChefError(`Agent ${agent.name} references missing workspace: ${agent.workspace}`);
     }
@@ -238,6 +240,23 @@ function semanticValidate(recipe: Recipe): void {
       );
     }
 
+    if (channel.agent?.trim()) {
+      if (channel.channel !== "telegram") {
+        throw new ClawChefError(
+          `channels[] entry for ${channel.channel} does not support agent binding. Use channel: telegram with agent.`,
+        );
+      }
+      const matched = agentNameCounts.get(channel.agent) ?? 0;
+      if (matched === 0) {
+        throw new ClawChefError(`channels[] entry references missing agent by name: ${channel.agent}`);
+      }
+      if (matched > 1) {
+        throw new ClawChefError(
+          `channels[] entry references duplicate agent name: ${channel.agent}. Agent names must be unique for channel binding.`,
+        );
+      }
+    }
+
     const hasAuth =
       Boolean(channel.use_env) ||
       Boolean(channel.token?.trim()) ||

package/src/schema.ts

@@ -15,6 +15,7 @@ const openClawCommandsSchema = z
     factory_reset: z.string().optional(),
     start_gateway: z.string().optional(),
     enable_plugin: z.string().optional(),
+    bind_channel_agent: z.string().optional(),
     login_channel: z.string().optional(),
     create_workspace: z.string().optional(),
     create_agent: z.string().optional(),
@@ -87,6 +88,7 @@ const channelSchema = z
   .object({
     channel: z.string().min(1),
     account: z.string().min(1).optional(),
+    agent: z.string().min(1).optional(),
     login: z.boolean().optional(),
     login_mode: z.enum(["interactive"]).optional(),
     login_account: z.string().min(1).optional(),

package/src/types.ts

@@ -25,6 +25,7 @@ export interface OpenClawCommandOverrides {
   factory_reset?: string;
   start_gateway?: string;
   enable_plugin?: string;
+  bind_channel_agent?: string;
   login_channel?: string;
   create_workspace?: string;
   create_agent?: string;
@@ -74,6 +75,7 @@ export interface WorkspaceDef {
 export interface ChannelDef {
   channel: string;
   account?: string;
+  agent?: string;
   login?: boolean;
   login_mode?: "interactive";
   login_account?: string;