Send OpenClaw Notifications to Android
Get a phone alert when an explicitly launched OpenClaw CLI invocation returns.
QuickStart
Needs: Configured OpenClaw CLI + Bash + curl
- Install QueueRing on Android, register the device, allow notifications, and copy the current Queue ID. Keep the phone online.
- Store the ID, create two scripts, select an agent
- Verify on your device
Queue ID grants permission to send: keep it secret. If leaked, reissue it in the app and update your configuration. Security details.
202 only means accepted; display, history, and ID validity are not guaranteed. Resends can duplicate alerts; retry the notification only, never the job or agent. HTTP errors and retry advice.
1. Store your Queue ID once
install -d -m 700 "$HOME/.config/queuering"
(
set +x
umask 077
read -r -s -p 'Paste the Queue ID from your Android app: ' QUEUE_ID
printf '\n'
[[ "$QUEUE_ID" =~ ^qr1\.[A-Za-z0-9_-]{1,16}\.[A-Za-z0-9_-]{59}$ ]] || exit 1
printf '%s\n' "$QUEUE_ID" > "$HOME/.config/queuering/queue-id"
chmod 600 "$HOME/.config/queuering/queue-id"
)Copy buttons copy code only. If unavailable, select the code and copy manually. Code messages are shared with the English examples.
Paste this into Bash on the sending machine. Enter the ID at the hidden prompt; it is stored outside your repository with restricted permissions.
2. Create the sender and wrapper
The setup creates notify-android.sh and notify-openclaw.sh in $HOME/.local/bin. Check openclaw agent --help, then enter an existing configured agent ID when running the command below.
Paste into Bash. It creates the two named files only when both names are unused. If either exists at the initial check, setup stops before writing either file. Review the existing scripts: use them only if they match this recipe, or choose unused names and update every corresponding path in setup (including the embedded wrapper) and run commands. Do not delete custom scripts just to retry. The sender handles HTTP, while the wrapper preserves the main command's exit code. Missing or unreadable ID configuration skips only the notification.
(
set -eu
umask 077
for file in "$HOME/.local/bin/notify-android.sh" "$HOME/.local/bin/notify-openclaw.sh"; do
if [[ -e "$file" || -L "$file" ]]; then
printf 'Setup stopped: %s already exists. Existing files were kept. Review them before continuing.\n' "$file" >&2
exit 1
fi
done
install -d -m 700 "$HOME/.local/bin"
set -C
cat > "$HOME/.local/bin/notify-android.sh" <<'QUEUERING_SENDER'
#!/usr/bin/env bash
set +x
set -eu
set +x
: "${QUEUE_ID:?Load your Queue ID before sending}"
[[ "$QUEUE_ID" =~ ^qr1\.[A-Za-z0-9_-]{1,16}\.[A-Za-z0-9_-]{59}$ ]] || {
printf 'Invalid Queue ID format; copy it from the app.\n' >&2
exit 1
}
: "${1:?Pass a short notification message}"
message=$1
status=$(curl --silent --connect-timeout 10 --max-time 30 \
--output /dev/null --dump-header /dev/stderr --write-out '%{http_code}' \
--request POST "https://api.queuering.org/q/$QUEUE_ID" \
--header 'Content-Type: text/plain; charset=utf-8' \
--data-binary "$message") || {
printf 'Notification transport failed; check connectivity.\n' >&2
exit 1
}
printf 'Notification HTTP %s\n' "$status" >&2
[[ "$status" == 202 ]]
QUEUERING_SENDER
cat > "$HOME/.local/bin/notify-openclaw.sh" <<'QUEUERING_WRAPPER'
#!/usr/bin/env bash
set +x
set -eu
unset QUEUE_ID
: "${OPENCLAW_AGENT:?Set an existing configured OpenClaw agent ID}"
result=0
openclaw agent --agent "$OPENCLAW_AGENT" \
--message 'Reply with a short readiness check. Do not modify files or call external services.' \
|| result=$?
if ! IFS= read -r QUEUE_ID < "$HOME/.config/queuering/queue-id"; then
printf 'Notification skipped: cannot read Queue ID configuration.\n' >&2
elif ! QUEUE_ID="$QUEUE_ID" bash "$HOME/.local/bin/notify-android.sh" "OpenClaw CLI finished (exit $result)"; then
printf 'Notification failed; the CLI exit code is preserved.\n' >&2
fi
exit "$result"
QUEUERING_WRAPPER
)3. Run the test
Continue only after setup succeeds, or after you have checked that the existing scripts match this recipe.
read -r -p 'Existing OpenClaw agent ID: ' OPENCLAW_AGENT
export OPENCLAW_AGENT
bash "$HOME/.local/bin/notify-openclaw.sh"
echo $?Verify on your device
Check the CLI output locally, the HTTP response, and the Android message OpenClaw CLI finished (exit 0) for a successful invocation. This reports the CLI exit status, not proof that the agent achieved a business task. A timeout or lost connection can leave remote work running; inspect the Gateway/session before rerunning the agent. Do not automatically retry agent execution to resend an alert.
If HTTP 202 arrives without a phone alert, verify the current Queue ID, Android notification permission, and device connectivity first. Check the app's recent history as an additional observation, not a delivery receipt.
More examples and integration limits
Integration steps and limits
Bash, curl, and a working OpenClaw CLI with a configured agent and provider or Gateway. Set OPENCLAW_AGENT to an existing agent ID from your configuration.
This is a shell integration based on the official OpenClaw agent CLI. It sends only a fixed status message, not prompts, transcripts, or model output. It does not subscribe to arbitrary background agent events. Keep the private Queue ID outside the agent workspace and sandbox mounts; do not give it to the model. The documented command path has been checked; a live OpenClaw installation and Android delivery have not been tested here.
Queue ID security details
Keep the Queue ID private
A Queue ID grants permission to send notifications to your device: treat it as a bearer credential. Never put a real ID in public repositories, Issues, logs, screenshots, prompts, or fixed sample values. Do not use shell tracing (set -x), curl verbose/trace output, or shared terminal recordings. The URL and process arguments can contain the ID; run only on a trusted machine and restrict proxy/access logs.
If exposed, reissue/rotate the Queue ID in the app and replace every local configuration or Actions secret using the old ID. Copy the new value from the app rather than editing the old one. A 202 response cannot confirm that an old ID remains valid.
API contract, HTTP errors, and retries
Understand the response and retry safely
Notifications and message history are best-effort. HTTP 202 means request acceptance, not guaranteed display on Android or guaranteed history storage. Invalid, inactive, and outdated Queue IDs intentionally receive the same 202 response. History stores up to 100 messages captured on the device; absence from history alone does not establish an HTTP failure.
The endpoint is POST https://api.queuering.org/q/{queueId}. Use UTF-8 text/plain; charset=utf-8, or application/json with a required nonempty body string and optional nonblank title. The raw request body, including JSON syntax, must be at most 4096 bytes.
| Result | What to do |
|---|---|
| 202 | Check Android notification permissions, connectivity, and the current ID in the app. Do not retry merely because no notification appears. |
| 400 | Fix the request, Content-Type, JSON syntax, and required fields before resending. |
| 413 | Shorten the UTF-8 body to 4096 bytes or less; JSON escaping also counts. |
| 429 | Wait at least Retry-After seconds when provided. If absent, use a delayed bounded retry with backoff rather than a tight loop. |
| 503 | Temporarily unavailable. Inspect the failure and retry later with bounded backoff. |
| Transport failure / timeout | The outcome may be unknown. Check connectivity before deciding to resend. |
The samples send once, with a 10-second connect timeout and 30-second total timeout. They print HTTP status and response headers (including Retry-After), and do not automatically retry. Resending can create duplicate alerts; there is no idempotency key in these examples. Retry the notification only, never rerun a backup, deployment, or agent just to send its status. Keep your normal job logs and monitoring as the source of truth.