OpenClaw Upstream Pull Request

Workflow for creating and submitting pull requests to the openclaw/openclaw GitHub repository from the kip-claw/openclaw fork.

Prerequisites

• GitHub CLI (gh) installed and authenticated as kip-claw (verify with gh auth status)
• SSH key at ~/.ssh/id_ed25519 configured for GitHub
• Crabbox CLI (crabbox) installed with Cloudflare provider configured
• Env vars CRABBOX_CLOUDFLARE_RUNNER_URL and CRABBOX_CLOUDFLARE_RUNNER_TOKEN in ~/.openclaw/.env

# gh is already authenticated system-wide — no need to export GH_TOKEN.
# Source the env only for Crabbox credentials:
source ~/.openclaw/.env && export CRABBOX_CLOUDFLARE_RUNNER_URL CRABBOX_CLOUDFLARE_RUNNER_TOKEN

CRITICAL env note: values in ~/.openclaw/.env are not auto-loaded into random interactive shells. Before any Crabbox command in a fresh terminal/session, run the source ~/.openclaw/.env line above (or explicitly pass CRABBOX_CLOUDFLARE_RUNNER_URL/CRABBOX_CLOUDFLARE_RUNNER_TOKEN). If you skip this, Crabbox may appear "not configured" even though the values exist in the file.

Prefer gh over naked git/curl wherever an equivalent exists. gh handles auth, fork-awareness, and API plumbing for you. Only fall back to raw git for operations gh doesn't cover (commit, push, rebase, local branching).

Fork Setup

The fork lives at kip-claw/openclaw. Use gh repo clone — it automatically sets the upstream remote to the parent repo for forks:

gh repo clone kip-claw/openclaw /tmp/openclaw-patch
cd /tmp/openclaw-patch
# `upstream` remote is already configured by `gh repo clone` for forks. Verify:
git remote -v   # should show origin=kip-claw/openclaw, upstream=openclaw/openclaw

# Sync the fork's default branch with upstream before branching:
gh repo sync kip-claw/openclaw --source openclaw/openclaw
git fetch upstream
git checkout -b fix/descriptive-branch-name upstream/main

The repo includes a .crabbox.yaml that configures Cloudflare remote builds (provider, instance class, setup steps, named jobs). No local pnpm install is needed — dependencies install on the remote container.

Source Layout

Key directories in the OpenClaw source:

TypeScript source compiles to dist/ as bundled JS files (e.g., dist/server-cron-*.js).

Extension / Plugin PRs

Not every PR is a core src/ fix. Bundled plugins live under extensions/<name>/ (e.g. memory-wiki, memory-core, channel plugins). The maintainers' stated default is "most features should be third-party plugins, not core changes." A change to a bundled extension is more defensible than a core change, but still expect pushback — if the PR adds a capability, preempt it in the body with a short "Why in core / why this extension owns it" paragraph (e.g. it's a thin read-only accessor over data the plugin already derives internally; a third-party plugin couldn't reach it without the unsafe-local escape hatch or duplicating logic).

Plugin manifest contract (bites silently). Every agent tool a plugin registers via api.registerTool must also be declared in that plugin's extensions/<name>/openclaw.plugin.json under contracts.tools (sorted array of tool names). If you add a tool in index.ts/src/tool.ts but forget the manifest, the plugin registry rejects the registration at runtime (plugin must declare contracts.tools for: <name>) and the test:contracts:plugins lane fails — but test:extension <name> does not catch it. This is exactly the kind of thing codex review flags and the per-extension test misses.

Validation commands for extension PRs (run remotely on Crabbox — see git caveat in Step 5):

pnpm build
pnpm tsgo:extensions          # typecheck extension source
pnpm tsgo:extensions:test     # typecheck extension tests
pnpm lint:extensions          # oxlint (0 warnings / 0 errors expected)
oxfmt --check extensions/<name>   # formatter (NOT prettier — repo uses oxfmt)
pnpm test:extension <name>    # that plugin's vitest suite
pnpm test:contracts:plugins   # cross-plugin contract lane (enforces the manifest above)
pnpm format:docs:check        # if the PR touches docs/

Repo tooling is oxfmt (.oxfmtrc.jsonc) + oxlint, tsgo for typecheck, vitest for tests, format-docs.mjs + markdownlint-cli2 for docs. There is no prettier — pnpm exec prettier will "not found". oxfmt <file> auto-fixes; oxfmt --check verifies.

Workflow

1. Identify the Problem in Production

Reproduce the issue on the local Pi 5 instance. Gather evidence:

# Journal logs with timestamps
sudo journalctl -u openclaw --since "1 hour ago" --no-pager | grep -i "error\|timeout\|abort"

