agent-intercom-config

name	agent-intercom-config
description	Configure OpenClaw multi-agent communication with sessions_send routing, allowlists, sender tags, and async ack rules. Use when setting up or fixing agent-to-agent messaging, cross-session relays, or ambiguous sender identity.

Agent Intercom Config

Set up reliable communication between agents.

Goals

• Allow cross-agent messaging via sessions_send
• Prevent unknown target and permission failures
• Make sender identity explicit in relayed messages
• Enforce async behavior for long-running requests

1) Minimum config in openclaw.json

Update these sections.

A. Agent allowlists

"agents": {
  "list": [
    { "id": "main", "subagents": { "allowAgents": ["dae", "unicorn"] } },
    { "id": "dae", "subagents": { "allowAgents": ["main", "unicorn"] } },
    { "id": "unicorn", "subagents": { "allowAgents": ["main", "dae"] } }
  ]
}

B. Agent-to-agent tool allowlist

"tools": {
  "agentToAgent": {
    "enabled": true,
    "allow": ["main", "dae", "unicorn"]
  }
}

2) Rule: steer vs send

• subagents.steer only controls sub-runs spawned by the same requester session.
• sessions_send is for cross-session or cross-agent messaging.

If you see "Unknown subagent target", switch from subagents.steer to sessions_send.

3) Sender tag protocol

In shared channels, relay messages must include tags:

• [master] ...
• [dae] ...
• [unicorn] ...
• if uncertain: [...][source-uncertain] ...

Do not claim certain sender identity from metadata alone when metadata is ambiguous.

3.1) Intent-based forwarding (hard rule)

When a requester says things like:

• "问呱呱 / 问baby / 问main"
• "帮我问另一个 agent"
• "转发给 xxx"

then the current agent MUST relay instead of answering locally:

1. Use sessions_send to target the intended agent session.
2. Prefix outbound message with sender tag (e.g., [dae] master问：...).
3. Wait for reply and then relay back to requester.

Forbidden in relay intent:

• answering directly with local tools before relay (e.g., local exec get-date)
• using subagents.steer for cross-agent messaging

4) Async relay protocol

For long tasks between agents:

1. Immediate ack: zheng zai cha xun, wan cheng hou zhu dong tong zhi ni
2. Continue async in background/sub-agent
3. Push final result proactively (success or failure)

Never leave requester waiting silently.

4.1) Timeout handling (hard rule)

If a spawned child/sub-agent hits timeout or returns no output:

1. Do not keep waiting or poll in a loop.
2. Do not repeatedly retry the same launch automatically.
3. Reply immediately in normal assistant voice with a short status like:
   • 已启动，但模型超时了。
   • or 已经触发，但这次超时了，我可以继续重试。
4. Treat timeout as a terminal status for that attempt unless the user explicitly asks to retry.

This prevents silent waiting and prevents repeated completion/restart storms.

4.2) Storm prevention rules (hard rule)

To reduce conversation/restart storms:

• Never create polling loops with sessions_list, sessions_history, subagents list, or repeated exec sleep checks.
• After spawning a child, rely on push completion events unless the user explicitly asks for status.
• If config reload/restart is pending while replies/tool runs are active, avoid stacking additional restart attempts.
• Prefer one clear terminal update over multiple partial updates.
• If a request already timed out once, ask before retrying unless the user already requested auto-retry.

5) Per-agent workspace notes

Create or update per-agent docs (use AGENT_LINKS.md) for all collaborating workspaces (main/dae/unicorn), including:

• target sessionKey conventions (agent:main:main, etc.)
• sessions_list -> sessions_send workflow
• sender-tag rules
• intent-based forwarding hard rule (relay intent => must use sessions_send)
• async ack rules
• human nickname/alias mapping (example: 独角兽 => unicorn)
• fallback lookup order when only a nickname is given

Recommended minimum rollout:

• workspace/AGENT_LINKS.md (main)
• workspace-dae/AGENT_LINKS.md
• workspace-unicorn/AGENT_LINKS.md

5.1) Alias routing rule (important)

When a human uses a nickname like:

• 独角兽
• unicorn
• dae
• 呱呱
• baby

then resolve target in this order:

1. Check AGENT_LINKS.md alias map first.
2. If alias points to a fixed main session, use that sessionKey directly.
3. If alias points to an agent family (example: unicorn), use sessions_list once and pick the most recent live/done session whose key starts with that agent prefix.
4. If still ambiguous, ask one clarifying question instead of silently guessing.

This avoids failures like No session found with label: unicorn when the real target exists only as a sessionKey such as agent:unicorn:subagent:<uuid>.

6) Verify

Run:

openclaw models status --agent dae --probe --probe-provider openai-codex
openclaw models status --agent unicorn --probe --probe-provider openai-codex

Functional checks:

• agent A sends a tagged message to B using sessions_send
• B receives and replies with proper tag
• long task triggers immediate ack and completion push

7) Common pitfalls

• using nickname instead of real agent id (example: GuaGua vs main)
• using subagents.steer for cross-agent messaging
• missing tools.agentToAgent.allow entries
• forgetting restart or reload when runtime does not hot-apply config