Dr. Claw

Dr. Claw is a tiny Telegram-first break-glass recovery bot for your own machine.

It is deliberately narrow:

• manual recovery commands only
• no auto-heal loops
• no open-ended chat control surface
• local config, local process, local allowlist

If your main agent stack is down and you need a phone-accessible path to check status, tail logs, or run a pre-approved restart command, this is the tool.

What it does

• long-polls Telegram with a bot token you control
• allowlists specific Telegram user IDs
• requires a shared setup token for protected commands
• ships with built-in openclaw and nanoclaw command profiles
• keeps dangerous actions disabled by default
• writes local diagnostics bundles to .bundle/
• includes first-run CLI setup and self-test commands

Supported profiles

openclaw

Default commands:

• status → openclaw gateway status
• logs → tails ~/.openclaw/logs/*.log
• restart_gateway → openclaw gateway restart
• restart_agent → attempts pkill -f "openclaw.*agent"
• ping → echo pong

nanoclaw

Default commands:

• status → searches process list for nanoclaw
• logs → tails ~/.nanoclaw/logs/*.log
• restart_gateway → placeholder message by default
• restart_agent → attempts pkill -f nanoclaw
• ping → echo pong

custom

Use this if you want to provide your own COMMAND_ALLOWLIST_JSON entirely.

Install

Use it without installing globally:

npx @stratuslabs/doctor@beta help

Or install the beta CLI globally:

npm install -g @stratuslabs/doctor@beta
doctor help

Quickstart

From a local clone:

npm install
npm run build
npm run start -- setup

The setup command asks for:

• profile (openclaw, nanoclaw, or custom)
• Telegram bot token
• allowed Telegram user IDs
• shared setup token for protected commands

It writes a usable local .env file you can review immediately.

Non-interactive setup

doctor setup \
  --non-interactive \
  --profile openclaw \
  --bot-token 123456:abc \
  --allowed-users 123456789 \
  --setup-token replace-me

Validate your local config

doctor self-test

This validates the env file, resolves the active profile, and prints the exact command allowlist Dr. Claw would use. It does not contact Telegram and it does not run recovery commands.

Start the bot

doctor

Telegram command surface

From Telegram chat with your bot:

• /help
• /ping
• /status <token>
• /logs <token>
• /bundle <token>
• /restart_gateway <token>
• /restart_agent <token>

Protected commands require the shared setup token. Restart commands also require ENABLE_DANGEROUS_ACTIONS=true in your local config.

Local testing on your own machine

Recommended flow:

npm install
npm run build
npm run start -- setup --non-interactive --profile openclaw --bot-token 123:abc --allowed-users 123456789 --setup-token dev-secret
npm run start -- self-test
npm run check

If you want to exercise the help surface without a real bot token yet:

doctor help
doctor setup --help
doctor self-test --config-file .env

Once you have a real Telegram bot token, start Dr. Claw locally and message the bot from an allowlisted Telegram account.

Safety model

Dr. Claw is for break-glass recovery, not routine remote administration.

Included safeguards:

• Telegram user allowlist
• setup token for protected commands
• dangerous commands off by default
• only configured allowlisted shell commands may run
• subprocess timeout and output size limit

Important limits:

• no MFA or challenge-response flow yet
• no audit log persistence yet
• no sandbox around configured shell commands
• if the host or bot token is compromised, this can become a recovery backdoor

Review the generated .env file before first use.

CLI reference

doctor                 # start Telegram polling
doctor setup           # interactive first-run setup
doctor self-test       # validate local config
doctor help            # show CLI help
npx @stratuslabs/doctor@beta help

Project layout

• src/index.ts - CLI entrypoint and polling loop
• src/cli.ts - setup and self-test UX
• src/config.ts - profile defaults and config loading
• src/telegram.ts - minimal Telegram Bot API client
• src/command-parser.ts - Telegram command surface
• src/auth.ts - allowlist and setup-token checks
• src/action-runner.ts - allowlisted shell execution
• src/diagnostics.ts - local diagnostics bundles
• src/handlers.ts - Telegram command dispatch
• tests/*.test.ts - auth, config, and CLI coverage

Publishing the beta

npm run check
npm pack --dry-run
npm publish --tag beta --access public

The published package name is @stratuslabs/doctor, and the installed executable is doctor.

Caveats

• Built-in restart commands are sensible defaults, not universal truth. Review them for your machine.
• restart_gateway for nanoclaw is intentionally conservative and does nothing dangerous by default.
• Telegram bot messages have practical length limits, so large outputs are truncated.
• This is a local recovery utility, not a hardened remote administration product.