Matrix - Receiving messages from cron?

[placid ledge]

@final heath I have my agent connected to the matrix network on their own account. Now my big question is: can these ping me?

Think of it like cron or heartbeat fire and I need to have that result from the agent somewhere I can get to it as user...

[cursive atlas]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[final heath]

Yes. If your Matrix channel is configured and the bot account is in a DM/room with you, both heartbeat and cron can deliver there.

For heartbeat, set an explicit Matrix target instead of the default silent target:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "matrix",
        to: "@your-user:example.org"
      }
    }
  }
}

[final heath]

For a Matrix room/alias instead of a DM, use one of the Matrix target forms:

to: "!roomid:example.org"
// or
to: "#room-alias:example.org"

Cron isolated jobs can do the same with announce delivery, e.g.:

openclaw cron add \
  --name "Morning check" \
  --cron "0 8 * * *" \
  --tz "Europe/Berlin" \
  --session isolated \

[final heath]

  --message "Check the thing and summarize anything I need to know." \
  --announce \
  --channel matrix \
  --to "@your-user:example.org"

A couple gotchas:

• Heartbeat default is target: "none", so it may run but not send anything unless you set target/to.
• Matrix invite auto-join defaults to off, so make sure the bot has actually joined the DM/room or configure channels.matrix.autoJoin.
• If you have multiple Matrix accounts, add accountId / the matching cron delivery account so it sends from the right bot account.
• If it doesn’t deliver, first check openclaw --version and openclaw channels status.

Docs: https://docs.openclaw.ai/gateway/heartbeat, https://docs.openclaw.ai/automation/cron-jobs, https://docs.openclaw.ai/channels/matrix

[placid ledge]

Matrix DM messaging works - so I can initiate a session from my end to the agent. It does not look like the agent can initiate it to me.

[final heath]

That distinction is real. Normal Matrix outbound send does not blindly create a brand-new DM from @user:server; it resolves a user target to an existing healthy 1:1 Matrix room. The repair command is the path that can create/repair the direct room mapping.

Since you can message the agent first, try one of these:

openclaw matrix direct inspect --user-id @your-user:server
openclaw matrix direct repair --user-id @your-user:server

Then target that user explicitly from heartbeat/cron:

target: "matrix",
to: "@your-user:server"

or for cron:

[final heath]

--announce --channel matrix --to "@your-user:server"

If you want the most deterministic route, use the Matrix room ID instead of the user ID:

--announce --channel matrix --to "!roomid:server"

Also check two common gotchas:

• if you configured multiple Matrix accounts, set the matching accountId on heartbeat/cron delivery
• isolated cron defaults may use last; for this case I’d avoid last and set --channel matrix --to ... explicitly

Can you share openclaw --version and whether your cron/heartbeat target is using @user:server, user:@user:server, or a !roomid:server?

[placid ledge]

I did not set up any heartbeat or crons yet as my plan was to ask the agent directly to ping me there and they couldn't do it (so there was no point to move forward for me)

[final heath]

Ah, that’s the right thing to test first.

Two separate pieces are involved:

1. Matrix outbound itself
2. The agent being allowed/able to use the shared message tool to initiate that outbound send

Before cron/heartbeat, test Matrix outbound directly from the CLI:

openclaw message send --channel matrix --target "@your-user:server" --message "test from OpenClaw"

If you use a named Matrix account:

[final heath]

openclaw message send --channel matrix --account <account-id> --target "@your-user:server" --message "test from OpenClaw"

If that fails with something like no direct room / m.direct missing, run:

openclaw matrix direct inspect --user-id "@your-user:server"
openclaw matrix direct repair --user-id "@your-user:server"

Then retry the openclaw message send.

If the CLI send works but the agent still “can’t”, then the Matrix side is fine and the issue is likely agent tool availability/routing. In that case check your tools.allow includes the message tool or group:messaging, and tell the agent very explicitly: “send a Matrix message to @your-user:server saying test”. If you’re asking for a future ping, the agent still needs a scheduler path: cron/heartbeat/reminder, not just memory.

Docs:
https://docs.openclaw.ai/cli/message

[final heath]

https://docs.openclaw.ai/channels/matrix
https://docs.openclaw.ai/automation/cron-jobs

Also please include openclaw --version if it still fails; there have been enough Matrix/channel changes that version matters here.

[placid ledge]

openclaw message send - that did work. So basically an agent could (ab)use that as well. I'm on v2026.5.22.

[final heath]

Yep. If the agent has access to the shared message tool, it can initiate that same Matrix send path. Your CLI test proves the Matrix side is healthy on v2026.5.22.

The important boundary is tool policy, not Matrix itself:

• message / group:messaging allowed → agent can send outbound messages when it chooses to use the tool.
• message denied or absent from a non-empty tools.allow → agent cannot send that way.
• If you use a restrictive profile like coding, note that it does not include messaging by default.
• tools.profile: "messaging" includes messaging, but is a different profile shape than coding.

Docs: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated and https://docs.openclaw.ai/gateway/configuration-reference#tools

For your use case, the clean setup is usually:

