openclaw-inter-instance

Communication between OpenClaw instances

When to use this skill

• Need to send a message to another OpenClaw instance
• Execute commands remotely across machines
• Multi-agent collaborative tasks
• Synchronize repositories/files to a remote instance

Communication method priority

Sorted by reliability and real-time capability, try in order:

1. sessions_send (best, requires configuration)

Direct agent-to-agent messaging, real-time and bidirectional.

Prerequisite: enabled in both configurations:

// ~/.openclaw/openclaw.json
"tools": { "agentToAgent": { "enabled": true } }

Usage:

sessions_send(sessionKey="agent:<target-agent>:main", message="...")

Pros: real-time, bidirectional, most concise Cons: disabled by default, requires both ends to enable it

2. nodes.run (remote command execution)

Execute commands on a remote machine through a paired node.

Prerequisite: the target machine is paired as a node and online (nodes status check)

Usage:

nodes(action="run", node="<node-name>", command=["bash", "-c", "<command>"], commandTimeoutMs=30000)

Notes:

• Environment variables may differ from local (such as proxy settings)
• Use env -u HTTP_PROXY -u HTTPS_PROXY to bypass an unreachable proxy
• Complex commands easily time out; split them into multiple small steps
• It times out when the gateway responds slowly (default 30s); you can increase commandTimeoutMs

Typical scenarios:

# 检查文件是否存在
nodes run: ["bash", "-c", "ls ~/target-dir 2>/dev/null && echo EXISTS || echo NOT_FOUND"]

# clone 仓库（注意代理问题）
nodes run: ["bash", "-c", "env -u HTTP_PROXY -u HTTPS_PROXY git clone https://github.com/user/repo.git ~/repo 2>&1"]

# 创建软链接
nodes run: ["bash", "-c", "ln -sfn /source/path /target/path && readlink /target/path"]

3. openclaw agent CLI (call a remote gateway through a node)

Inject a message into the target instance through the CLI on the remote node.

Usage:

openclaw agent --session-id <session-id> -m '<message>' --json

Note: you need to wait for the gateway to process the agent turn, and it easily times out (60-120s). Suitable for non-urgent notifications.

4. File-level communication (fallback solution)

Write directly into the target instance's memory file and wait for heartbeat to read it.

Usage:

# 通过 nodes.run 写入远程 memory 文件
cat >> <workspace>/memory/YYYY-MM-DD.md << 'EOF'
## 来自小a的通知 (HH:MM)
<消息内容>
EOF

Pros: it will definitely be delivered, does not depend on a real-time connection Cons: not real-time, you need to wait for heartbeat or a new session before it can be read

5. Telegram/messaging channels (limited)

Send through the message tool.

Limitation: Telegram bots cannot send messages to each other (403 Forbidden). Only applicable to bot → human scenarios.

Infeasible methods

Method	Reason
Telegram bot → bot	Forbidden by the Telegram API
curl calling the remote gateway REST API	The gateway does not expose a REST messaging interface
sessions_send without agentToAgent enabled	Returns forbidden

Practical checklist

1. nodes status — Is the target node online?
2. Does the target machine have proxy/network restrictions?
3. Is the SSH key configured? (HTTPS is more stable for git clone)
4. Are the timeout settings sufficient?
5. Is the symlink path correct?

Recommended architecture

小a (Linux VPS)                    小m (Mac-Mini)
├── OpenClaw gateway               ├── OpenClaw gateway
├── ~/AGI-Super-Skills (git repo)  ├── ~/AGI-Super-Skills (git clone)
├── ~/clawd/skills/ (workspace)    ├── ~/.openclaw/workspace/skills → ~/AGI-Super-Skills/skills
│                                  │
├── nodes.run ──────────────────── ├── paired node (connected)
└── sessions_send ─────────────── └── agent-to-agent (需开启)

Local Agent coordination (A2A)

⭐ Executive working mode (core principle)

You are an executive, not a mouthpiece.

1. Assign the task and move on — sessions_send without carrying timeoutSeconds(or set to 1-5s), do the next thing immediately after sending the instruction
2. Do not forward — employees post messages in the group themselves; you do not forward replies on their behalf
3. Do not wait idly — 9 employees work in parallel; you do not need to wait for results one by one
4. Parallel processing — after assigning tasks, continue handling Daniel's other requests
5. Focus on results only — employees report to the group; you only need to review quality

❌ 错误模式（秘书）:
   派活 → 等回复 → 转发回复 → 再派下一个

✅ 正确模式（高管）:
   批量派活（不等） → 做其他事 → 看群里汇报 → 审核质量

Instruction template

sessions_send(
  sessionKey="agent:<agentId>:telegram:group:YOUR_GROUP_CHAT_ID",
  message="【小a工作指令】<具体任务>。直接在群里发结果，不要回复我。",
  timeoutSeconds=5  // 最多等5秒，超时也没关系，后台会继续
)

Difference between sessions_send and message

Method	Function	Correct use
message(accountId=xxx, target=群ID)	Send a message as that bot	Announcements, notifications, sending fixed text in an employee's name
sessions_send(sessionKey=..., message=...)	Send an instruction to the agent; the agent handles it and replies on its own	Assigning tasks, triggering agent behavior

sessionKey format (local agent)

agent:<agentId>:telegram:group:<chatId>

⚠️ Note: delivery echo issue

sessions_send By default, delivery: "announce" will echo the agent's reply to the caller's session, causing the main bot to repeatedly post the agent's reply in the group. The agent has already sent the message itself via the message tool, so the echo is redundant.

Solution: the agent itself sends messages to the group; the main bot does not need to forward them again. Seeing the agent's status=ok/timeout is enough.

Complete employee list

Employee	agentId	accountId	Model
Little ops	ops	xiaoops	xsc-opus46
Little code	code	xiaocode	xsc-opus46
Little quant	quant	xiaoq	xsc-opus46
Little content	content	xiaocontent	glm5
Little data	data	xiaodata	glm5
Little finance	finance	xiaofinance	glm5
Little research	research	xiaoresearch	glm5
Little market	market	xiaomarket	glm5
Little pm	pm	xiaopm	glm5

Note: quant's accountId is xiaoq(not xiaoquant).

GLM-5 identity override issue

GLM-5 has a built-in "Kiro" persona that overrides the SOUL.md identity. Solution: add at the top of AGENTS.md CRITICAL IDENTITY to force the declaration.

Batch scheduling

for agent_id in ["ops", "code", "quant", "content", "data", "finance", "research", "market", "pm"]:
    sessions_send(
        sessionKey=f"agent:{agent_id}:telegram:group:YOUR_GROUP_CHAT_ID",
        message="你的任务指令"
    )

Trigger words

• "Send a message to Little m"
• "Notify another instance"
• "Cross-machine execution"
• "Sync to remote"
• "inter-agent communication"
• "inter-instance communication"