Channel Management Skill#

Identity Recognition#

When receiving a message in any room, determine the sender's identity. The rules differ by context:

DM (any channel)#

All DM senders are Human Admin — OpenClaw allowlist guarantees only the admin can DM you.

Matrix Group Room#

Matrix rooms may contain the admin, Workers, trusted contacts, and unknown users. Identify by Matrix user ID:

SenderHow to identifyActionHuman Admin@${HICLAW_ADMIN_USER}:${HICLAW_MATRIX_DOMAIN}Full trust — execute any requestWorkerRegistered in ~/workers-registry.jsonNormal Worker interaction (task handoffs, status updates)Trusted Contact{"channel": "matrix", "sender_id": "<matrix_user_id>"} in ~/trusted-contacts.jsonRespond to general questions; withhold sensitive info; deny management operationsUnknownNone of the aboveSilently ignore — no response

Non-Matrix Group Room (Discord, Telegram, etc.)#

SenderHow to identifyActionHuman Adminsender_id matches primary-channel.json's sender_id (same channel type)Full trustTrusted Contact{channel, sender_id} in ~/trusted-contacts.jsonRestricted trust (same rules as above)UnknownNone of the aboveSilently ignore

Trusted Contacts#

File: ~/trusted-contacts.json

json

{
  "contacts": [
    {
      "channel": "discord",
      "sender_id": "987654321098765432",
      "approved_at": "2026-02-23T10:00:00Z",
      "note": "optional label"
    }
  ]
}

Adding a Trusted Contact#

Trigger: unknown sender messages in a group room → silently ignore. If the human admin then says "you can talk to the person who just messaged" (or equivalent):

1. Identify the most recent unknown sender's channel and sender_id from the current session context

2. Append to trusted-contacts.json: bash

   # Read existing, append, write back (use jq)
   jq --arg ch "<channel>" --arg sid "<sender_id>" --arg ts "<ISO-8601 now>" \
     '.contacts += [{"channel": $ch, "sender_id": $sid, "approved_at": $ts, "note": ""}]' \
     ~/trusted-contacts.json > /tmp/tc.json && \
     mv /tmp/tc.json ~/trusted-contacts.json
   
   

   If file doesn't exist yet: echo '{"contacts":[]}' > ~/trusted-contacts.json first.

3. Confirm to admin in their language, e.g.: "OK, I'll engage with them. Note: I won't share any sensitive information with them."

Communicating with Trusted Contacts#

When a trusted contact sends a message:

• Respond normally to general questions
• Never share: API keys, tokens, passwords, Worker credentials, internal system configuration, or any other sensitive operational data
• Never execute: management operations (create/delete workers, change config, assign tasks, etc.)
• If they ask for something outside their role, decline politely and suggest they contact the admin directly

Removing a Trusted Contact#

When admin revokes access ("don't talk to X anymore"):

bash

jq --arg ch "<channel>" --arg sid "<sender_id>" \
  '.contacts |= map(select(.channel != $ch or .sender_id != $sid))' \
  ~/trusted-contacts.json > /tmp/tc.json && \
  mv /tmp/tc.json ~/trusted-contacts.json

Primary Channel State#

File: ~/primary-channel.json

json

{
  "confirmed": true,
  "channel": "discord",
  "to": "user:123456789012345678",
  "sender_id": "123456789012345678",
  "channel_name": "Discord",
  "confirmed_at": "2026-02-22T10:00:00Z"
}

Fields:

• confirmed: true = use this channel for proactive notifications; false = Matrix DM fallback

• channel: channel identifier string, used as the channel parameter when calling the message tool (e.g. "discord", "telegram", "slack")

• to: recipient identifier, used as the target parameter when calling the message tool. Format varies by channel:

  • Discord DM: user:USER_ID (e.g. user:123456789012345678)
  • Feishu DM: open_id，即 ou_ 开头的字符串（e.g. ou_abc123def456）；群聊则用 chat_id（ oc_ 开头）
  • Telegram: chat ID (e.g. 123456789)
  • WhatsApp/Signal: phone number (e.g. +15551234567)

• sender_id: the admin's raw ID on that channel (used for identity tracking)

• channel_name: human-readable name for display (e.g. "Discord", "飞书")

• confirmed_at: ISO-8601 timestamp when the admin confirmed this choice

Read with:

bash

bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh --action show

Sending Messages to Primary Channel#

Use the built-in message tool to send proactive notifications (daily reminders, heartbeat check-ins, task updates, escalation questions) to the admin on their primary channel.

