Agents: add account-scoped bind and routing commands by gumadeiras · Pull Request #27195 · openclaw/openclaw

gumadeiras · 2026-02-26T04:57:20Z

Summary

add openclaw agents bindings, openclaw agents bind, and openclaw agents unbind
support account-scoped channel bindings and binding upgrades without duplicate entries
load plugin registry for agents commands and support channel setup hooks for binding account resolution
add optional interactive bind step in channels add when account IDs are configured

Validation

pnpm vitest src/commands/agents.bind.commands.test.ts src/commands/agents.test.ts src/cli/program/register.agent.test.ts src/cli/program/preaction.test.ts
pnpm check

Notes

matrix-js-specific integration test is intentionally excluded from this generic PR stack because extensions/matrix-js is not in main yet.

greptile-apps · 2026-02-26T05:07:08Z

Greptile Summary

This PR adds account-scoped channel bindings and routing commands to support multi-agent configurations with account-level isolation.

Key additions:

openclaw agents bindings - lists routing bindings with optional agent filtering
openclaw agents bind - adds channel bindings with optional account scoping (e.g., telegram:work)
openclaw agents unbind - removes bindings by specification or with --all flag

Implementation highlights:

Smart binding upgrades: channel-only bindings can be upgraded to account-specific for the same agent without duplicates
Conflict detection: prevents multiple agents from claiming the same channel+account combination
Plugin hooks: new resolveBindingAccountId adapter allows channel plugins to customize account resolution
Interactive setup: channels add wizard includes optional agent routing step when account IDs are configured

Testing:

Comprehensive unit tests cover bind/unbind operations, upgrades, conflicts, and role-based routing
CLI integration tests verify command registration and option forwarding
Tests demonstrate matrix-js plugin integration pattern for account resolution hooks

Confidence Score: 5/5

This PR is safe to merge with minimal risk
The implementation is well-structured with comprehensive test coverage (200+ test lines across 3 test files). The binding logic properly handles edge cases including conflicts, duplicates, and upgrades. All new functionality follows existing codebase patterns for CLI commands, config management, and plugin integration. The PR includes proper validation, error handling, and user feedback for all operations.
No files require special attention

_{Last reviewed commit: afd13a2}

Copilot

Pull request overview

This PR adds comprehensive agent binding and routing management commands to the CLI, enabling users to configure how channels and accounts are routed to different agents. The implementation includes account-scoped bindings with automatic resolution via plugin hooks, support for binding upgrades without duplicates, and integration with the existing channels setup wizard.

Changes:

Added openclaw agents bindings, bind, and unbind commands for managing routing bindings
Implemented account-scoped binding upgrades that preserve existing bindings while refining their scope
Integrated optional interactive binding step into channels add wizard when accountIds are configured

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/commands/agents.bindings.ts	Enhanced binding identity key to include roles; added `canUpgradeBindingAccountScope` for progressive refinement; implemented `removeAgentBindings` and `resolveBindingAccountId` with plugin hook support
src/commands/agents.commands.bind.ts	New file implementing three commands: `bindings` (list), `bind` (add), and `unbind` (remove) with JSON output support and conflict detection
src/commands/agents.commands.add.ts	Updated to include `updated` field in binding results payload
src/commands/agents.test.ts	Added comprehensive tests for binding upgrades, role-based bindings, and removal behavior
src/commands/agents.bind.commands.test.ts	New test file with mock matrix-js plugin demonstrating `resolveBindingAccountId` hook usage
src/commands/channels/add.ts	Moved `accountId` resolution after input construction to support new `input` parameter; added interactive binding prompt for channels with accountIds
src/cli/program/register.agent.ts	Registered three new commands with proper option parsing and help text
src/cli/program/register.agent.test.ts	Added tests verifying command registration and option forwarding
src/cli/program/preaction.ts	Added `agents` to `PLUGIN_REQUIRED_COMMANDS` set
src/cli/program/preaction.test.ts	Added test ensuring plugin registry loads for agents command
src/channels/plugins/types.adapters.ts	Added `resolveBindingAccountId` hook and `input` parameter to `resolveAccountId`
src/commands/agents.ts	Exported new `agents.commands.bind.js` module

Comments suppressed due to low confidence (1)

src/commands/agents.bindings.ts:72

The describeBinding function doesn't include roles in the description output, but roles are part of the binding identity key and affect routing. When users list or view bindings with roles, the roles won't be shown in the description, making it unclear how the binding differs from one without roles. Consider adding roles to the description output similar to how guildId and teamId are included.

export function describeBinding(binding: AgentBinding) {
  const match = binding.match;
  const parts = [match.channel];
  if (match.accountId) {
    parts.push(`accountId=${match.accountId}`);
  }
  if (match.peer) {
    parts.push(`peer=${match.peer.kind}:${match.peer.id}`);
  }
  if (match.guildId) {
    parts.push(`guild=${match.guildId}`);
  }
  if (match.teamId) {
    parts.push(`team=${match.teamId}`);
  }
  return parts.join(" ");
}

gumadeiras · 2026-02-26T07:36:59Z

Merged via squash.

Prepared head SHA: ad35a45
Merge commit: 96c7702

Thanks @gumadeiras!

Syncs 29 upstream commits including: - Account-scoped bind and routing commands (openclaw#27195) - Single-account config migration to accounts.default (openclaw#27334) - Preserve agent-level apiKey/baseUrl during models.json merge (openclaw#27293) - Plugin-owned interactive channel onboarding flows (openclaw#27191) - Android notifications.list, invoke refactoring - Daemon launchd restart hardening - SSRF dispatcher fix, doctor improvements Conflict resolution: 4 import-order conflicts in onboarding/channel commands resolved by taking upstream (no custom code in those files).

@gumadeiras