Neura Market Logo

Repository Scripts: Purpose, Scope, and Safety Notes

This page covers utility scripts for local development and operational tasks, including conventions for use and an optional auth monitoring system. It is intended for developers and operators managing Claude Code CLI subscriptions.

Read this when

  • Running scripts from the repo
  • Adding or changing scripts under ./scripts

scripts/ contains utility scripts for local development workflows and operational tasks. Reach for these when a job is directly associated with a script; otherwise, the CLI is the recommended tool.

Conventions

  • Scripts are not mandatory unless documentation or release checklists mention them.
  • Where CLI commands exist, use them first (for instance, openclaw models status --check).
  • Scripts may behave differently per machine; always review them before execution on an unfamiliar host.

Auth monitoring scripts

General model authentication is explained in Authentication. The following scripts form an independent, optional mechanism for tracking a Claude Code CLI subscription token on a remote or headless machine and refreshing it from a mobile device:

  • scripts/setup-auth-system.sh performs a one-time setup: it inspects current authentication, assists in generating a persistent claude setup-token, and displays installation steps for systemd and Termux.
  • scripts/claude-auth-status.sh [full|json|simple] verifies the authentication status of both Claude Code and OpenClaw.
  • scripts/auth-monitor.sh periodically checks the token status and, when expiration is near, dispatches a notification through OpenClaw send or ntfy.sh. Configured via WARN_HOURS (default 2), NOTIFY_PHONE, and NOTIFY_NTFY. Schedule it with the included scripts/systemd/openclaw-auth-monitor.{service,timer} (runs every 30 minutes).
  • scripts/mobile-reauth.sh executes claude setup-token again and outputs URLs that can be opened on a phone, intended for use over SSH from Termux.
  • scripts/termux-quick-auth.sh, scripts/termux-auth-widget.sh, and scripts/termux-sync-widget.sh are Termux:Widget scripts that connect via SSH to the host, display a status toast, and launch the re-authentication console or instructions once auth has expired.

GitHub read helper

Run scripts/gh-read when you need gh to employ a GitHub App installation token for read-only repo access, while keeping your personal login's normal gh for write operations.

Required environment variables:

  • OPENCLAW_GH_READ_APP_ID
  • OPENCLAW_GH_READ_PRIVATE_KEY_FILE

Optional environment variables:

  • OPENCLAW_GH_READ_INSTALLATION_ID to bypass repo-based installation lookup
  • OPENCLAW_GH_READ_PERMISSIONS a comma-separated override specifying which read permissions to request

Resolution order for repositories:

  • gh ... -R owner/repo
  • GH_REPO
  • git remote origin

Examples:

  • scripts/gh-read pr view 123
  • scripts/gh-read run list -R openclaw/openclaw
  • scripts/gh-read api repos/openclaw/openclaw/pulls/123

When adding scripts

  • Keep scripts concise and well documented.
  • Add a brief note to the appropriate document, or create one if none exists.