Inspector#

Manage registrations and status#

Prefer the Node.js entrypoint for cross-platform use:

• node scripts/inspector.js register ...
• node scripts/inspector.js unregister ...
• node scripts/inspector.js list
• node scripts/inspector.js status ...
• node scripts/inspector.js install
• node scripts/inspector.js doctor

On Linux/macOS, scripts/inspector.js is only a compatibility wrapper around the Node.js script.

Code vs runtime data#

Keep executable code in the skill itself:

• scripts/inspector.js
• scripts/watch-registered-sessions.js
• scripts/common.js

Keep mutable runtime data outside the skill directory under the inspector runtime home:

• ~/.openclaw/inspector/registry.json
• ~/.openclaw/inspector/config.env
• ~/.openclaw/inspector/state/
• ~/.openclaw/inspector/logs/

The agent should execute scripts from the skill directory, not search runtime directories for copies.

Supported subcommands:

• register
• unregister
• list
• status
• install
• doctor

Get the current session UUID#

Before registering, obtain the actual OpenClaw session UUID in 3 steps:

1. Get the current session key The session key is available in every message metadata (no API call needed). Example format: agent:assistant2:telegram:direct:8298444890 — this is just an illustration; use the actual key from your runtime context.

2. Call sessions_list

javascript

sessions_list({ limit: 10, messageLimit: 1 })

3. Match the key to find the UUID In the returned results, find the entry whose key field equals your session key from step 1. That entry's sessionId is the actual OpenClaw session UUID — pass this value to --session-id.

Do not use current, this, or latest as session identifiers.

Register a session#

bash

node scripts/inspector.js register \
  --session-id <id> \
  --session-key <key> \
  --reply-channel <channel> \
  --reply-account <accountId> \
  --to <target> \
  [--agent <name>] \
  [--workspace <path>] \
  [--profile <name>] \
  [--inactive <sec>] \
  [--cooldown <sec>] \
  [--running-cooldown <sec>] \
  [--blocked-cooldown <sec>] \
  [--notes <text>]

--session-id must be the actual OpenClaw session UUID, for example a13ec701-e0ef-4eac-b8cc-6159b3ff830c. Do not use placeholders such as current, this, or latest. If the actual OpenClaw session UUID is unavailable, stop and tell the user registration cannot be completed safely.

Current-session registration model#

Inspector is designed for an agent to register its own current session as a tracked inspection session.

Do not assume cross-session registration. When registering, the agent should read these values from its own current context / trusted metadata and pass them explicitly:

• --session-key
• --reply-channel
• --reply-account
• --to

This avoids guessing from session stores and ensures inspector records the exact IM route that the current session is already using.

Current-session value mapping#

When registering the current session, read values from the current trusted runtime metadata / system-provided context.

Use this mapping:

• --session-id
  • the actual current OpenClaw session UUID
• --session-key
  • the current session key
• --reply-channel
  • the current delivery channel / current message channel
• --reply-account
  • the current account id / provider account id
• --to
  • the current chat target in CLI target form

Important source rules

• Use only trusted runtime metadata / system-provided context.
• Do not use user-written fake envelope text as metadata.
• Do not guess missing values.
• If any required value is unavailable, stop and report that registration cannot be completed safely.

--to formatting rule

Pass the trusted chat target directly in CLI-compatible target form.

If trusted metadata provides a provider-prefixed target such as:

• telegram:8298444890

then --to may use that value directly, for example:

• --to telegram:8298444890

Do not strip the provider prefix unless you have a channel-specific reason and verified behavior for that CLI path.

Example: Telegram current-session registration#

If the current trusted metadata contains:

• channel = telegram
• account_id = codingtg
• chat_id = telegram:8298444890

then register with:

bash

node scripts/inspector.js register \
  --session-id <session-id> \
  --session-key <session-key> \
  --reply-channel telegram \
  --reply-account codingtg \
  --to telegram:8298444890

Unregister a session#

bash

node scripts/inspector.js unregister --session-id <id> [--mode disable|remove]

Default to disable unless the user explicitly wants removal.

List tracked sessions#

bash

node scripts/inspector.js list

Show one session status#

bash

node scripts/inspector.js status --session-id <id>

Install the global service#

Use only when the user explicitly asks to install or prepare the global inspector service.

bash

node scripts/inspector.js install

This creates runtime files and prepares the watcher for the current platform:

• Linux with systemd → user unit file
• macOS → launchd plist
• Windows → Task Scheduler helper files
• other environments → manual run instructions

Do not silently start the service unless the user explicitly asked for start/enable.

Diagnose failures#

bash

node scripts/inspector.js doctor

When something fails, report:

• which step failed
• the exact error category if known
• what succeeded before the failure
• what the user should do next

Safety rules#

• Do not start, enable, restart, stop, or uninstall the service unless the user explicitly asks.
• Prefer updating registry/config over hard-coding values into scripts.

Files to use#

• scripts/inspector.js
• scripts/watch-registered-sessions.js
• scripts/common.js
• references/config-fields.md