CLI: add explicit agents bind/unbind/bindings commands

src/cli/program/register.agent.test.ts

@@ -3,9 +3,12 @@ import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const agentCliCommandMock = vi.fn();
 const agentsAddCommandMock = vi.fn();
+const agentsBindingsCommandMock = vi.fn();
+const agentsBindCommandMock = vi.fn();
 const agentsDeleteCommandMock = vi.fn();
 const agentsListCommandMock = vi.fn();
 const agentsSetIdentityCommandMock = vi.fn();
+const agentsUnbindCommandMock = vi.fn();
 const setVerboseMock = vi.fn();
 const createDefaultDepsMock = vi.fn(() => ({ deps: true }));
 
@@ -21,9 +24,12 @@ vi.mock("../../commands/agent-via-gateway.js", () => ({
 
 vi.mock("../../commands/agents.js", () => ({
   agentsAddCommand: agentsAddCommandMock,
+  agentsBindingsCommand: agentsBindingsCommandMock,
+  agentsBindCommand: agentsBindCommandMock,
   agentsDeleteCommand: agentsDeleteCommandMock,
   agentsListCommand: agentsListCommandMock,
   agentsSetIdentityCommand: agentsSetIdentityCommandMock,
+  agentsUnbindCommand: agentsUnbindCommandMock,
 }));
 
 vi.mock("../../globals.js", () => ({
@@ -55,9 +61,12 @@ describe("registerAgentCommands", () => {
     vi.clearAllMocks();
     agentCliCommandMock.mockResolvedValue(undefined);
     agentsAddCommandMock.mockResolvedValue(undefined);
+    agentsBindingsCommandMock.mockResolvedValue(undefined);
+    agentsBindCommandMock.mockResolvedValue(undefined);
     agentsDeleteCommandMock.mockResolvedValue(undefined);
     agentsListCommandMock.mockResolvedValue(undefined);
     agentsSetIdentityCommandMock.mockResolvedValue(undefined);
+    agentsUnbindCommandMock.mockResolvedValue(undefined);
     createDefaultDepsMock.mockReturnValue({ deps: true });
   });
 
@@ -147,6 +156,52 @@ describe("registerAgentCommands", () => {
     );
   });
 
+  it("forwards agents bindings options", async () => {
+    await runCli(["agents", "bindings", "--agent", "ops", "--json"]);
+    expect(agentsBindingsCommandMock).toHaveBeenCalledWith(
+      {
+        agent: "ops",
+        json: true,
+      },
+      runtime,
+    );
+  });
+
+  it("forwards agents bind options", async () => {
+    await runCli([
+      "agents",
+      "bind",
+      "--agent",
+      "ops",
+      "--bind",
+      "matrix-js:ops",
+      "--bind",
+      "telegram",
+      "--json",
+    ]);
+    expect(agentsBindCommandMock).toHaveBeenCalledWith(
+      {
+        agent: "ops",
+        bind: ["matrix-js:ops", "telegram"],
+        json: true,
+      },
+      runtime,
+    );
+  });
+
+  it("forwards agents unbind options", async () => {
+    await runCli(["agents", "unbind", "--agent", "ops", "--all", "--json"]);
+    expect(agentsUnbindCommandMock).toHaveBeenCalledWith(
+      {
+        agent: "ops",
+        bind: [],
+        all: true,
+        json: true,
+      },
+      runtime,
+    );
+  });
+
   it("forwards agents delete options", async () => {
     await runCli(["agents", "delete", "worker-a", "--force", "--json"]);
     expect(agentsDeleteCommandMock).toHaveBeenCalledWith(

src/cli/program/register.agent.ts

@@ -2,9 +2,12 @@ import type { Command } from "commander";
 import { agentCliCommand } from "../../commands/agent-via-gateway.js";
 import {
   agentsAddCommand,
+  agentsBindingsCommand,
+  agentsBindCommand,
   agentsDeleteCommand,
   agentsListCommand,
   agentsSetIdentityCommand,
+  agentsUnbindCommand,
 } from "../../commands/agents.js";
 import { setVerbose } from "../../globals.js";
 import { defaultRuntime } from "../../runtime.js";
@@ -102,6 +105,63 @@ ${theme.muted("Docs:")} ${formatDocsLink("/cli/agent", "docs.openclaw.ai/cli/age
       });
     });
 
+  agents
+    .command("bindings")
+    .description("List routing bindings")
+    .option("--agent <id>", "Filter by agent id")
+    .option("--json", "Output JSON instead of text", false)
+    .action(async (opts) => {
+      await runCommandWithRuntime(defaultRuntime, async () => {
+        await agentsBindingsCommand(
+          {
+            agent: opts.agent as string | undefined,
+            json: Boolean(opts.json),
+          },
+          defaultRuntime,
+        );
+      });
+    });
+
+  agents
+    .command("bind")
+    .description("Add routing bindings for an agent")
+    .option("--agent <id>", "Agent id (defaults to current default agent)")
+    .option("--bind <channel[:accountId]>", "Binding to add (repeatable)", collectOption, [])
+    .option("--json", "Output JSON summary", false)
+    .action(async (opts) => {
+      await runCommandWithRuntime(defaultRuntime, async () => {
+        await agentsBindCommand(
+          {
+            agent: opts.agent as string | undefined,
+            bind: Array.isArray(opts.bind) ? (opts.bind as string[]) : undefined,
+            json: Boolean(opts.json),
+          },
+          defaultRuntime,
+        );
+      });
+    });
+
+  agents
+    .command("unbind")
+    .description("Remove routing bindings for an agent")
+    .option("--agent <id>", "Agent id (defaults to current default agent)")
+    .option("--bind <channel[:accountId]>", "Binding to remove (repeatable)", collectOption, [])
+    .option("--all", "Remove all bindings for this agent", false)
+    .option("--json", "Output JSON summary", false)
+    .action(async (opts) => {
+      await runCommandWithRuntime(defaultRuntime, async () => {
+        await agentsUnbindCommand(
+          {
+            agent: opts.agent as string | undefined,
+            bind: Array.isArray(opts.bind) ? (opts.bind as string[]) : undefined,
+            all: Boolean(opts.all),
+            json: Boolean(opts.json),
+          },
+          defaultRuntime,
+        );
+      });
+    });
+
   agents
     .command("add [name]")
     .description("Add a new isolated agent")

src/commands/agents.bind.commands.test.ts

@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { baseConfigSnapshot, createTestRuntime } from "./test-runtime-config-helpers.js";
+
+const readConfigFileSnapshotMock = vi.hoisted(() => vi.fn());
+const writeConfigFileMock = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+
+vi.mock("../config/config.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../config/config.js")>()),
+  readConfigFileSnapshot: readConfigFileSnapshotMock,
+  writeConfigFile: writeConfigFileMock,
+}));
+
+import { agentsBindCommand, agentsBindingsCommand, agentsUnbindCommand } from "./agents.js";
+
+const runtime = createTestRuntime();
+
+describe("agents bind/unbind commands", () => {
+  beforeEach(() => {
+    readConfigFileSnapshotMock.mockClear();
+    writeConfigFileMock.mockClear();
+    runtime.log.mockClear();
+    runtime.error.mockClear();
+    runtime.exit.mockClear();
+  });
+
+  it("lists all bindings by default", async () => {
+    readConfigFileSnapshotMock.mockResolvedValue({
+      ...baseConfigSnapshot,
+      config: {
+        bindings: [
+          { agentId: "main", match: { channel: "matrix-js" } },
+          { agentId: "ops", match: { channel: "telegram", accountId: "work" } },
+        ],
+      },
+    });
+
+    await agentsBindingsCommand({}, runtime);
+
+    expect(runtime.log).toHaveBeenCalledWith(expect.stringContaining("main <- matrix-js"));
+    expect(runtime.log).toHaveBeenCalledWith(
+      expect.stringContaining("ops <- telegram accountId=work"),
+    );
+  });
+
+  it("binds routes to default agent when --agent is omitted", async () => {
+    readConfigFileSnapshotMock.mockResolvedValue({
+      ...baseConfigSnapshot,
+      config: {},
+    });
+
+    await agentsBindCommand({ bind: ["telegram"] }, runtime);
+
+    expect(writeConfigFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        bindings: [{ agentId: "main", match: { channel: "telegram" } }],
+      }),
+    );
+    expect(runtime.exit).not.toHaveBeenCalled();
+  });
+
+  it("unbinds all routes for an agent", async () => {
+    readConfigFileSnapshotMock.mockResolvedValue({
+      ...baseConfigSnapshot,
+      config: {
+        agents: { list: [{ id: "ops", workspace: "/tmp/ops" }] },
+        bindings: [
+          { agentId: "main", match: { channel: "matrix-js" } },
+          { agentId: "ops", match: { channel: "telegram", accountId: "work" } },
+        ],
+      },
+    });
+
+    await agentsUnbindCommand({ agent: "ops", all: true }, runtime);
+
+    expect(writeConfigFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        bindings: [{ agentId: "main", match: { channel: "matrix-js" } }],
+      }),
+    );
+    expect(runtime.exit).not.toHaveBeenCalled();
+  });
+
+  it("reports ownership conflicts during unbind and exits 1", async () => {
+    readConfigFileSnapshotMock.mockResolvedValue({
+      ...baseConfigSnapshot,
+      config: {
+        agents: { list: [{ id: "ops", workspace: "/tmp/ops" }] },
+        bindings: [{ agentId: "main", match: { channel: "telegram", accountId: "ops" } }],
+      },
+    });
+
+    await agentsUnbindCommand({ agent: "ops", bind: ["telegram:ops"] }, runtime);
+
+    expect(writeConfigFileMock).not.toHaveBeenCalled();
+    expect(runtime.error).toHaveBeenCalledWith("Bindings are owned by another agent:");
+    expect(runtime.exit).toHaveBeenCalledWith(1);
+  });
+});