1. keep Matrix outbound working with the exact --target you tested
2. create a cron/heartbeat with explicit channel: matrix + to: "@you:server"
3. only allow message / group:messaging for agents you trust to proactively contact you

That way scheduled pings are deliberate, and random agent sessions don’t get broad “message anyone” power unless you intend that.

[placid ledge]

can we verify the relevant settings? I want the agent to proactively alert me.

[final heath]

Yes. Since openclaw message send --channel matrix ... works, I’d verify these layers in order.

First, confirm the Matrix channel/account is healthy:

openclaw channels status
openclaw matrix direct inspect --user-id "@your-user:server"

If the direct inspect looks stale/missing:

openclaw matrix direct repair --user-id "@your-user:server"

Then verify the agent is allowed to send messages proactively. Check your effective config:

[final heath]

openclaw config get tools
openclaw config get agents

You want either no restrictive tools.allow, or an allowlist/profile that includes message / group:messaging. If tools.allow is non-empty and doesn’t include messaging, the agent won’t be able to use the message tool.

For proactive alerts specifically, configure heartbeat or cron with an explicit Matrix target. Heartbeat example:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "matrix",

[final heath]

        to: "@your-user:server",
        // accountId: "your-matrix-account-id" // only if using named accounts
      }
    }
  }
}

Also make sure heartbeat visibility isn’t suppressing alerts:

openclaw config get channels.defaults.heartbeat
openclaw config get channels.matrix.heartbeat

Defaults should be fine: showAlerts: true, showOk: false. If showAlerts: false, alerts will be suppressed.

[final heath]

For cron, test with a one-shot isolated job:

openclaw cron add \
  --name "Matrix alert test" \
  --at "2m" \
  --session isolated \
  --message "Send a short proactive test alert. Do not reply HEARTBEAT_OK." \
  --announce \
  --channel matrix \
  --to "@your-user:server"

Then inspect:

[final heath]

openclaw cron list
openclaw cron runs --id <job-id>

If you paste redacted output from openclaw config get tools, the heartbeat block, and whether you use named Matrix accounts, I can sanity-check the exact settings.

[placid ledge]

openclaw config get tools

OpenClaw 2026.5.22 (a374c3a)

{
  "profile": "coding",
  "web": {
    "search": {
      "enabled": true,
      "provider": "searxng",
      "openaiCodex": {}
    },
    "fetch": {
      "enabled": false,
      "ssrfPolicy": {
        "allowRfc2544BenchmarkRange": true
      }
    }
  },
  "sessions": {
    "visibility": "all"
  },
  "message": {
    "crossContext": {
      "allowWithinProvider": true,
      "allowAcrossProviders": true
    },
    "broadcast": {
      "enabled": true
    }
  }
}

[final heath]

This confirms the likely missing piece.

You currently have:

tools.profile: "coding"

That profile does not include the message tool. The tools.message.crossContext block only configures message-tool behavior once the tool is available; it does not grant the tool.

Smallest fix while keeping the coding profile:

openclaw config set tools.alsoAllow '["group:messaging"]' --strict-json

or narrower:

[final heath]

openclaw config set tools.alsoAllow '["message"]' --strict-json

Then restart/apply config so the agent session sees the updated tool inventory.

After that, verify:

openclaw config get tools.alsoAllow

For proactive alerts, you still need the scheduler/delivery part. Heartbeat baseline:

{

[final heath]

  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "matrix",
        to: "@your-user:server"
      }
    }
  }
}

If you use a named Matrix account, add accountId there too.

Then check alert visibility:

[final heath]

openclaw config get channels.defaults.heartbeat
openclaw config get channels.matrix.heartbeat

You do not want showAlerts: false. Default is fine if unset.

So: Matrix outbound is good, tool access is currently missing because coding excludes messaging, and heartbeat/cron still needs an explicit Matrix target for proactive alerts.

[placid ledge]

elisabeth@agent:~/.openclaw$ openclaw config get tools.alsoAllow

OpenClaw 2026.5.22 (a374c3a)

[
  "message"
]

This looks good to me.

[final heath]

Yep, that part looks right. tools.profile: "coding" + tools.alsoAllow: ["message"] should expose the message tool without switching the whole agent to a messaging profile.

Next checks:

openclaw config get agents.defaults.heartbeat
openclaw config get channels.defaults.heartbeat
openclaw config get channels.matrix.heartbeat

You want heartbeat to have an explicit Matrix destination, for example:

{
  "every": "30m",
  "target": "matrix",

[final heath]

  "to": "@your-user:server"
}

And you do not want showAlerts: false in either heartbeat visibility block.

After config changes, restart/apply the gateway before testing from the agent session. Then ask the agent something direct like:

Use the message tool to send a Matrix message to @your-user:server saying “proactive alert test”.

If that works, cron/heartbeat is the remaining scheduling piece, not Matrix/tool access.

[placid ledge]

That did it! Thanks!

[final heath]

Glad that fixed it.

For Answer Overflow: please right-click the solution message -> Apps -> ✅ Mark Solution. That helps the next person who hits the same tools.profile: "coding" vs message tool issue find the answer.