vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-07-09 15:59:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 22

docs: default agent validation to remote runners (#100220)

Browse source 
* docs: default agent validation to remote runners

* docs: isolate untrusted validation networking

* fix: harden untrusted Crabbox validation

* docs: refresh generated docs map
This commit is contained in:
Peter Steinberger 2026-07-05 02:01:51 -07:00 • committed by GitHub
parent e60c510560
commit b6f4cf5ac4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 510 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

182
.agents/skills/crabbox/SKILL.md
View file

@ -5,9 +5,10 @@ description: Use the Crabbox wrapper for OpenClaw remote validation across Linux
# Crabbox
Use the Crabbox wrapper when OpenClaw needs remote Linux proof for broad tests,
OpenClaw agent sessions use the Crabbox wrapper by default for tests and
computationally intensive work: builds, typechecks, lint fan-out, broad gates,
CI-parity checks, secrets, hosted services, Docker/E2E/package lanes, warmed
reusable boxes, sync timing, logs/results, cache inspection, or lease cleanup.
reusable boxes, sync timing, logs/results, cache inspection, and lease cleanup.
Crabbox is the transport/orchestration surface. The actual backend can be:
@ -16,17 +17,18 @@ Crabbox is the transport/orchestration surface. The actual backend can be:
- Blacksmith Testbox through Crabbox: delegated provider,
`provider=blacksmith-testbox`, ids like `tbx_...`, `syncDelegated=true`
For OpenClaw maintainer broad `pnpm` gates, Blacksmith Testbox through the
Crabbox wrapper is acceptable and often preferred when the standing Testbox
rules apply. Do not describe those runs as "AWS Crabbox"; report them as
Testbox-through-Crabbox with the `tbx_...` id and Actions run.
Blacksmith Testbox through the Crabbox wrapper is the default OpenClaw agent
backend for trusted maintainer code and heavy `pnpm` gates. The configured
Blacksmith workflow hydrates provider and agent credentials, so never sync or
run untrusted contributor/fork code there. Use secretless fork CI or
sanitized direct AWS Crabbox for untrusted source. Do not describe
Blacksmith runs as "AWS Crabbox"; report them as Testbox-through-Crabbox with
the `tbx_...` id and Actions run.
Use the repo `.crabbox.yaml` brokered AWS path when the task specifically needs
direct AWS Crabbox behavior, persistent direct-provider leases, `--fresh-pr`,
`--full-resync`, environment forwarding, capture/download support, or provider
comparison. Use `--provider blacksmith-testbox` when the task needs OpenClaw
maintainer Testbox proof, prepared CI environment, broad/heavy pnpm gates, or
the user asks for Testbox/Blacksmith.
Pass `--provider aws` when the task specifically needs direct AWS Crabbox
behavior, persistent direct-provider leases, `--fresh-pr`, `--full-resync`,
environment forwarding, capture/download support, or provider comparison. Use
`--provider blacksmith-testbox` for the default OpenClaw agent path.
## First Checks
@ -51,16 +53,85 @@ pnpm crabbox:run -- --help | sed -n '1,120p'
config pins hot `eu-west-1a/b/c` placement so Fast Snapshot Restore can apply.
If warmup drifts well past the minute-scale path, verify image promotion,
region/AZ placement, and FSR state before blaming OpenClaw.
- For broad OpenClaw maintainer `pnpm` gates, prefer the repo wrapper with
`--provider blacksmith-testbox` or the repo Testbox helpers when the standing
Testbox policy applies.
- Cold Testbox acquisition and hydration often take tens of seconds. When broad
remote proof is likely, immediately start
- For trusted OpenClaw agent tests and computationally intensive work, use the
repo wrapper with `--provider blacksmith-testbox` or the repo Testbox helpers.
- Treat contributor/fork source as untrusted unless a maintainer explicitly
approves credentialed execution after review. Run untrusted source only in
secretless fork CI or sanitized direct AWS Crabbox. For every untrusted AWS
run, launch an installed trusted Crabbox binary from a clean trusted `main`
checkout and fetch the remote PR with `--fresh-pr`; never execute the
untrusted checkout's wrapper or config locally. Set
`CRABBOX_ENV_ALLOW=CI` to replace the repo's `OPENCLAW_*`/`NODE_OPTIONS`
allowlist, pass `--provider aws --no-hydrate`, and use a fresh temporary
remote `HOME` on a newly warmed lease dedicated to that untrusted source.
Unset `CRABBOX_AWS_INSTANCE_PROFILE` and fail closed unless resolved
`aws.instanceProfile` is empty. Before install/test, use trusted absolute-path
tools to require an IMDSv2 token, prove the IAM credentials endpoint returns
404, and verify remote `git rev-parse HEAD` equals the full reviewed PR head
SHA. Bind the lease to that SHA; stop and rewarm when the head changes. Do not
inherit Tailscale: unset every `CRABBOX_TAILSCALE*` override, force
`--network public --tailscale=false`, clear exit-node/LAN flags, and require
`crabbox inspect` to report public networking with no Tailscale state before
uploading any script. Execute PR code only through trusted
`scripts/crabbox-untrusted-bootstrap.sh`, uploaded from clean `main` alongside
`--fresh-pr`; it installs pinned Node/pnpm and rejects a changed PR
`packageManager` pin before install. Never reuse a trusted or previously
hydrated lease. If the broker cannot provide
the no-role proof or no remote PR exists, use secretless fork CI. Never use
`hydrate-github` or a credential-hydrated Testbox workflow for untrusted code.
- Cold Testbox acquisition and hydration often take about a minute. At the
start of any task likely to change code or need tests/heavy proof, immediately
start, after confirming the source is trusted,
`node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json`
in a background command session while inspecting, editing, and running
focused local tests. Poll later, reuse the returned `tbx_...` with
in a background command session while inspecting and editing. Poll later,
reuse the returned `tbx_...` with
`--provider blacksmith-testbox --id <tbx_id>`, and stop it before handoff.
Do not warm speculatively when remote proof is unlikely.
For untrusted source, switch to a clean trusted `main` checkout and pre-warm
with the installed binary after the empty-instance-profile check below.
Do not warm for read-only, docs-only, or clearly trivial work that will not
run tests or heavy commands.
- Run untrusted source only with the sanitized form below. The explicit
allowlist prevents locally exported `OPENCLAW_*` credentials from crossing
the SSH boundary; `--no-hydrate` and temporary `HOME` prevent auth-profile
reuse:
```sh
env -u CRABBOX_AWS_INSTANCE_PROFILE \
crabbox config show --json | \
jq -e '.aws.instanceProfile == ""' >/dev/null
env -u CRABBOX_AWS_INSTANCE_PROFILE \
-u CRABBOX_TAILSCALE \
-u CRABBOX_TAILSCALE_AUTH_KEY \
-u CRABBOX_TAILSCALE_AUTH_KEY_ENV \
-u CRABBOX_TAILSCALE_EXIT_NODE \
-u CRABBOX_TAILSCALE_EXIT_NODE_ALLOW_LAN_ACCESS \
-u CRABBOX_TAILSCALE_HOSTNAME_TEMPLATE \
-u CRABBOX_TAILSCALE_TAGS \
crabbox warmup \
--provider aws \
--network public \
--tailscale=false \
--tailscale-exit-node= \
--tailscale-exit-node-allow-lan-access=false \
--keep \
--timing-json
crabbox inspect --provider aws --id <cbx_id> --json | \
jq -e '.network == "public" and .tailscale == null' >/dev/null
env -u CRABBOX_AWS_INSTANCE_PROFILE \
CRABBOX_ENV_ALLOW=CI \
crabbox run \
--provider aws \
--id <cbx_id> \
--fresh-pr <owner/repo#number> \
--no-hydrate \
--timing-json \
--script scripts/crabbox-untrusted-bootstrap.sh -- \
<expected_head_sha> /usr/local/bin/pnpm test <path>
# After all proof:
env -u CRABBOX_AWS_INSTANCE_PROFILE \
crabbox stop --provider aws <cbx_id>
```
- Always report the actual provider and id. `cbx_...` means AWS Crabbox;
`tbx_...` means Blacksmith Testbox through Crabbox. If the output only says
`blacksmith testbox list`, use `blacksmith testbox list --all` before
@ -75,15 +146,17 @@ pnpm crabbox:run -- --help | sed -n '1,120p'
not leave it in remote shell history or logs. If no secret-safe injection path
is available, say true live provider auth is blocked instead of silently using
a fake key.
- Prefer local targeted tests for tight edit loops. Broad gates belong remote.
- Agent-run tests, including targeted edit-loop tests, default to a pre-warmed
remote box selected by source trust. Local test execution requires an
explicit user request or a reported remote-provider blocker.
- Do not treat inherited shell env as operator intent. In particular,
`OPENCLAW_LOCAL_CHECK_MODE=throttled` from the local shell is not permission
to move broad `pnpm check:changed`, `pnpm test:changed`, full `pnpm test`, or
lint/typecheck fan-out onto the laptop.
- Only use `OPENCLAW_LOCAL_CHECK_MODE=throttled|full` when the user explicitly
asks for local proof in the current task. If Testbox is queued or capacity is
constrained, report the blocker and keep only targeted local edit-loop checks
running.
constrained, report the blocker; do not silently move heavy work onto the
laptop.
## macOS And Windows Targets
@ -152,6 +225,7 @@ Changed gate:
```sh
pnpm crabbox:run -- \
--provider aws \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
@ -163,6 +237,7 @@ Full suite:
```sh
pnpm crabbox:run -- \
--provider aws \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
@ -179,6 +254,7 @@ Focused rerun:
```sh
pnpm crabbox:run -- \
--provider aws \
--idle-timeout 90m \
--ttl 240m \
--timing-json \
@ -368,7 +444,7 @@ Efficient flow:
1. Reproduce or prove the pre-fix symptom from the real user-facing entrypoint
when feasible. If the issue cannot be reproduced, capture the exact command
and observed behavior instead.
2. Patch locally and run narrow local tests for edit speed.
2. Patch locally and run narrow tests on the pre-warmed remote box.
3. Run one Crabbox E2E command that starts from the user-facing entrypoint:
package install, Docker setup, onboarding, channel add, gateway start, or
agent turn as appropriate.
@ -387,8 +463,9 @@ Keep it efficient:
top of that PR.
- Use `--full-resync` before replacing a warmed direct-provider lease when the
remote workdir or sync fingerprint appears stale.
- Use one-shot Crabbox for a single proof; use a reusable Testbox only when
several commands must share built images, installed packages, or live state.
- For agent code tasks, reuse the pre-warmed remote box across focused tests
and heavy proof. Use a one-shot only when a single late proof is genuinely
the task's only remote command.
- Prefer `OPENCLAW_CURRENT_PACKAGE_TGZ` with Docker/package lanes when testing a
candidate tarball; prefer the repo's package helper instead of direct source
execution when the bug might be packaging/install related.
@ -448,13 +525,24 @@ Interactive CLI/onboarding:
## Reuse And Keepalive
For most Crabbox calls, one-shot is enough. Use reuse only when you need
multiple manual commands on the same hydrated box.
Agent code tasks should pre-warm and reuse one remote box selected by source
trust for focused tests and heavy proof. One-shot runs remain appropriate for a
single late proof when early warmup was not warranted.
Reuse the lease, not stale source. Each command must sync the current checkout;
use `--no-sync` only to rerun an unchanged, already-synced tree intentionally.
Untrusted reuse still requires `CRABBOX_ENV_ALLOW=CI`,
`--no-hydrate`, and a fresh temporary remote `HOME` on every command. Reuse
only a fresh lease dedicated to the same untrusted source; never a trusted or
previously hydrated lease. Launch from the clean trusted `main` checkout and
use `--fresh-pr` plus the same reviewed-SHA check on every run. Keep
`CRABBOX_AWS_INSTANCE_PROFILE` unset for warmup, run, and cleanup. The lease is
valid only for that reviewed SHA; stop and rewarm after any head change.
If Crabbox returns a reusable id or you intentionally keep a lease:
```sh
pnpm crabbox:run -- --id <cbx_id-or-slug> --no-sync --timing-json --shell -- "pnpm test <path>"
node scripts/crabbox-wrapper.mjs run --provider <blacksmith-testbox-or-aws> --id <id-or-slug> --timing-json --shell -- "corepack pnpm test <path>"
```
Stop boxes you created before handoff:
@ -549,8 +637,8 @@ Common Crabbox-only failures:
- Provider missing or old CLI: use `../crabbox/bin/crabbox` from the sibling
repo, or update/install Crabbox before retrying.
- Bad local config: inspect `.crabbox.yaml`, `crabbox config show`, and
`crabbox whoami`; normal OpenClaw proof should use brokered AWS without
asking for cloud keys.
`crabbox whoami`; normal OpenClaw agent proof should use Blacksmith Testbox.
Direct AWS is an explicit fallback and must use brokered auth, not raw keys.
- Slug/claim confusion: use the raw `cbx_...` / `tbx_...` id, or run one-shot
without `--id`.
- Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the
@ -563,21 +651,21 @@ Common Crabbox-only failures:
Blacksmith runs, use `blacksmith testbox list` and stop only boxes you
created.
- Testbox queued/capacity pressure: do not retry Blacksmith repeatedly. Rerun
once without `--provider` so `.crabbox.yaml` routes to brokered AWS, or report
the Blacksmith blocker if Testbox itself is the requested proof.
once with `--provider aws` when direct AWS still proves the requested
surface, or report the Blacksmith blocker if Testbox itself is required.
If brokered AWS cannot dispatch, sync, attach, or stop, retry once with
`--debug` and `--timing-json`:
```sh
pnpm crabbox:run -- --debug --timing-json -- \
pnpm crabbox:run -- --provider aws --debug --timing-json -- \
pnpm test:changed
```
Full suite:
```sh
pnpm crabbox:run -- --debug --timing-json -- \
pnpm crabbox:run -- --provider aws --debug --timing-json -- \
pnpm test
```
@ -596,10 +684,10 @@ Raw Blacksmith footguns:
- Treat `blacksmith testbox list` as cleanup diagnostics, not a shared reusable
queue.
Use Blacksmith only when the task is specifically about Testbox, brokered AWS
is unavailable, or an explicit comparison is needed. If Blacksmith is down or
quota-limited, do not keep probing it; stay on brokered AWS and note the
delegated-provider outage.
Use Blacksmith Testbox through Crabbox by default for OpenClaw agent tests and
heavy work. If Blacksmith is down or quota-limited, do not keep probing it;
switch to direct AWS only when that backend proves the same surface, and note
the delegated-provider outage.
## Blacksmith Backend Notes
@ -636,17 +724,17 @@ Important Blacksmith footguns:
blacksmith auth login --non-interactive --organization openclaw
```
## Brokered AWS
## Brokered AWS Fallback
Use AWS for normal OpenClaw remote proof. The repo `.crabbox.yaml` already
selects brokered AWS, so omit `--provider` unless you are testing a different
provider deliberately.
Use direct AWS when Testbox is unavailable, when the task needs direct-provider
semantics, or when an explicit backend comparison is required. The repo
`.crabbox.yaml` defaults to Blacksmith Testbox, so pass `--provider aws`.
```sh
pnpm crabbox:warmup -- --class beast --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "pnpm test:changed"
pnpm crabbox:stop -- <cbx_id-or-slug>
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --provider aws --id <cbx_id-or-slug>
pnpm crabbox:run -- --provider aws --id <cbx_id-or-slug> --timing-json --shell -- "pnpm test:changed"
pnpm crabbox:stop -- --provider aws <cbx_id-or-slug>
```
Install/auth for owned Crabbox if needed:

22
.agents/skills/openclaw-pr-maintainer/SKILL.md
View file

@ -279,12 +279,32 @@ gh search issues --repo openclaw/openclaw --match title,body --limit 50 \
## Follow PR review and landing hygiene
- At the start of code-changing or landing work that will need tests or heavy
proof, classify source trust and pre-warm the safe backend through `$crabbox`
in the background. Trusted maintainer code defaults to Blacksmith Testbox;
contributor/fork code stays untrusted unless a maintainer explicitly approves
credentialed execution after review; it uses secretless fork CI or
sanitized direct AWS Crabbox with `CRABBOX_ENV_ALLOW=CI`,
`--no-hydrate`, and a fresh temporary remote `HOME`, never the
credential-hydrated Testbox workflow or a previously hydrated lease. Launch
an installed trusted Crabbox binary from clean trusted `main`, fetch the PR
with `--fresh-pr`, unset and reject any resolved AWS instance profile, verify
trusted IMDS reports no IAM credentials, bind the lease to the reviewed head
SHA, and never execute its local wrapper or config. Upload trusted
`scripts/crabbox-untrusted-bootstrap.sh` from clean `main` alongside
`--fresh-pr`; it installs the pinned Node/pnpm runtime before executing PR
code. Force public networking, disable and
unset inherited Tailscale/exit-node settings, and fail closed unless
`crabbox inspect` reports no Tailscale state before any script. Rewarm after
any head change. Continue
review/editing while it hydrates, sync every run, reuse the lease, then stop
it before handoff. Skip warmup for read-only triage and docs-only work.
- Never mention release-note bookkeeping in review-only output. It is landing
or release-generation mechanics, not a correctness finding.
- If bot review conversations exist on your PR, address them and resolve them yourself once fixed.
- Leave a review conversation unresolved only when reviewer or maintainer judgment is still needed.
- Before landing any PR with non-trivial code changes, run `$autoreview` until no accepted/actionable findings remain, unless equivalent manual review already covered it, the change is trivial/docs-only, or the user opts out.
- When an agent is landing or merging a PR targeting `main`, use only the repo-native `scripts/pr` wrapper: run `scripts/pr review-init <PR>`, follow its emitted checkout/guard guidance, initialize and complete review artifacts with `scripts/pr review-artifacts-init <PR>`, validate them with `scripts/pr review-validate-artifacts <PR>`, then run `scripts/pr prepare-run <PR>` and `scripts/pr merge-run <PR>`.
- When an agent is landing or merging a PR targeting `main`, use only the repo-native `scripts/pr` wrapper: run `scripts/pr review-init <PR>`, follow its emitted checkout/guard guidance, initialize and complete review artifacts with `scripts/pr review-artifacts-init <PR>`, validate them with `scripts/pr review-validate-artifacts <PR>`, then run `OPENCLAW_TESTBOX=1 scripts/pr prepare-run <PR>` and `scripts/pr merge-run <PR>`. The Testbox flag is mandatory for agents: it verifies exact-head hosted CI/Testbox instead of running full `pnpm` gates locally.
- Use `scripts/committer "<msg>" <file...>` for scoped commits instead of manual `git add` and `git commit`.
- Keep commit messages concise and action-oriented.
- Group related changes; avoid bundling unrelated refactors.

147
.agents/skills/openclaw-testing/SKILL.md
View file

@ -18,18 +18,97 @@ or validating a change without wasting hours.
Prove the touched surface first. Do not reflexively run the whole suite.
Agent sessions are remote-first for tests and computationally intensive work.
Classify source trust before selecting a backend. Trusted maintainer code
defaults to Blacksmith Testbox. Untrusted contributor or fork code must use
secretless fork CI or sanitized direct AWS Crabbox; never sync or run it on the
credential-hydrated Blacksmith workflow.
When trusted work is likely to change code or need tests, builds, typechecks,
lint fan-out, Docker, packaging, E2E, or live proof, immediately start this in
a background command session:
```bash
node scripts/crabbox-wrapper.mjs warmup \
--provider blacksmith-testbox \
--keep \
--timing-json
```
For untrusted code, switch to a clean trusted `main` checkout and pre-warm
direct AWS with an installed trusted Crabbox binary. Do not execute the
untrusted checkout's wrapper or config locally:
```bash
cd <trusted-openclaw-main>
env -u CRABBOX_AWS_INSTANCE_PROFILE \
crabbox config show --json | \
jq -e '.aws.instanceProfile == ""' >/dev/null
env -u CRABBOX_AWS_INSTANCE_PROFILE \
-u CRABBOX_TAILSCALE \
-u CRABBOX_TAILSCALE_AUTH_KEY \
-u CRABBOX_TAILSCALE_AUTH_KEY_ENV \
-u CRABBOX_TAILSCALE_EXIT_NODE \
-u CRABBOX_TAILSCALE_EXIT_NODE_ALLOW_LAN_ACCESS \
-u CRABBOX_TAILSCALE_HOSTNAME_TEMPLATE \
-u CRABBOX_TAILSCALE_TAGS \
crabbox warmup \
--provider aws \
--network public \
--tailscale=false \
--tailscale-exit-node= \
--tailscale-exit-node-allow-lan-access=false \
--keep \
--timing-json
crabbox inspect --provider aws --id <cbx_id> --json | \
jq -e '.network == "public" and .tailscale == null' >/dev/null
```
Bind the returned lease to one immutable reviewed head SHA; never repurpose a
trusted or previously hydrated lease, and stop/rewarm if the head changes.
Record the reviewed PR's full head SHA with
`gh pr view <number> --repo <owner/repo> --json headRefOid --jq .headRefOid`.
Every untrusted AWS run must override the repo env allowlist, skip Actions
hydration, and upload the trusted bootstrap script from clean `main` alongside
`--fresh-pr`. The script bypasses raw-box JavaScript preflight, proves the
identity boundary, installs pinned Node/pnpm, verifies the exact SHA and
package-manager pin, isolates `HOME`, installs dependencies, then runs the
requested test command:
```bash
env -u CRABBOX_AWS_INSTANCE_PROFILE \
CRABBOX_ENV_ALLOW=CI \
crabbox run \
--provider aws \
--id <cbx_id> \
--fresh-pr <owner/repo#number> \
--no-hydrate \
--timing-json \
--script scripts/crabbox-untrusted-bootstrap.sh -- \
<expected_head_sha> /usr/local/bin/pnpm test <path-or-filter>
# After all proof:
env -u CRABBOX_AWS_INSTANCE_PROFILE \
crabbox stop --provider aws <cbx_id>
```
Continue inspection and editing while the remote box hydrates. Save the
returned id, reuse it for the task's focused tests and heavy gates, sync the
current checkout on every run, and stop it before handoff. Do not pre-warm for
read-only, docs-only, or clearly trivial work that will not run tests or heavy
commands.
1. Inspect the diff and classify the touched surface:
- normal source checkout, source change: `pnpm changed:lanes --json`, then `pnpm check:changed` (delegates to Crabbox/Testbox)
- normal source checkout, tests only: `pnpm test:changed`
- normal source checkout, one failing file: `pnpm test <path-or-filter> -- --reporter=verbose`
- Codex worktree or linked/sparse checkout, one/few explicit files: `node scripts/run-vitest.mjs <path-or-filter>`
- Codex worktree or linked/sparse checkout, changed gates or anything broad:
use the Crabbox wrapper with the provider that matches the proof surface.
For maintainer heavy `pnpm` gates, that is usually delegated Blacksmith
Testbox through Crabbox, e.g. `node scripts/crabbox-wrapper.mjs run
--provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed`. For direct AWS
Crabbox proof, pass `--provider aws`; omitting `--provider` follows the
`.crabbox.yaml` default (Blacksmith Testbox).
- any agent-run test, focused or broad: run it on the pre-warmed safe remote
backend; Blacksmith Testbox only for trusted maintainer code
- changed gates, builds, typechecks, lint fan-out, Docker, package, E2E, or
live work: run it remotely; these are never routine laptop work
- normal source checkout, `pnpm check:changed`: it delegates to
Crabbox/Testbox, but prefer the explicit kept-lease path when a Testbox was
pre-warmed so the task reuses one lease
- explicit local fallback requested by the user, one/few files:
`node scripts/run-vitest.mjs <path-or-filter>`
- direct AWS Crabbox proof: pass `--provider aws`; untrusted code also
requires the sanitized invocation above
- workflow-only: `git diff --check`, workflow syntax/lint (`actionlint` when available)
- docs-only: `pnpm docs:list`, docs formatter/lint only if docs tooling changed or requested
2. Reproduce narrowly before fixing.
@ -40,21 +119,45 @@ Prove the touched surface first. Do not reflexively run the whole suite.
## Guardrails
- Do not kill unrelated processes or tests. If something is running elsewhere, treat it as owned by the user or another agent.
- Do not run expensive local Docker, full release checks, full `pnpm test`, or full `pnpm check` unless the user asks or the change genuinely requires it.
- Do not run tests or computationally intensive commands locally unless the user explicitly asks for local proof. Remote-provider unavailability permits only a narrow reported fallback, not a silent local full gate.
- Prefer GitHub Actions for release/Docker proof when the workflow already has the prepared image and secrets.
- Use `scripts/committer "<msg>" <paths...>` when committing; stage only your files.
- If deps are missing, run `pnpm install`, retry once, then report the first actionable error.
- If dependencies are missing on the selected remote box, run `pnpm install` there, retry
once, then report the first actionable error. Do not reconcile or reinstall a
local Codex worktree merely to run validation.
- In a Codex worktree or linked/sparse checkout, do not run direct local
`pnpm test*`, `pnpm check*`, `pnpm crabbox:run`, or `scripts/committer` until
you have verified pnpm will not reconcile or reinstall dependencies. Use
`node scripts/run-vitest.mjs` for tiny local proof, `node
scripts/crabbox-wrapper.mjs` for Testbox, and `git commit --no-verify` only
after the relevant remote or node-wrapper proof is already clean.
`pnpm test*`, `pnpm check*`, `pnpm crabbox:run`, or `scripts/committer`. Use
`node scripts/crabbox-wrapper.mjs` for remote proof, and `git commit --no-verify`
only after the relevant remote proof is already clean. The direct
`node scripts/run-vitest.mjs` path is an explicit local fallback only.
- For remote proof, use the Crabbox wrapper first, but name the actual backend.
Direct AWS Crabbox uses `provider=aws` and `cbx_...` ids. Delegated
Blacksmith Testbox through Crabbox uses `provider=blacksmith-testbox`,
`syncDelegated=true`, and `tbx_...` ids. Both satisfy "remote proof" when the
requested proof surface allows either.
- Treat contributor and fork patches as untrusted unless a maintainer
explicitly approves credentialed execution after review. For untrusted AWS
runs, `CRABBOX_ENV_ALLOW=CI` must replace the repo's
`OPENCLAW_*` allowlist, `--no-hydrate` must block auth-profile hydration, and
the remote command must use a fresh temporary `HOME`. The lease must be newly
warmed for and bound to one reviewed head SHA, never trusted or previously
hydrated; stop and rewarm when the SHA changes. Do
not execute repo scripts or config from the untrusted local checkout: launch
an installed trusted Crabbox binary from a clean trusted `main` checkout and
fetch the PR with `--fresh-pr`. Unset `CRABBOX_AWS_INSTANCE_PROFILE` and fail
closed unless `crabbox config show --json` resolves an empty
`aws.instanceProfile`. Before any install/test, use trusted absolute-path
tools to require an IMDSv2 token, prove the IAM credentials endpoint returns
404, and compare remote `git rev-parse HEAD` with the full reviewed head SHA.
Unset all `CRABBOX_TAILSCALE*` overrides, pass `--network public
--tailscale=false`, clear exit-node/LAN flags, then require `crabbox inspect`
to report `network=public` and no Tailscale state before uploading any script.
Upload trusted `scripts/crabbox-untrusted-bootstrap.sh` with `--fresh-pr`; it
bootstraps Node 24 and repository-pinned pnpm before executing PR code and
rejects a changed `packageManager` pin before install.
If the broker cannot provide that no-role proof or no remote PR exists, use
secretless fork CI. Do not select `hydrate-github` or a credential-hydrated
Testbox workflow.
- Do not infer "no Testbox is running" from plain `blacksmith testbox list`.
Use `blacksmith testbox list --all` or `blacksmith testbox status <tbx_id>`
before reporting cloud state.
@ -62,8 +165,14 @@ scripts/crabbox-wrapper.mjs` for Testbox, and `git commit --no-verify` only
coordinating with another lane. If Testbox queues, fails capacity, or cannot
allocate, report the blocker or switch to direct AWS Crabbox only when that
still proves the requested surface.
- Reuse does not mean stale source: omit `--no-sync` so every run uploads the
current checkout. Use `--no-sync` only to rerun an unchanged, already-synced
tree intentionally.
## Local Test Shortcuts
## Explicit Local Test Fallbacks
These commands are for human workflows or an agent's explicit local fallback.
They are not the default agent path.
```bash
pnpm changed:lanes --json

20
AGENTS.md
View file

@ -113,27 +113,29 @@ Skills own workflows; root owns hard policy and routing.
- Runtime: Node 22.19+; Node 24 recommended. Keep Node + Bun paths working.
- Package manager/runtime: repo defaults only. No swaps without approval.
- Install: `pnpm install` (keep Bun lock/patches aligned if touched).
- Install: `pnpm install` (keep Bun lock/patches aligned if touched). Agent dependency installation for tests/builds defaults to the selected remote box; do not reconcile a local Codex worktree just to run validation.
- CLI: `pnpm openclaw ...` or `pnpm dev`; build: `pnpm build`.
- Tests in a normal source checkout: `pnpm test <path-or-filter> [vitest args...]`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`; never raw `vitest`.
- Agent tests default remote through Crabbox, including focused tests. Trusted maintainer code defaults to Blacksmith Testbox. Contributor/fork code remains untrusted unless a maintainer explicitly approves credentialed execution after review; use secretless fork CI or sanitized direct AWS Crabbox, never a credential-hydrated Testbox. Sanitized AWS must launch an installed trusted Crabbox binary from a clean trusted `main` checkout and fetch only the remote PR via `--fresh-pr`; never execute a wrapper, config, or command from the untrusted local checkout. Before warmup, unset `CRABBOX_AWS_INSTANCE_PROFILE` and all `CRABBOX_TAILSCALE*` overrides; fail closed unless resolved `aws.instanceProfile` is empty. Force `--network public --tailscale=false`, clear exit-node/LAN flags, and require `crabbox inspect` to report public networking with no Tailscale state before any script. Upload trusted `scripts/crabbox-untrusted-bootstrap.sh` from clean `main` alongside `--fresh-pr`; it proves the remote IMDSv2 IAM credentials endpoint returns 404, verifies the reviewed head SHA, unsets `NODE_OPTIONS`, installs pinned Node/pnpm, verifies the package-manager pin, isolates `HOME`, installs dependencies, then runs the requested test. Use a newly warmed lease bound to one reviewed head SHA, set `CRABBOX_ENV_ALLOW=CI`, and use `--no-hydrate`. Never reuse a trusted/previously hydrated lease or carry an untrusted lease across head revisions; stop and rewarm when the SHA changes. No repo `OPENCLAW_*` allowlist, existing auth profile, instance role, tailnet/LAN access, moving PR head, or ambient Node preload may reach untrusted execution. When a code task is likely to need tests, classify source trust, pre-warm the safe backend immediately, keep working while it hydrates, reuse trusted leases or same-SHA untrusted leases, then stop before handoff.
- Test commands (run inside the selected remote box by default): `pnpm test <path-or-filter> [vitest args...]`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`; never raw `vitest`.
- If raw Vitest is unavoidable, use `vitest run ...`; bare `vitest ...` starts local watch mode and will not exit on its own.
- Tests in a Codex worktree or linked/sparse checkout: avoid direct local `pnpm test*`; use `node scripts/run-vitest.mjs <path-or-filter>` for tiny explicit-file proof, or Crabbox/Testbox for anything broader.
- Local agent test execution is opt-in: only when the user explicitly requests local proof or Testbox is unavailable and the fallback is reported. In a Codex worktree or linked/sparse checkout, the narrow local fallback is `node scripts/run-vitest.mjs <path-or-filter>`; never direct local `pnpm test*`.
- Checks/lint in a normal source checkout: `pnpm check:changed` delegates to Crabbox/Testbox; lanes: `pnpm changed:lanes --json`; staged/path-scoped: `pnpm check:changed --staged` or `pnpm check:changed -- <files...>`; full `pnpm check`/`pnpm lint` only when required.
- Checks in a Codex worktree or linked/sparse checkout: avoid direct local `pnpm check*`; use `node scripts/crabbox-wrapper.mjs run ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed` so pnpm runs inside Testbox, not locally.
- Checks in a Codex worktree or linked/sparse checkout: avoid direct local `pnpm check*`; use `node scripts/crabbox-wrapper.mjs run ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed` so pnpm runs inside the selected remote box, not locally.
- Extension tests: `pnpm test:extensions`, `pnpm test extensions`, `pnpm test extensions/<id>`.
- Typecheck: `tsgo` lanes only (`pnpm tsgo*`, `pnpm check:test-types`); never add `tsc --noEmit`, `typecheck`, `check:types`.
- Formatting: `oxfmt`, not Prettier. Use repo wrappers (`pnpm format:*`, `scripts/run-oxlint.mjs`; full `pnpm lint:*` only when scope requires).
- Build before push when build output, packaging, lazy/module boundaries, dynamic imports, or published surfaces can change.
- Build before push when build output, packaging, lazy/module boundaries, dynamic imports, or published surfaces can change; agent builds default to the selected remote box unless platform-specific proof requires another remote host.
## Validation
- Use `$openclaw-testing` for test/CI choice and `$crabbox` for remote/full/E2E proof.
- At task start, if code changes, tests, builds, typechecks, lint fan-out, Docker, packaging, E2E, or live proof are likely, classify source trust and immediately pre-warm the safe Crabbox backend in a background command session. Trusted maintainer code defaults to Blacksmith Testbox; untrusted contributor/fork code uses secretless fork CI or sanitized direct AWS Crabbox under the rule above. Continue inspection/editing while it hydrates; sync the current checkout for every run, reuse the lease, then stop it before handoff.
- Crabbox request means real scenario proof: install/update/call/repro user path; not just copy tests and run them remotely.
- Visual proof: use Crabbox, set up like a user, then screenshot-verify. No harness/bypass/shortcut unless explicitly asked.
- Small/narrow tests, lints, format checks, and type probes are fine locally only in a healthy normal checkout.
- Local agent work is limited to lightweight non-test checks such as `git diff --check`, targeted formatting, and cheap static probes. Tests and computationally intensive work default to the selected remote box.
- In Codex worktrees, direct local `pnpm test*`, `pnpm check*`, `pnpm crabbox:run`, and `scripts/committer` can trigger pnpm dependency reconciliation or install prompts. Prefer `node` wrappers locally and Crabbox/Testbox for pnpm-gated proof.
- Full suites, broad changed gates, Docker/package/E2E/live/cross-OS proof, or anything that bogs down the Mac: Crabbox/Testbox.
- One/few files local. If a local command fans out, stop and move broad proof to Crabbox/Testbox.
- Full suites, changed gates, builds, typechecks, lint fan-out, Docker/package/E2E/live/cross-OS proof, or anything computationally intensive: Crabbox/Testbox.
- If an allowed local fallback fans out or becomes expensive, stop it and move the work to the pre-warmed remote box.
- Before handoff/push: prove touched surface. Before landing to `main`: issue proof plus appropriate full/broad proof unless scope is clearly narrow.
- Pre-land/pre-commit code changes: mandatory fresh `$autoreview` until no accepted/actionable findings remain. Do not land code on CI, ClawSweeper, prior review comments, or your own manual review alone unless user explicitly opts out or scope is truly trivial/docs-only. If findings want refactor, refactor; no ugly fixes.
- If proof is blocked, say exactly what is missing and why.
@ -175,7 +177,7 @@ Skills own workflows; root owns hard policy and routing.
- Contributor PRs: parsed context requires authored `What Problem This Solves` and `Evidence` sections. Do not require field-level proof forms; reviewers inspect code, tests, and CI for correctness.
- PR artifacts/screenshots: attach to PR/comment/external artifact store. Never push screenshots, videos, proof images, or proof assets to OpenClaw or any product repo branch, including temp artifact branches. Use Crabbox artifact publishing plus the manifest URL. Do not commit `.github/pr-assets`.
- CI polling: exact SHA, relevant checks only, minimal fields. Skip routine noise (`Auto response`, `Labeler`, docs agents, performance/stale). Logs only after failure/completion or concrete need.
- Agent PR landing to `main`: use only the repo-native `scripts/pr` wrapper: run `scripts/pr review-init <PR>`, follow its emitted checkout/guard guidance, initialize and complete review artifacts with `scripts/pr review-artifacts-init <PR>`, validate them with `scripts/pr review-validate-artifacts <PR>`, then run `scripts/pr prepare-run <PR>` and `scripts/pr merge-run <PR>`; do not idle on `auto-response` or `check-docs`.
- Agent PR landing to `main`: use only the repo-native `scripts/pr` wrapper: run `scripts/pr review-init <PR>`, follow its emitted checkout/guard guidance, initialize and complete review artifacts with `scripts/pr review-artifacts-init <PR>`, validate them with `scripts/pr review-validate-artifacts <PR>`, then run `OPENCLAW_TESTBOX=1 scripts/pr prepare-run <PR>` and `scripts/pr merge-run <PR>`. The Testbox flag is mandatory for agents so prepare verifies exact-head hosted CI/Testbox instead of running full gates locally; do not idle on `auto-response` or `check-docs`.
## Code

68
docs/ci.md
View file

@ -605,13 +605,43 @@ Local changed-test routing lives in `scripts/test-projects.test-support.mjs` and
## Testbox validation
Crabbox is the repo-owned remote-box wrapper for maintainer Linux proof. Use it
from the repo root when a check is too broad for a local edit loop, when CI
parity matters, or when the proof needs secrets, Docker, package lanes,
reusable boxes, or remote logs. The normal OpenClaw backend is
`blacksmith-testbox`, and `.crabbox.yaml` now defaults to it; owned AWS/Hetzner
capacity is a fallback for Blacksmith outages, quota issues, or explicit
owned-capacity testing.
Crabbox is the repo-owned remote-box wrapper for maintainer Linux proof. Agent
sessions use it by default for tests and computationally intensive work,
including builds, typechecks, lint fan-out, Docker, package lanes, E2E, live
proof, and CI parity. Trusted maintainer code defaults to
`blacksmith-testbox`, and `.crabbox.yaml` now defaults to it. Its configured
workflow hydrates provider and agent credentials, so untrusted contributor or
fork code must use secretless fork CI or sanitized direct AWS Crabbox instead.
Sanitized AWS runs set `CRABBOX_ENV_ALLOW=CI`, pass
`--no-hydrate`, and use a fresh temporary remote `HOME`; this prevents the repo
`OPENCLAW_*` allowlist and existing auth profiles from reaching untrusted code.
They use a newly warmed lease dedicated to that untrusted source, never a
trusted or previously hydrated lease. Launch an installed trusted Crabbox
binary from a clean trusted `main` checkout and fetch only the remote PR with
`--fresh-pr`; never execute the untrusted checkout's wrapper or config locally.
Unset `CRABBOX_AWS_INSTANCE_PROFILE` and fail closed unless resolved
`aws.instanceProfile` is empty. Before any install/test, use trusted
absolute-path tools to require an IMDSv2 token, prove the IAM credentials
endpoint returns 404, and compare remote `git rev-parse HEAD` to the full
reviewed PR head SHA. Bind the lease to that SHA and stop/rewarm on head change.
Upload trusted `scripts/crabbox-untrusted-bootstrap.sh` from clean `main`
alongside `--fresh-pr`; it installs pinned Node/pnpm, verifies the SHA and
package-manager pin, isolates `HOME`, installs dependencies, then executes the
requested test.
Unset all `CRABBOX_TAILSCALE*` overrides, force `--network public
--tailscale=false`, clear exit-node/LAN flags, and require `crabbox inspect` to
report public networking with no Tailscale state before uploading any script.
Owned AWS/Hetzner capacity also remains the fallback for Blacksmith outages,
quota issues, or explicit owned-capacity testing.
At the start of a trusted code task likely to need tests or heavy proof, agents
should pre-warm immediately in a background command session, continue
inspection and editing while hydration runs, reuse the returned `tbx_...` id,
sync the current checkout on every run, and stop it before handoff:
```bash
node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json
```
Crabbox-backed Blacksmith runs warm, claim, sync, run, report, and clean up
one-shot Testboxes. The built-in sync sanity check fails fast when
@ -700,10 +730,26 @@ blacksmith testbox stop --id <tbx_id>
Use reuse only when you intentionally need multiple commands on the same hydrated box:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox --id <tbx_id> --timing-json --shell -- "corepack pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>
```
Reuse the lease, not stale source. Omit `--no-sync` so each run uploads the
current checkout; use it only to rerun an unchanged, already-synced tree
intentionally. Untrusted contributor/fork code must use
`CRABBOX_ENV_ALLOW=CI`, `--provider aws --no-hydrate`, and a fresh
temporary remote `HOME` for every command; install dependencies inside that
sanitized command before testing. Reuse only a newly warmed lease dedicated to
the same untrusted source; never a trusted or previously hydrated lease. Never
execute the untrusted checkout's wrapper or config locally: launch the installed
trusted Crabbox binary from clean trusted `main` and pass `--fresh-pr` on every
run. Keep `CRABBOX_AWS_INSTANCE_PROFILE` unset, reject a non-empty resolved
instance profile, require a trusted remote IMDS no-role proof, and verify the
reviewed head SHA before install/test. Bind the lease to that SHA; stop and
rewarm after any head change. If no remote PR exists, use secretless fork CI.
Never select `hydrate-github` or the credential-hydrated Blacksmith workflow
for untrusted source.
If Crabbox is the broken layer but Blacksmith itself works, use direct
Blacksmith only for diagnostics such as `list`, `status`, and cleanup. Fix the
Crabbox path before treating a direct Blacksmith run as maintainer proof.
@ -720,9 +766,9 @@ Escalate to owned Crabbox capacity only when Blacksmith is down, quota-limited,
```bash
CRABBOX_CAPACITY_REGIONS=eu-west-1,eu-west-2,eu-central-1,us-east-1,us-west-2 \
pnpm crabbox:warmup -- --provider aws --class standard --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "pnpm check:changed"
pnpm crabbox:stop -- <cbx_id-or-slug>
pnpm crabbox:hydrate -- --provider aws --id <cbx_id-or-slug>
pnpm crabbox:run -- --provider aws --id <cbx_id-or-slug> --timing-json --shell -- "pnpm check:changed"
pnpm crabbox:stop -- --provider aws <cbx_id-or-slug>
```
Under AWS pressure, avoid `class=beast` unless the task really needs 48xlarge-class CPU. A `beast` request starts at 192 vCPUs and is the easiest way to trip regional EC2 Spot or On-Demand Standard quota. The repo-owned `.crabbox.yaml` defaults to `class: standard`, on-demand market, and `capacity.hints: true` so brokered AWS leases print selected region/market, quota pressure, Spot fallback, and high-pressure class warnings. Use `fast` for heavier broad checks, `large` only after standard/fast are not enough, and `beast` only for exceptional CPU-bound lanes such as full-suite or all-plugin Docker matrices, explicit release/blocker validation, or high-core performance profiling. Do not use `beast` for `pnpm check:changed`, focused tests, docs-only work, ordinary lint/typecheck, small E2E repros, or Blacksmith outage triage. Use `--market on-demand` for capacity diagnosis so Spot market churn is not mixed into the signal.

1
docs/docs_map.md
View file

@ -8399,6 +8399,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- Route: /reference/test
- Headings:
- H2: Agent default
- H2: Routine local order
- H2: Core commands
- H2: Shared test state and process helpers

52
docs/reference/test.md
View file

@ -8,17 +8,59 @@ title: "Tests"
- Full testing kit (suites, live, Docker): [Testing](/help/testing)
- Update and plugin package validation: [Testing updates and plugins](/help/testing-updates-plugins)
## Agent default
Agent sessions run tests and computationally intensive validation remotely
through Crabbox. Trusted maintainer code defaults to Blacksmith Testbox. The
configured Testbox workflow hydrates credentials, so untrusted contributor or
fork code must use secretless fork CI or sanitized direct AWS Crabbox instead.
When a trusted code task is likely to need tests or heavy proof, pre-warm
immediately in a background command session, keep working while it hydrates,
reuse the returned `tbx_...` id, sync the current checkout on every run, and
stop it before handoff:
```bash
node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json
```
Local test commands below are for human workflows or an explicit agent fallback
requested by the user. Remote-provider unavailability must be reported; it is
not permission to silently run a broad local gate.
For untrusted code, pre-warm with `--provider aws`. Every run must set
`CRABBOX_ENV_ALLOW=CI`, pass `--provider aws --no-hydrate`, and use
a fresh temporary remote `HOME` before installing dependencies or running
tests. Use a newly warmed lease dedicated to that untrusted source; never reuse
a trusted or previously hydrated lease. Launch an installed trusted Crabbox
binary from a clean trusted `main` checkout and fetch only the remote PR with
`--fresh-pr`; never execute the untrusted checkout's wrapper or config locally.
Unset `CRABBOX_AWS_INSTANCE_PROFILE` and fail closed unless resolved
`aws.instanceProfile` is empty. Before any install/test, use trusted
absolute-path tools to require an IMDSv2 token, prove the IAM credentials
endpoint returns 404, and verify remote `git rev-parse HEAD` equals the full
reviewed PR head SHA. Bind the lease to that SHA and stop/rewarm when the head
changes. Upload trusted `scripts/crabbox-untrusted-bootstrap.sh` from clean
`main` alongside `--fresh-pr`; it installs pinned Node/pnpm, verifies the SHA
and package-manager pin, isolates `HOME`, installs dependencies, then executes
the requested test. If the broker cannot prove no role or no remote PR exists,
use secretless fork CI. Do not use `hydrate-github`, `--no-sync`, or a
credential-hydrated Testbox workflow.
Unset all `CRABBOX_TAILSCALE*` overrides, force `--network public
--tailscale=false`, clear exit-node/LAN flags, and require `crabbox inspect` to
report public networking with no Tailscale state before uploading any script.
## Routine local order
1. `pnpm test:changed` for changed-scope Vitest proof.
2. `pnpm test <path-or-filter>` for one file, directory, or explicit target.
3. `pnpm test` only when you intentionally need the full local Vitest suite.
In a Codex worktree or linked/sparse checkout, avoid direct local `pnpm test*` /
`pnpm check*` / `pnpm crabbox:run` unless you have verified pnpm will not
reconcile dependencies:
In a Codex worktree or linked/sparse checkout, agents avoid direct local
`pnpm test*` / `pnpm check*` / `pnpm crabbox:run`:
- Tiny explicit-file proof: `node scripts/run-vitest.mjs <path-or-filter>`.
- Explicit user-requested local fallback for a tiny file:
`node scripts/run-vitest.mjs <path-or-filter>`.
- Changed gates or broad proof: `node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed` so pnpm runs inside Testbox.
- The wrapper's final `exitCode` and timing JSON are the command result. A delegated Blacksmith GitHub Actions run may show `cancelled` after a successful SSH command because the Testbox is stopped from outside the keepalive action; check the wrapper summary and command output before treating that as a failure.
- `OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>`: keeps heavy-check serialization inside the current worktree instead of the Git common dir for commands such as `pnpm check:changed` and targeted `pnpm test ...`. Use it only on high-capacity local hosts when you intentionally run independent checks across linked worktrees.
@ -47,7 +89,7 @@ Test wrapper runs end with a short `[test] passed|failed|skipped ... in ...` sum
## Control UI, TUI, and extension lanes
- **Control UI mocked E2E:** `pnpm test:ui:e2e` runs the Vitest + Playwright lane that starts the Vite Control UI and drives a real Chromium page against a mocked Gateway WebSocket. Tests live in `ui/src/**/*.e2e.test.ts`; shared mocks/controls live in `ui/src/test-helpers/control-ui-e2e.ts`. `pnpm test:e2e` includes this lane. In Codex worktrees, prefer `node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts` for tiny targeted proof, or Testbox/Crabbox for broader GUI proof.
- **Control UI mocked E2E:** `pnpm test:ui:e2e` runs the Vitest + Playwright lane that starts the Vite Control UI and drives a real Chromium page against a mocked Gateway WebSocket. Tests live in `ui/src/**/*.e2e.test.ts`; shared mocks/controls live in `ui/src/test-helpers/control-ui-e2e.ts`. `pnpm test:e2e` includes this lane. Agent runs default to Testbox/Crabbox, including targeted proof; use `node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts` only for an explicit local fallback.
- **TUI PTY tests:** `node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts` runs the fast fake-backend PTY lane. `OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1` or `pnpm tui:pty:test:watch --mode local` runs the slower `tui --local` smoke, which mocks only the external model endpoint. Assert stable visible text or fixture calls, not raw ANSI snapshots.
- `pnpm test:extensions` and `pnpm test extensions` run all extension/plugin shards. Heavy channel plugins, the browser plugin, and OpenAI run as dedicated shards; other plugin groups stay batched. `pnpm test extensions/<id>` runs one bundled plugin lane.
- Source files with sibling tests map to that sibling before falling back to wider directory globs. Helper edits under `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, and `src/plugins/contracts` use a local import graph to run importing tests instead of broad-running every shard when the dependency path is precise.

2
scripts/README.md
View file

@ -41,7 +41,7 @@ new directory taxonomy.
| Release checks | `pnpm release:check`, `pnpm release:beta`, `pnpm release:candidate` | Release scripts are maintainer workflows; read release docs before use. |
| GitHub reads | `scripts/gh-read` | Uses a GitHub App read token when configured, leaving normal `gh` login for writes. |
| Commits | `scripts/committer "<message>" <files...>` | Preferred scoped commit helper for OpenClaw changes. |
| Remote proof | `node scripts/crabbox-wrapper.mjs ...` | Use for Crabbox/Testbox lanes when local proof would be too broad or environment-sensitive. |
| Remote proof | `node scripts/crabbox-wrapper.mjs ...` | Agent default for tests and heavy work; pre-warm by source trust, sync each run, reuse the lease. |
## Script Families

109
scripts/crabbox-untrusted-bootstrap.sh Executable file
View file

@ -0,0 +1,109 @@
#!/usr/bin/env bash
set -euo pipefail
node_version="24.15.0"
pnpm_spec="pnpm@11.2.2+sha512.36e6621fad506178936455e70247b8808ef4ec25797a9f437a93281a020484e2607f6a469a22e982987c3dbb8866e3071514ab10a4a1749e06edcd1ec118436f"
if [[ $# -lt 2 ]]; then
echo "usage: $0 <expected-head-sha> <command> [args...]" >&2
exit 2
fi
expected_head_sha="$1"
shift
unset NODE_OPTIONS
imds_token="$(
/usr/bin/curl -fsS -X PUT \
-H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
http://169.254.169.254/latest/api/token
)"
iam_status="$(
/usr/bin/curl -sS -o /dev/null -w "%{http_code}" \
-H "X-aws-ec2-metadata-token: ${imds_token}" \
http://169.254.169.254/latest/meta-data/iam/security-credentials/
)"
if [[ "$iam_status" != "404" ]]; then
echo "refusing untrusted bootstrap: IAM credentials endpoint returned ${iam_status}" >&2
exit 1
fi
actual_head_sha="$(/usr/bin/git rev-parse HEAD)"
if [[ "$actual_head_sha" != "$expected_head_sha" ]]; then
echo "refusing untrusted run: expected HEAD ${expected_head_sha}, got ${actual_head_sha}" >&2
exit 1
fi
case "$(/usr/bin/uname -m)" in
x86_64) node_arch="x64" ;;
aarch64 | arm64) node_arch="arm64" ;;
*)
echo "unsupported architecture: $(/usr/bin/uname -m)" >&2
exit 2
;;
esac
archive="node-v${node_version}-linux-${node_arch}.tar.xz"
base_url="https://nodejs.org/dist/v${node_version}"
install_root="/opt/openclaw-untrusted-node-v${node_version}-${node_arch}"
corepack_home="/opt/openclaw-untrusted-corepack"
tmp_dir="$(/usr/bin/mktemp -d)"
run_home=""
# Invoked by the EXIT trap.
# shellcheck disable=SC2329
cleanup() {
/bin/rm -rf -- "$tmp_dir"
if [[ -n "$run_home" ]]; then
/bin/rm -rf -- "$run_home"
fi
}
trap cleanup EXIT
/usr/bin/curl -fsSL --connect-timeout 10 --max-time 300 --retry 2 \
-o "$tmp_dir/$archive" "$base_url/$archive"
/usr/bin/curl -fsSL --connect-timeout 10 --max-time 60 --retry 2 \
-o "$tmp_dir/SHASUMS256.txt" "$base_url/SHASUMS256.txt"
(
cd "$tmp_dir"
/usr/bin/grep " ${archive}\$" SHASUMS256.txt | /usr/bin/sha256sum -c -
)
sudo /bin/rm -rf -- "$install_root" "$corepack_home"
sudo /usr/bin/mkdir -p "$install_root" "$corepack_home"
sudo /usr/bin/tar -xJf "$tmp_dir/$archive" -C "$install_root" --strip-components=1
sudo /usr/bin/env \
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
COREPACK_HOME="$corepack_home" \
PATH="$install_root/bin:/usr/bin:/bin" \
"$install_root/bin/corepack" enable --install-directory "$install_root/bin"
sudo /usr/bin/env \
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
COREPACK_HOME="$corepack_home" \
PATH="$install_root/bin:/usr/bin:/bin" \
"$install_root/bin/corepack" prepare "$pnpm_spec" --activate
for tool in node npm npx corepack pnpm pnpx; do
if [[ -e "$install_root/bin/$tool" ]]; then
sudo /usr/bin/ln -sfn "$install_root/bin/$tool" "/usr/local/bin/$tool"
fi
done
/usr/local/bin/node --version
actual_package_manager="$(
/usr/local/bin/node -e \
'const fs = require("node:fs"); const pkg = JSON.parse(fs.readFileSync("package.json", "utf8")); process.stdout.write(pkg.packageManager || "")'
)"
if [[ "$actual_package_manager" != "$pnpm_spec" ]]; then
echo "refusing untrusted run: packageManager pin differs from trusted main" >&2
exit 1
fi
run_home="$(/usr/bin/mktemp -d)"
export HOME="$run_home"
export COREPACK_HOME="$corepack_home"
export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
/usr/local/bin/pnpm --version
/usr/local/bin/pnpm install --frozen-lockfile
command_status=0
"$@" || command_status=$?
exit "$command_status"