FreeSmsGateway

Send and receive SMS using a local sms-gate.app instance running on Android (via Termux) or a dedicated device. Use when the user needs to send text messages...

Security Scan

The skill mostly does what it says (talk to a local sms-gate.app) but contains undocumented behavior that forwards incoming SMS webhooks to an OpenClaw endpoint by default and uses environment/config files not declared in the manifest — this mismatch could leak sensitive message content if you don't notice it.

Purpose & Capability

Name/description, required binaries (python3), and the included scripts (send, list, status, health, webhook management) are consistent with a local SMS gateway integration. The requested env vars (SMS_GATE_URL, SMS_GATE_USER, SMS_GATE_PASS) are appropriate for this purpose.

Instruction Scope

SKILL.md documents how to run the provided scripts but omits a runtime behavior present in the code: scripts/webhook_server.py will attempt to forward every incoming SMS webhook to an OPENCLAW_WEBHOOK_URL (default http://localhost:8080/webhook) unless that env var is explicitly set to 'disabled'. That forwarding is not documented in SKILL.md and thus is unexpected scope creep — it transmits message payloads to another HTTP endpoint by default.

Install Mechanism

Instruction-only skill with no install spec; included code uses only Python stdlib. No remote downloads, no archive extraction, and no extra packages are pulled in by the skill.

Credentials

Declared env vars (SMS_GATE_URL/USER/PASS) are proportionate. However, the code reads additional environment variables not declared in the manifest/SKILL.md (OPENCLAW_WEBHOOK_URL controls automatic forwarding) and also reads a local .env in the skill root via auth._load_env. The presence of an undeclared forwarding target is the primary proportionality concern because it can cause exfiltration of incoming SMS content to an endpoint the user did not configure in the SKILL.md.

Persistence & Privilege

The skill writes a token cache (.token.json) into the skill root and a last-check state file (~/.sms_gateway_last_check) in the user's home; this is normal for caching but stores sensitive access_token in plaintext JSON. The skill is not always-enabled and does not modify other skills or system-wide settings.

What to consider before installing

This skill appears to implement a legitimate local SMS gateway client, but be aware of hidden forwarding and local files: - The webhook receiver (scripts/webhook_server.py) automatically forwards incoming SMS payloads to OPENCLAW_WEBHOOK_URL, which defaults to http://localhost:8080/webhook unless you set OPENCLAW_WEBHOOK_URL='disabled'. SKILL.md does not document this. Before running the webhook server, explicitly set OPENCLAW_WEBHOOK_URL to 'disabled' (or to a URL you trust) if you do not want incoming message content forwarded. - The skill caches JWT tokens to .token.json in the skill directory and writes ~/.sms_gateway_last_check. These files contain sensitive data (access_token and timestamps). If you install the skill, ensure the skill directory is not world-readable and consider clearing the token file when not needed. - The skill reads a .env file in its root (auth._load_env). Follow the README guidance to create .env, but be aware credentials in .env are used directly; keep that file private. - When configuring webhooks via manage_webhooks.py, avoid registering public/unknown endpoints for sms:received unless you trust them, because message bodies can be delivered to those endpoints. - If you want to proceed: audit or modify scripts/webhook_server.py to change the default OPENCLAW_WEBHOOK_URL to 'disabled' or make forwarding opt-in, and confirm file permissions for .token.json and .env. If you are unsure, run the scripts in a controlled environment (not exposed to the internet) and review outgoing network traffic while testing.

SMS Gateway

Interact with a local sms-gate.app instance to send and receive SMS through an Android device.

Setup

Requires environment variables:

• SMS_GATE_URL — Your gateway URL (e.g., http://192.168.50.69:8080)
• SMS_GATE_USER — HTTP Basic Auth username
• SMS_GATE_PASS — HTTP Basic Auth password

Quick Start

Send an SMS:

python3 scripts/send_sms.py '[phone]' 'Hello from OpenClaw!'

Check delivery status:

python3 scripts/check_status.py 'VdHHQ3nlNwDZ-W9SNuLzm'

List recent messages:

python3 scripts/list_messages.py 20

Operations

Sending SMS

Use scripts/send_sms.py:

python3 scripts/send_sms.py '<phone_number>' '<message>' [delivery_report]

Phone numbers can include + prefix (will be normalized). Delivery report is true by default.

Checking Status

Use scripts/check_status.py with the message ID returned from send:

python3 scripts/check_status.py '<message_id>'

States: Pending → Sent → Delivered (or Failed)

Listing Messages

Use scripts/list_messages.py:

python3 scripts/list_messages.py [limit]

Shows both sent (📤) and received (📥) messages with their current state.

Managing Webhooks

Use scripts/manage_webhooks.py:

# List configured webhooks
python3 scripts/manage_webhooks.py list

# Add webhook for incoming SMS
python3 scripts/manage_webhooks.py add sms:received https://your-server.com/sms

# Add delivery confirmation webhook
python3 scripts/manage_webhooks.py add sms:delivered https://your-server.com/delivered

# Delete webhook
python3 scripts/manage_webhooks.py delete sms:received

API Reference

See references/api.md for complete endpoint documentation.

Common Patterns

Send with status check:

# Send and capture ID
MSG_ID=$(python3 scripts/send_sms.py '[phone]' 'Test' 2>&1 | grep "ID:" | awk '{print $3}')

# Check status after a few seconds
sleep 5
python3 scripts/check_status.py "$MSG_ID"

Health check:

python3 scripts/health.py

Receiving SMS (Incoming)

The sms-gate.app API doesn't store message content - it only delivers via webhooks. To receive incoming SMS:

Option 1: Webhook Server + ngrok (Recommended)

1. Start the webhook receiver:

python3 scripts/webhook_server.py 8787

2. Expose via ngrok:

ngrok http 8787
# Copy the https://xxxx.ngrok-free.app URL

3. Configure webhook:

python3 scripts/manage_webhooks.py add sms:received https://xxxx.ngrok-free.app/sms-received

Now incoming SMS will be printed to the webhook server console.

Option 2: Local Network (Same WiFi)

If Pixel 3 and Mac are on same network:

# Get Mac IP
ipconfig getifaddr en0
# Configure webhook directly (if gateway allows HTTP)
python3 scripts/manage_webhooks.py add sms:received http://<mac-ip>:8787/sms-received

Notes

• The Android device must have SMS capability and be on the same network (or accessible via tunnel like Cloudflare)
• Webhooks require HTTPS for remote access (ngrok provides this)
• Message content is only available via webhooks, not stored in /messages API
• Message IDs are URL-safe strings returned after sending