openclaw-route-check

openclaw-route-check is a small static-analysis CLI for checking where OpenClaw messages, cron jobs, and announce deliveries are expected to route before you rely on them in production.

It focuses only on delivery and routing correctness. It does not send test messages.

Install

pipx install openclaw-route-check

For local development:

uv sync
uv run openclaw-route-check --help
uv run pytest

Examples

openclaw-route-check --job 429c62e0-2b1f-4179-bac3-792f405d09ae
openclaw-route-check --session agent:main:telegram:group:-1003710118964
openclaw-route-check --all-crons --markdown
openclaw-route-check --announce fixtures/announce.json --json
openclaw-route-check --channel telegram --target -1003710118964 --thread 77

By default, --job and --all-crons read ./jobs.json. Use --jobs path/to/jobs.json to point at another file.

What Is Checked

The checker resolves and reports:

• resolved channel
• resolved target or chat
• resolved thread or topic when present
• session target behavior
• routing confidence score
• warnings or errors that are suitable for CI

It detects:

• missing announce target
• mismatched sessionKey and delivery target
• likely thread/topic loss
• cron jobs relying on implicit routing where explicit routing would be safer
• ambiguous channel: last and target: last usage

Supported Inputs

The analyzer intentionally accepts flexible JSON shapes because OpenClaw routing config can appear under different keys. It looks for route fields directly on an object and inside route-like containers such as delivery, announce, route, routing, target, and destination.

Recognized channel-like keys include:

channel, transport, provider, driver, via

Recognized target-like keys include:

target, chat, chat_id, chatId, room, room_id, to, recipient, target_id, targetId, channel_id, channelId

Recognized thread/topic keys include:

thread, thread_id, threadId, topic, topic_id, topicId, message_thread_id, messageThreadId, forum_topic_id, forumTopicId

Session keys are parsed heuristically. A key like this:

agent:main:telegram:group:-1003710118964:topic:77

resolves to:

• channel: telegram
• target/chat: -1003710118964
• thread/topic: 77

Output Formats

Terminal output is optimized for local inspection:

openclaw-route-check --job implicit-nightly --jobs fixtures/jobs.json

JSON output is suitable for CI automation:

openclaw-route-check --all-crons --jobs fixtures/jobs.json --json

Markdown output works well in GitHub Actions step summaries:

openclaw-route-check --all-crons --jobs fixtures/jobs.json --markdown >> "$GITHUB_STEP_SUMMARY"

Use --strict to return a non-zero exit code on warnings as well as errors.

What Cannot Be Proven Statically

Static analysis cannot prove:

• whether an OpenClaw runtime session still exists
• whether last points at the conversation you expect
• whether credentials, bot membership, or permissions allow delivery
• whether Telegram forum topics or similar thread ids are still valid
• whether runtime code mutates routing after config load
• whether an external provider silently remaps channels, chats, or topics

The tool is best used as a preflight check for config shape and obvious routing risks before a production deploy.

Development

uv sync
uv run pytest
uv run openclaw-route-check --all-crons --jobs fixtures/jobs.json

Releases

This repository includes a tag-driven GitHub Actions release workflow. Tags matching v*.*.* build and publish the Python package to PyPI, then update pfrederiksen/homebrew-tap.

Recommended release flow:

git tag v0.1.2
git push origin v0.1.2

PyPI publishing is configured for trusted publishing via GitHub Actions. Do not commit PyPI tokens. Configure the PyPI project to trust this repository and workflow environment.

The Homebrew tap update requires a GitHub secret named HOMEBREW_TAP_TOKEN with permission to push to pfrederiksen/homebrew-tap.