Clawkeeper

Use this skill only for the Clawkeeper workspace. Treat

clawkeeper-watcher

as the product center and

clawkeeper

as the launcher that prepares mode-specific runtime state.

Core mental model

• plugins/clawkeeper-watcher/

  is the watcher plugin and governance engine.

• clawkeeper/

  is the launcher that prepares isolated

  remote

  and

  local

  mode roots, then delegates to OpenClaw.

• plugins/clawkeeper-bands/

  is the user-side bridge for notifications and approvals.

• remote

  is read-only judgment and historical intelligence.

• local

  is trusted audit, hardening, rollback, drift monitoring, and skill guard.
• Both watcher modes expose

  POST /plugins/clawkeeper-watcher/context-judge

  .

Read these files when needed:

• README.md

• plugins/clawkeeper-watcher/README.md

• plugins/clawkeeper-bands/README.md

• clawkeeper/src/cli.ts

Preferred workflow

Follow this order unless the user explicitly narrows the task:

1. Identify whether the user wants install, config, validation, or debugging.
2. Check whether the issue is about the launcher, the watcher plugin, or the bands bridge.
3. Verify the exact mode in play:

   remote

   ,

   local

   , or both.
4. Run the smallest direct validation command first.
5. Only after validation fails, inspect config, logs, bridge wiring, and code paths.

Do not jump straight to speculative fixes.

Install and initialize

For source checkout setup in this repo, use:

pnpm install
cd clawkeeper
npm install
npm run build
npm link
cd ..

Initialize modes with:

clawkeeper init remote
clawkeeper init local
clawkeeper local config set gateway.mode local
clawkeeper status

Important:

• local

  mode expects

  gateway.mode=local

  .
• The launcher stores mode state under

  ~/.clawkeeper/

  by default unless

  --root

  overrides it.
• If the problem is only inside the watcher plugin, do not blame launcher setup until

  clawkeeper status

  or mode launch actually fails.

Validation commands

Use the most direct command for the claimed problem.

Launcher validation

clawkeeper --help
clawkeeper status
clawkeeper init remote
clawkeeper init local

Mode launch validation

clawkeeper remote gateway run
clawkeeper local gateway run

Watcher validation

clawkeeper remote clawkeeper-watcher status
clawkeeper remote clawkeeper-watcher logs
clawkeeper remote clawkeeper-watcher fingerprints
clawkeeper remote clawkeeper-watcher profiles

clawkeeper local clawkeeper-watcher status
clawkeeper local clawkeeper-watcher logs
clawkeeper local clawkeeper-watcher audit
clawkeeper local clawkeeper-watcher harden
clawkeeper local clawkeeper-watcher monitor
clawkeeper local clawkeeper-watcher rollback
clawkeeper local clawkeeper-watcher scan-skill <name-or-path>

Context-judge validation

Confirm that the route is the watcher route, not the bands route:

POST /plugins/clawkeeper-watcher/context-judge

Bridge validation

Install the receiving-side bridge plugin with:

openclaw plugins install --link /path/to/clawkeeper/plugins/clawkeeper-bands

Then verify the local watcher bridge config:

clawkeeper local config set plugins.entries.clawkeeper-watcher.config.notify.userBridge.enabled true
clawkeeper local config set plugins.entries.clawkeeper-watcher.config.notify.userBridge.url http://127.0.0.1:18889
clawkeeper local config set plugins.entries.clawkeeper-watcher.config.notify.userBridge.token <gateway-token>

Debugging order

When debugging, follow this sequence:

1. Confirm the exact failing command.
2. Confirm whether the command is running in

   remote

   or

   local

   .
3. Confirm whether the command is launcher-level or watcher-level.
4. Inspect current config relevant to that failure.
5. Read watcher logs or gateway output.
6. Check bridge endpoint path and token if notifications or approvals are involved.
7. Only then inspect code.

Report the first verified failing boundary, not every possible theory.

Common failure patterns

Local command run in remote mode

Symptoms:

• audit

  ,

  harden

  ,

  monitor

  , or

  rollback

  rejected
• output says the command is only available in local mode

Fix:

• rerun on the local instance
• verify

  CLAWKEEPER_MODE

  or config mode if behavior is unexpected

gateway.mode

mismatch

Symptoms:

• local launch behaves like plain or wrong mode
• local-only watcher behavior does not appear

Fix:

• set

  clawkeeper local config set gateway.mode local

• restart the local mode process

Wrong route when testing context judgment

Symptoms:

• request sent to bands instead of watcher
• remote judgment appears missing

Fix:

• use

  POST /plugins/clawkeeper-watcher/context-judge

  for watcher judgment
• use

  clawkeeper-bands

  only for the receiving-side bridge and approval surface

Bridge configured but notifications do not arrive

Symptoms:

• startup audit or approval summary never reaches user-side gateway

Check:

• bridge

  enabled

• bridge

  url

• bridge

  token

• receiving gateway has

  clawkeeper-bands

  installed
• user-side receiver path exists and gateway is reachable

Logs exist but the wrong file is inspected

Symptoms:

• "no events" while watcher is active

Check:

• today vs explicit

  --date

• current mode and workspace
• whether the command is reading watcher event logs or launcher stdout

Use:

clawkeeper local clawkeeper-watcher log-path
clawkeeper local clawkeeper-watcher logs --all
clawkeeper local clawkeeper-watcher logs --date YYYY-MM-DD

Audit result interpreted as host hardening

Symptoms:

• user expects firewall, SSH, or OS policy changes

Clarify:

• Clawkeeper watcher audits and hardens OpenClaw-side runtime state
• it does not automatically perform generic host OS hardening

Command accuracy guardrails

Do not invent flags or routes. Prefer commands already documented in:

• README.md

• plugins/clawkeeper-watcher/README.md

• clawkeeper/src/cli.ts

Current launcher surface:

• clawkeeper init <mode>

• clawkeeper status

• clawkeeper remote ...

• clawkeeper local ...

Current watcher CLI surface includes:

• audit

• harden

• monitor

• rollback

• status

• logs

• log-path

• scan-skill

• fingerprints

• profiles

Response expectations

When using this skill:

• State whether the issue is launcher, watcher, or bridge related.
• State whether it is

  remote

  ,

  local

  , or cross-mode.
• Show the exact command you used to validate the issue.
• Separate verified facts from inference.
• Prefer the narrowest fix that matches the failing boundary.