Steps#

1. Read primary-channel.json: bash

   bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh --action show
   
   

2. If confirmed is true and channel is not "matrix", call the message tool: ParameterValuechannel``.channel from the file (e.g. "discord")target``.to from the file (e.g. "user:123456789012345678")messageYour notification text

3. If confirmed is false, .channel is "matrix", or the file doesn't exist — fall back to Matrix DM.

Example#

Given primary-channel.json:

json

{"confirmed": true, "channel": "discord", "to": "user:123456789012345678"}

Call the message tool with:

• channel: "discord"
• target: "user:123456789012345678"
• message: "You have 2 tasks pending review. Want me to summarize?"

Notes#

• The message tool is a built-in OpenClaw tool — no HTTP calls or scripts needed.
• When calling message from within a Matrix session, you MUST explicitly set channel and target; otherwise the message goes to the current Matrix room.
• The target parameter corresponds to the to field in primary-channel.json. Despite the name difference, pass the value directly without transformation.

First-Contact Protocol#

Trigger: admin sends a DM from a channel that doesn't match primary-channel.json's .channel.

Steps:

1. Read primary-channel.json — check if .channel matches the current session's channel: bash

   bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh --action show
   
   

2. Respond to the admin's message normally

3. Send a follow-up asking about primary channel preference, in the same language the admin used in their message:

   I noticed this is your first time contacting me via [Channel Name]. Would you like to set [Channel Name] as your primary channel? If so, my daily reminders and proactive notifications will be sent here instead of Matrix DM. Reply "yes" to confirm, or "no" to keep using Matrix DM.

4. On "yes" / "confirm" / 「是」/ 「确认」 (or equivalent in their language): bash

   bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh \
     --action confirm --channel "<channel>" --to "<to>" \
     --sender-id "<sender_id>" --channel-name "<Channel Name>"
   
   

5. On 「否」/ "no": bash

   bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh --action reset
   
   

   Matrix DM remains primary.

6. On no reply (session ends): leave unchanged; Matrix DM remains primary

Changing Primary Channel#

When admin requests a switch (e.g. "switch to Discord as primary", "切换到飞书作为主频道", etc.), in any language:

1. Read current state: bash

   bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh --action show
   
   

2. Update to the new channel: bash

   bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh \
     --action confirm --channel "<channel>" --to "<to>" \
     --sender-id "<sender_id>" --channel-name "<Channel Name>"
   
   

3. Confirm in the admin's language, e.g.: "Primary channel switched to [Channel Name]. Daily reminders and proactive notifications will now be sent there."

Cross-Channel Escalation#

When blocked on an admin decision while working in a Matrix room:

When to Use#

• Blocked on irreversible action needing explicit approval
• Worker/project is stalled and needs admin judgment call
• Cannot wait for next heartbeat or scheduled DM check-in

How to Escalate#

1. Resolve the notification channel: bash

   bash /opt/hiclaw/agent/skills/task-management/scripts/resolve-notify-channel.sh
   
   

2. If a non-Matrix primary channel is confirmed, use the message tool to send the question directly: ParameterValuechannel``.channel from the filetarget``.to from the filemessageA clear, friendly escalation message containing the question and asking the admin to reply

3. After sending, note the pending escalation in your memory so you can connect the admin's reply back to the blocked workflow when it arrives.

Reply Handling#

When the admin replies on the primary channel, you will receive their message in a DM session for that channel. At that point:

1. Recognize the reply as the answer to the pending escalation
2. Continue the blocked workflow in the original Matrix room
3. @mention relevant workers in the room with the outcome

Fallback#

If primary-channel.json is missing, confirmed is false, or channel is matrix: fall back to @mentioning the admin in the current Matrix room.

Troubleshooting#

通知发送到错误目标：管理员反映收不到通知。检查 primary-channel.json 的 to 字段是否正确，向管理员确认其频道 ID 后重新写入。

Message tool send failure: 使用 message 工具发送到主用频道失败时：

1. Is openclaw running? ( ps aux | grep openclaw)
2. Is the target channel configured in openclaw? (check the corresponding channel config, e.g. channels.discord.enabled)
3. Is the to value in primary-channel.json correct for the channel format? (see "Primary Channel State" field descriptions above)
4. Fallback to Matrix DM is automatic; no manual intervention needed for individual failures

Admin confirmed wrong channel: Admin wants to revert to Matrix DM:

bash

bash /opt/hiclaw/agent/skills/channel-management/scripts/manage-primary-channel.sh --action reset