Problem

When creating a new agent instance, if the user configures agents.list[], workspace (with SOUL.md/IDENTITY.md), and channels.feishu.accounts.<id>, but forgets to add a bindings[] entry, the system silently falls back to the main agent.

Symptom: The new bot responds with the main agent's identity instead of its own (e.g., a "stack" bot自称 "Mango").

Log appearance: feishu[stack]: dispatching to agent (session=agent:main:main) — this looks like a normal dispatch to a user who doesn't know about bindings.

Root Cause

The config is split into three independent pieces that must all be present:

1. agents.list[] — defines the agent
2. channels.<ch>.accounts.<id> — channel credentials
3. bindings[] — routes channel+account → agent

When bindings[] has no matching entry, the dispatch phase silently falls back to main with no error, no warning, no log distinction from a normal dispatch.

Three Compounding Design Issues

1. Config Fragmentation

Three independent config blocks must be manually aligned. CLI/wizard guides users through agents.list[] and channels.*.accounts.* but often omits bindings[]. There's no declaration-style linking (like K8s label selectors).

2. Silent Fallback

When no binding matches, the system falls back to main without any warning. The error manifests as "wrong agent identity," which is very far from the actual root cause (routing config). This makes debugging extremely difficult — users naturally check SOUL.md/IDENTITY.md first.

3. Inconsistent Hot-Reload

Other config sections (agents.list[], channels.feishu.accounts.*, mcp.servers) support hot-reload. bindings[] does not — changes require a gateway restart. But the log says config change detected; evaluating reload (bindings) without indicating that restart is needed.

Proposed Improvements (by priority)

P0: Startup Sanity Check

Scan all channels.<ch>.accounts.* entries and check if each has a corresponding bindings[] entry. Output WARNING for any account without a binding:

WARNING: channel account "stack" (feishu) has no binding — will silently fallback to main agent

This alone eliminates this class of bugs.

P1: Dispatch-time Warning

When dispatch falls back to main, upgrade log to WARN with explicit reason:

WARN: no binding matched (channel=feishu, accountId=stack); falling back to main agent

Make fallback logs distinguishable from normal dispatch.

P2: Agent Creation Wizard Completion

When openclaw agent create or console "new agent" flow detects a channel account was configured, auto-generate the corresponding binding entry — or at minimum prompt: "No binding configured for this agent. Would you like to add one?"

P3: Hot-Reload Consistency

Either make bindings[] support hot-reload, or when a bindings change is detected but cannot be hot-applied, output explicit guidance:

NOTICE: bindings changes require gateway restart — run: openclaw gateway restart

P4 (Optional): Convention-Based Binding

When agents.list[].id matches a channels.<ch>.accounts.<id> name and no explicit binding exists, automatically route by name convention. This reduces the need for manual bindings[] maintenance.

P5: Config Validation CLI

openclaw config check or openclaw agent validate <id> — one-shot diagnostic that checks all four elements (agent exists, workspace has SOUL.md, channel account valid, binding present) and outputs a report.

Environment

• OpenClaw CLI 2026.6.9 (c645ec4)
• macOS Darwin 25.5.0 (arm64)
• Channel: feishu (websocket mode)
• Affects: all agents with "complete config but missing binding"