# Cron job state
openclaw cron list 2>&1
openclaw cron get <job-id> 2>&1

2. Find the Relevant Source

Locate the compiled runtime to understand the code path:

# Find compiled modules
ls /usr/lib/node_modules/openclaw/dist/

# Search for constants/functions
grep -n "RELEVANT_CONSTANT" /usr/lib/node_modules/openclaw/dist/*.js

Then find the corresponding TypeScript source in the fork:

cd /tmp/openclaw-patch
grep -rn "RELEVANT_CONSTANT" src/

3. Validate the Fix Locally First

Patch the compiled JS in production to confirm the fix works before writing the PR:

# Edit the compiled file
sudo nano /usr/lib/node_modules/openclaw/dist/server-cron-*.js

# Clear Node compile cache (CRITICAL — stale bytecode will mask your patch)
sudo rm -rf /var/tmp/openclaw-compile-cache

# Restart the gateway
sudo systemctl restart openclaw

# Test
openclaw cron run <job-id>
sudo journalctl -u openclaw -f

4. Write the TypeScript Fix

Apply the equivalent change in the fork's TypeScript source:

cd /tmp/openclaw-patch
# Edit the relevant .ts files
# Follow existing code patterns (naming, exports, config structure)

Conventions observed:

• Constants use SCREAMING_SNAKE_CASE
• Config resolution functions follow resolve<PropertyName>() pattern
• Optional config fields use property?: type in interface definitions
• Watchdog/timeout values should be configurable via CronConfig when possible

5. Build & Test via Crabbox (Cloudflare)

Crabbox runs build and typecheck remotely on Cloudflare containers (standard-4: 4 vCPU, 12 GiB RAM). This satisfies the CONTRIBUTING.md requirement to "Run tests: pnpm build && pnpm check" before submitting. The .crabbox.yaml in the repo handles provider selection, dependency installation, and named jobs.

Remote-first test policy (default): run every test/validation that can run remotely on Crabbox, not on the Pi. Use local Pi execution only when the check requires local runtime state, credentials, or live channel integrations that cannot exist in an ephemeral Crabbox container.

Important: Crabbox can handle both build validation AND behavior proof generation. The quick-check job proves compilation + typecheck. The proof job builds the patched binary and runs targeted commands to produce real output for the PR body. For fixes that require runtime state (gateway running, cron jobs active), use local Pi production evidence instead.

Quick one-shot (build + typecheck)

cd /tmp/openclaw-patch
crabbox job run quick-check

This syncs your working tree to a fresh container, runs git init + pnpm install + pnpm build + typecheck. Completes in ~3-4 minutes.

Named jobs (from .crabbox.yaml)

Iterative development (warm box)

For rapid feedback while developing a fix. The huge win is not re-paying pnpm install + pnpm build (~8 min combined) on every run — pay it once, then iterate in seconds.

[!CRITICAL] Warm boxes have NO .git — git-dependent tests fail unless you init it. Ephemeral crabbox run (no --id) does git init/commit for you. The warm-box path (crabbox warmup + crabbox run --id) syncs via rsync and does NOT include .git — the workspace is not a git repo. Many contract tests enumerate files via git ls-files (their names read "lists … from git without walking …"). With no git they fall back to fs.readdirSync and fail en masse with expected "readdirSync" to not be called at all, but actually been called N times. In this session 8 of the test:contracts:plugins files failed this way — a pure environment artifact, nothing to do with the code. Always git init && git add -A && git commit in the warm-box workspace before running test:contracts:plugins (or any git-listing test). With git present the suite passed 986/986; without it, 8 spurious failures.

# Lease a persistent container — leases in ~1s ("warmup complete total=854ms")
crabbox warmup --provider cloudflare
# Returns an id (cbx_...) + slug (e.g. "brisk-crab"). Reuse the cbx_ id for all runs.

# --reclaim is REQUIRED if you run from a different cwd than where you warmed up
# (else: "lease cbx_... is claimed by repo <path>; use --reclaim").
# First run: set up git (MANDATORY, see callout) + deps
crabbox run --id cbx_... --reclaim --provider cloudflare -- bash -lc \
  'git init -q && git config user.email t@t.co && git config user.name t && git add -A && git commit -q -m snapshot && pnpm install --frozen-lockfile'

# Subsequent runs: build/test (git + deps persist on the box)
crabbox run --id cbx_... --reclaim --provider cloudflare -- bash -lc 'pnpm build && pnpm tsgo:extensions'
crabbox run --id cbx_... --reclaim --provider cloudflare -- bash -lc 'pnpm test:contracts:plugins 2>&1 | tail -40'

# Done — release. NOTE: `stop` takes the id POSITIONALLY, provider flag FIRST.
# `crabbox stop --id <x>` is WRONG (`flag provided but not defined: -id`).
crabbox stop --provider cloudflare cbx_...
# If you forget, it auto-releases after the 30m idle timeout — no 24/7 box needed.

Sizing / limits (asked-and-answered): default -type standard-4, -class beast are already the top tier. The ~15 min cutoff is a Cloudflare Worker wall-clock/stream limit, not CPU starvation — a bigger -type finishes faster (buying headroom) but does not raise the ceiling. -idle-timeout (default 30m) governs auto-release; the box is never idle mid-run so that's not what cuts long commands. For cross-session speed without a live box, see crabbox checkpoint (snapshot post-install/build) and crabbox cache warm.

set -e masks test failures. In a crabbox script, set -e + pnpm test ...; echo EXIT=$? aborts the whole script the instant the test returns non-zero — before your echo/log-dump runs, so you never see why it failed. Either drop set -e around the test, or write output to a file and always cat/tail it regardless of exit: pnpm test:contracts:plugins > /tmp/c.log 2>&1; echo "EXIT=$?"; tail -60 /tmp/c.log.

Flaky streaming — retry, don't panic. Transient cloudflare stream ended before completion and HTTP2 PROTOCOL_ERROR on upload happen; they are not real failures. Retry. To minimize exposure, split work into short commands (install / build / each test suite / proof) rather than one long chained run that risks the wall-clock and a mid-stream drop.

Troubleshooting

# Verify provider is healthy
crabbox doctor --provider cloudflare

# If a container hits stream timeout, use quick-check instead of full check
# Cloudflare containers have ~15 min stream limit — lint can exceed this on large repos

Limitations:

• ~15 min stream timeout — full lint (pnpm check) may exceed this; use quick-check for reliable runs
• 20 GB disk — fits the monorepo comfortably
• No SSH into the container — output streaming only
• Containers are ephemeral; warm boxes persist only while leased
• Full test suite (pnpm test) exceeds the timeout; use test-changed or run tests in upstream CI

6. Generate Behavior Proof via Crabbox

After quick-check passes, generate real behavior proof for the PR body. The proof job in .crabbox.yaml builds the patched binary and runs commands that demonstrate the fix works.

Customize the proof job

Edit .crabbox.yaml's proof job — replace the placeholder proof commands with fix-specific ones:

  proof:
    command: >-
      git config --global user.email x@x &&
      git config --global user.name x &&
      git init -q && git add -A && git commit -m x -q &&
      corepack enable &&
      pnpm install --frozen-lockfile &&
      pnpm build &&
      echo "=== PROOF START ===" &&
      node openclaw.mjs --version &&
      echo "--- fix-specific proof below ---" &&
      node openclaw.mjs <your-proof-command> &&
      echo "=== PROOF END ==="

What to put in proof commands (depends on fix type):

Run proof

cd /tmp/openclaw-patch
crabbox job run proof

Completes in ~3 min. Copy the output between === PROOF START === and === PROOF END === into the PR body's Real behavior proof section.

Warm box variant (for iterating on proof commands)

crabbox warmup --provider cloudflare
# First: setup + build
crabbox run --id <slug> -- 'git config --global user.email x@x && git config --global user.name x && git init -q && git add -A && git commit -m x -q && corepack enable && pnpm install --frozen-lockfile && pnpm build'
# Then iterate on proof commands quickly (no rebuild needed):
crabbox run --id <slug> -- 'node openclaw.mjs <proof-command>'
crabbox run --id <slug> -- 'node openclaw.mjs <another-proof-command>'
# Done
crabbox stop <slug>

Proof via a throwaway vitest spec (best for plugin/tool PRs — no build needed)

Importing a tool from dist/ for proof forces a full pnpm build (~slow, and the step most likely to hit the stream limit / a mid-stream drop). Avoid it: write a throwaway *.test.ts that invokes the real tool/function against a seeded fixture and console.logs the output, then run it with vitest — vitest transforms TS on the fly, so no build is required and it runs in seconds on a warm box.

// extensions/<name>/src/_proof.test.ts  — TEMP, do NOT commit
import { it } from "vitest";
import { createWikiOpenItemsTool } from "./tool.js";
import { resolveMemoryWikiConfig } from "./config.js";
// ...seed a temp vault on disk...
it("PROOF", async () => {
  const tool = createWikiOpenItemsTool(config);
  const out = await tool.execute("proof", {});
  console.log(out.content[0].text);
  console.log("details =", JSON.stringify(out.details));
});

crabbox run --id cbx_... --reclaim --provider cloudflare -- bash -lc \
  'pnpm exec vitest run extensions/<name>/src/_proof.test.ts 2>&1 | tail -60'

Create the spec locally (so it syncs to the box), capture the printed output for the PR, then delete it before committing (rm extensions/<name>/src/_proof.test.ts) — it must not land in the PR. vitest prints console.log under a stdout | … header.

When to use Pi instead of Crabbox

Use local Pi production evidence when the proof requires:

• A running gateway with real plugins/channels connected
• Active cron jobs with historical state
• Real message delivery (Telegram, Matrix, etc.)
• Network-dependent features (health checks against live services)
• Auth/credential resolution — stored OAuth tokens, API keys in the profile store, or cross-provider credential lookups (Crabbox containers have no stored credentials)

For these cases, follow Step 3's local validation approach and paste journal logs.

Lesson learned: Crabbox is excellent as a remote CI (build + typecheck confirmation without local toolchain), but for fixes involving credential resolution (e.g. openai/openai-codex cross-provider auth), the proof MUST come from the Pi where real credentials exist. A fresh container cannot exercise auth paths that depend on stored OAuth tokens. Plan accordingly — use quick-check for build validation, then patch the local Pi runtime (/usr/lib/node_modules/openclaw/dist/) for behavior proof. Remember the dist files use tabs for indentation; Python sed/replace scripts must account for this.

7. Commit and Push

git is still the right tool for local commits and pushing branches (no gh equivalent for these):

cd /tmp/openclaw-patch
git add -A
git commit -m "fix(cron): descriptive summary of the change

Longer explanation of the problem, root cause, and fix approach.
Include production evidence (durations, error messages) that proves the fix."

git push -u origin fix/descriptive-branch-name

8. Create the Pull Request

The PR body must include a Real behavior proof section. This is a hard requirement from upstream — unit tests, mocks, CI, lint, and typechecks alone do NOT satisfy it.

[!WARNING] The external-PR gate is a LITERAL heading match, not a content check. The Real behavior proof CI job runs scripts/github/real-behavior-proof-check.mjs → real-behavior-proof-policy.mjs, which requires the body to contain headings matching the exact regexes /^#{2,6}\s+What Problem This Solves\b/im and /^#{2,6}\s+Evidence\b/im. A semantically-identical but reworded heading (e.g. ## What problem does this solve?) fails the job even with perfect content. Use the verbatim headings ## What Problem This Solves and ## Evidence. The section must also be non-empty / not a placeholder (n/a, tbd, -, etc. count as missing). Maintainer/collaborator/bot PRs skip this gate; external PRs (like ours) do not.

[!NOTE] Editing the PR body/title: use gh api, not gh pr edit. gh pr edit resolves the author's org membership and fails on this token: GraphQL: … 'login' field requires … 'read:org' … token has only … [repo, workflow, …]. Update the body via the REST API instead (no org scope needed):

gh api -X PATCH repos/openclaw/openclaw/pulls/<N> -f body="$(cat body.md)"

Fetch the current body first (gh api repos/openclaw/openclaw/pulls/<N> --jq .body) if you're appending rather than replacing.

# gh is system-authenticated — no env export needed.
gh pr create \
  --repo openclaw/openclaw \
  --head kip-claw:fix/descriptive-branch-name \
  --title "fix(scope): short title" \
  --body "$(cat <<'EOF'
## Problem

Description of the issue with production evidence.

## Root Cause

What causes it in the source code (reference specific files/lines).

## Fix

What the PR changes and why.

## Real behavior proof

> Required by CONTRIBUTING.md. Must show real post-patch behavior from your own setup.

**Setup:** Cloudflare Container (standard-4: 4 vCPU, 12 GiB RAM, Node 24.x) via Crabbox
*(or: Raspberry Pi 5 (4GB, ARM64, Debian bookworm) if proof requires running gateway)*

**BEFORE (unpatched):**

<paste real production output — journal logs, health output, error messages>

**AFTER (patched):**

### 9. Search for Related Issues/PRs

Before or after submitting, search for existing work on the same problem:

```bash
gh search prs --repo openclaw/openclaw "relevant keywords" --state open
gh search issues --repo openclaw/openclaw "relevant keywords"

gh pr comment <number> --repo openclaw/openclaw --body "Production evidence from my environment: ..."
gh issue comment <number> --repo openclaw/openclaw --body "Cross-reference: #your-pr-number"

gh pr view --repo openclaw/openclaw <number>          # full PR detail + comments
gh pr checks --repo openclaw/openclaw <number>        # CI status
gh pr status --repo openclaw/openclaw                 # all your PRs at a glance
gh pr diff --repo openclaw/openclaw <number>          # confirm what reviewers see

cd /tmp/openclaw-patch
gh repo sync kip-claw/openclaw --source openclaw/openclaw
git fetch upstream
git rebase upstream/main
git push origin fix/branch-name --force-with-lease