src/commands/agents.bindings.ts

@@ -89,6 +89,72 @@ export function applyAgentBindings(
   };
 }
 
+export function removeAgentBindings(
+  cfg: OpenClawConfig,
+  bindings: AgentBinding[],
+): {
+  config: OpenClawConfig;
+  removed: AgentBinding[];
+  missing: AgentBinding[];
+  conflicts: Array<{ binding: AgentBinding; existingAgentId: string }>;
+} {
+  const existing = cfg.bindings ?? [];
+  const removeIndexes = new Set<number>();
+  const removed: AgentBinding[] = [];
+  const missing: AgentBinding[] = [];
+  const conflicts: Array<{ binding: AgentBinding; existingAgentId: string }> = [];
+
+  for (const binding of bindings) {
+    const desiredAgentId = normalizeAgentId(binding.agentId);
+    const key = bindingMatchKey(binding.match);
+    let matchedIndex = -1;
+    let conflictingAgentId: string | null = null;
+    for (let i = 0; i < existing.length; i += 1) {
+      if (removeIndexes.has(i)) {
+        continue;
+      }
+      const current = existing[i];
+      if (!current || bindingMatchKey(current.match) !== key) {
+        continue;
+      }
+      const currentAgentId = normalizeAgentId(current.agentId);
+      if (currentAgentId === desiredAgentId) {
+        matchedIndex = i;
+        break;
+      }
+      conflictingAgentId = currentAgentId;
+    }
+    if (matchedIndex >= 0) {
+      const matched = existing[matchedIndex];
+      if (matched) {
+        removeIndexes.add(matchedIndex);
+        removed.push(matched);
+      }
+      continue;
+    }
+    if (conflictingAgentId) {
+      conflicts.push({ binding, existingAgentId: conflictingAgentId });
+      continue;
+    }
+    missing.push(binding);
+  }
+
+  if (removeIndexes.size === 0) {
+    return { config: cfg, removed, missing, conflicts };
+  }
+
+  const nextBindings = existing.filter((_, index) => !removeIndexes.has(index));
+  return {
+    config: {
+      ...cfg,
+      bindings: nextBindings.length > 0 ? nextBindings : undefined,
+    },
+    removed,
+    missing,
+    conflicts,
+  };
+}
+
 function resolveDefaultAccountId(cfg: OpenClawConfig, provider: ChannelId): string {
   const plugin = getChannelPlugin(provider);
   if (!plugin) {

src/commands/agents.commands.bind.ts

@@ -0,0 +1,316 @@
+import { resolveDefaultAgentId } from "../agents/agent-scope.js";
+import { writeConfigFile } from "../config/config.js";
+import { logConfigUpdated } from "../config/logging.js";
+import type { AgentBinding } from "../config/types.js";
+import { normalizeAgentId } from "../routing/session-key.js";
+import type { RuntimeEnv } from "../runtime.js";
+import { defaultRuntime } from "../runtime.js";
+import {
+  applyAgentBindings,
+  describeBinding,
+  parseBindingSpecs,
+  removeAgentBindings,
+} from "./agents.bindings.js";
+import { requireValidConfig } from "./agents.command-shared.js";
+import { buildAgentSummaries } from "./agents.config.js";
+
+type AgentsBindingsListOptions = {
+  agent?: string;
+  json?: boolean;
+};
+
+type AgentsBindOptions = {
+  agent?: string;
+  bind?: string[];
+  json?: boolean;
+};
+
+type AgentsUnbindOptions = {
+  agent?: string;
+  bind?: string[];
+  all?: boolean;
+  json?: boolean;
+};
+
+function resolveAgentId(
+  cfg: Awaited<ReturnType<typeof requireValidConfig>>,
+  agentInput: string | undefined,
+  params?: { fallbackToDefault?: boolean },
+): string | null {
+  if (!cfg) {
+    return null;
+  }
+  if (agentInput?.trim()) {
+    return normalizeAgentId(agentInput);
+  }
+  if (params?.fallbackToDefault) {
+    return resolveDefaultAgentId(cfg);
+  }
+  return null;
+}
+
+function hasAgent(cfg: Awaited<ReturnType<typeof requireValidConfig>>, agentId: string): boolean {
+  if (!cfg) {
+    return false;
+  }
+  return buildAgentSummaries(cfg).some((summary) => summary.id === agentId);
+}
+
+function formatBindingOwnerLine(binding: AgentBinding): string {
+  return `${normalizeAgentId(binding.agentId)} <- ${describeBinding(binding)}`;
+}
+
+export async function agentsBindingsCommand(
+  opts: AgentsBindingsListOptions,
+  runtime: RuntimeEnv = defaultRuntime,
+) {
+  const cfg = await requireValidConfig(runtime);
+  if (!cfg) {
+    return;
+  }
+
+  const filterAgentId = resolveAgentId(cfg, opts.agent?.trim());
+  if (opts.agent && !filterAgentId) {
+    runtime.error("Agent id is required.");
+    runtime.exit(1);
+    return;
+  }
+  if (filterAgentId && !hasAgent(cfg, filterAgentId)) {
+    runtime.error(`Agent "${filterAgentId}" not found.`);
+    runtime.exit(1);
+    return;
+  }
+
+  const filtered = (cfg.bindings ?? []).filter(
+    (binding) => !filterAgentId || normalizeAgentId(binding.agentId) === filterAgentId,
+  );
+  if (opts.json) {
+    runtime.log(
+      JSON.stringify(
+        filtered.map((binding) => ({
+          agentId: normalizeAgentId(binding.agentId),
+          match: binding.match,
+          description: describeBinding(binding),
+        })),
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (filtered.length === 0) {
+    runtime.log(
+      filterAgentId ? `No routing bindings for agent "${filterAgentId}".` : "No routing bindings.",
+    );
+    return;
+  }
+
+  runtime.log(
+    [
+      "Routing bindings:",
+      ...filtered.map((binding) => `- ${formatBindingOwnerLine(binding)}`),
+    ].join("\n"),
+  );
+}
+
+export async function agentsBindCommand(
+  opts: AgentsBindOptions,
+  runtime: RuntimeEnv = defaultRuntime,
+) {
+  const cfg = await requireValidConfig(runtime);
+  if (!cfg) {
+    return;
+  }
+
+  const agentId = resolveAgentId(cfg, opts.agent?.trim(), { fallbackToDefault: true });
+  if (!agentId) {
+    runtime.error("Unable to resolve agent id.");
+    runtime.exit(1);
+    return;
+  }
+  if (!hasAgent(cfg, agentId)) {
+    runtime.error(`Agent "${agentId}" not found.`);
+    runtime.exit(1);
+    return;
+  }
+
+  const specs = (opts.bind ?? []).map((value) => value.trim()).filter(Boolean);
+  if (specs.length === 0) {
+    runtime.error("Provide at least one --bind <channel[:accountId]>.");
+    runtime.exit(1);
+    return;
+  }
+
+  const parsed = parseBindingSpecs({ agentId, specs, config: cfg });
+  if (parsed.errors.length > 0) {
+    runtime.error(parsed.errors.join("\n"));
+    runtime.exit(1);
+    return;
+  }
+
+  const result = applyAgentBindings(cfg, parsed.bindings);
+  if (result.added.length > 0) {
+    await writeConfigFile(result.config);
+    if (!opts.json) {
+      logConfigUpdated(runtime);
+    }
+  }
+
+  const payload = {
+    agentId,
+    added: result.added.map(describeBinding),
+    skipped: result.skipped.map(describeBinding),
+    conflicts: result.conflicts.map(
+      (conflict) => `${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`,
+    ),
+  };
+  if (opts.json) {
+    runtime.log(JSON.stringify(payload, null, 2));
+    if (result.conflicts.length > 0) {
+      runtime.exit(1);
+    }
+    return;
+  }
+
+  if (result.added.length > 0) {
+    runtime.log("Added bindings:");
+    for (const binding of result.added) {
+      runtime.log(`- ${describeBinding(binding)}`);
+    }
+  } else {
+    runtime.log("No new bindings added.");
+  }
+
+  if (result.skipped.length > 0) {
+    runtime.log("Already present:");
+    for (const binding of result.skipped) {
+      runtime.log(`- ${describeBinding(binding)}`);
+    }
+  }
+
+  if (result.conflicts.length > 0) {
+    runtime.error("Skipped bindings already claimed by another agent:");
+    for (const conflict of result.conflicts) {
+      runtime.error(`- ${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`);
+    }
+    runtime.exit(1);
+  }
+}
+
+export async function agentsUnbindCommand(
+  opts: AgentsUnbindOptions,
+  runtime: RuntimeEnv = defaultRuntime,
+) {
+  const cfg = await requireValidConfig(runtime);
+  if (!cfg) {
+    return;
+  }
+
+  const agentId = resolveAgentId(cfg, opts.agent?.trim(), { fallbackToDefault: true });
+  if (!agentId) {
+    runtime.error("Unable to resolve agent id.");
+    runtime.exit(1);
+    return;
+  }
+  if (!hasAgent(cfg, agentId)) {
+    runtime.error(`Agent "${agentId}" not found.`);
+    runtime.exit(1);
+    return;
+  }
+  if (opts.all && (opts.bind?.length ?? 0) > 0) {
+    runtime.error("Use either --all or --bind, not both.");
+    runtime.exit(1);
+    return;
+  }
+
+  if (opts.all) {
+    const existing = cfg.bindings ?? [];
+    const removed = existing.filter((binding) => normalizeAgentId(binding.agentId) === agentId);
+    const kept = existing.filter((binding) => normalizeAgentId(binding.agentId) !== agentId);
+    if (removed.length === 0) {
+      runtime.log(`No bindings to remove for agent "${agentId}".`);
+      return;
+    }
+    const next = {
+      ...cfg,
+      bindings: kept.length > 0 ? kept : undefined,
+    };
+    await writeConfigFile(next);
+    if (!opts.json) {
+      logConfigUpdated(runtime);
+    }
+    const payload = {
+      agentId,
+      removed: removed.map(describeBinding),
+      missing: [] as string[],
+      conflicts: [] as string[],
+    };
+    if (opts.json) {
+      runtime.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    runtime.log(`Removed ${removed.length} binding(s) for "${agentId}".`);
+    return;
+  }
+
+  const specs = (opts.bind ?? []).map((value) => value.trim()).filter(Boolean);
+  if (specs.length === 0) {
+    runtime.error("Provide at least one --bind <channel[:accountId]> or use --all.");
+    runtime.exit(1);
+    return;
+  }
+
+  const parsed = parseBindingSpecs({ agentId, specs, config: cfg });
+  if (parsed.errors.length > 0) {
+    runtime.error(parsed.errors.join("\n"));
+    runtime.exit(1);
+    return;
+  }
+
+  const result = removeAgentBindings(cfg, parsed.bindings);
+  if (result.removed.length > 0) {
+    await writeConfigFile(result.config);
+    if (!opts.json) {
+      logConfigUpdated(runtime);
+    }
+  }
+
+  const payload = {
+    agentId,
+    removed: result.removed.map(describeBinding),
+    missing: result.missing.map(describeBinding),
+    conflicts: result.conflicts.map(
+      (conflict) => `${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`,
+    ),
+  };
+  if (opts.json) {
+    runtime.log(JSON.stringify(payload, null, 2));
+    if (result.conflicts.length > 0) {
+      runtime.exit(1);
+    }
+    return;
+  }
+
+  if (result.removed.length > 0) {
+    runtime.log("Removed bindings:");
+    for (const binding of result.removed) {
+      runtime.log(`- ${describeBinding(binding)}`);
+    }
+  } else {
+    runtime.log("No bindings removed.");
+  }
+  if (result.missing.length > 0) {
+    runtime.log("Not found:");
+    for (const binding of result.missing) {
+      runtime.log(`- ${describeBinding(binding)}`);
+    }
+  }
+  if (result.conflicts.length > 0) {
+    runtime.error("Bindings are owned by another agent:");
+    for (const conflict of result.conflicts) {
+      runtime.error(`- ${describeBinding(conflict.binding)} (agent=${conflict.existingAgentId})`);
+    }
+    runtime.exit(1);
+  }
+}

src/commands/agents.ts

@@ -1,4 +1,5 @@
 export * from "./agents.bindings.js";
+export * from "./agents.commands.bind.js";
 export * from "./agents.commands.add.js";
 export * from "./agents.commands.delete.js";
 export * from "./agents.commands.identity.js";