chore(env): config-surface reduction tranche 4 — env-var cleanup (review request) by steipete · Pull Request #111584 · openclaw/openclaw

steipete · 2026-07-20T00:36:38Z

What Problem This Solves

The production env-var surface reached ~645 distinct OPENCLAW_* names, 444 of them undocumented, with no unified mechanism: test-only flags steered core path resolution (OPENCLAW_TEST_FAST was read inside src/config/paths.ts), build/dev controls lived in shipped runtime code, several vars existed twice under different names, and _ENV/_ARG indirection pairs named other variables instead of carrying values.

Tranche 4 of the config-surface reduction program (maintainer-directed). This PR is intentionally left unmerged for maintainer review.

Why This Change Was Made

Test-only controls isolated (refactor(env): isolate test-only controls): OPENCLAW_TEST_* and QA leak-set reads moved out of production paths into test seams or behind the central test-runtime detection in src/infra/env.ts; prod builds no longer consult them.
Build/dev controls isolated: dev-source-root, dist-entry, and similar build-time vars moved out of shipped runtime modules.
Indirection collapsed: process-identity _ENV/_ARG name-of-a-var pairs replaced with direct variables where both producer and consumer are in-repo.
Duplicates removed: OPENCLAW_CONFIG vs OPENCLAW_CONFIG_PATH and temp-dir aliases unified to the documented names.
Operator allowlist documented (docs/help/environment.md): the supported operator-facing set is now enumerated, with an explicit note that undocumented OPENCLAW_* names are internal and may vanish without notice.
Growth ratchet: scripts/check-env-var-count.mjs + tracked config/env-var-count-budget.txt (shrink-only, max-lines-ratchet pattern). Initialized at the post-cleanup count of 529 distinct production names (down from ~645).

User Impact

No documented operator-facing variable was renamed or removed (docs/help/environment.md set is treated as public contract). Behavior for production reads that remain is unchanged. Undocumented internal/test/build vars were removed or isolated; anyone depending on those was outside the documented contract, which this PR now states explicitly.

Config-surface metric (ClawSweeper): production OPENCLAW_* names ~645 → 529, direction: shrinking; new shrink-only budget prevents regrowth.

Evidence

Fresh autoreview on the final branch: clean, zero findings ("patch is correct").
node scripts/check-env-var-count.mjs: 529/529 green.
Focused tests across touched areas (paths, daemon/service-env, cron harnesses, plugins, tailscale, secrets fast-path) green during development; deadcode/lint/type lanes exercised in the fix commits (fix(env): remove stale provider helper import, fix(env): make ratchet sorting explicit, test(env): keep test seam in dead-code audit).
Hosted CI on this PR provides the authoritative lane run.

Note: Do not merge without maintainer review — this is the review vehicle for the env tranche of the config-reduction program (see #111142, #111382, #111527 for the prior tranches).

clawsweeper · 2026-07-20T02:38:18Z

Codex review: needs real behavior proof before merge. Reviewed July 20, 2026, 9:34 AM ET / 13:34 UTC.

Summary
The branch centralizes test-runtime detection, retires duplicate or internal environment-variable paths, moves ACPX lease identity from environment variables to wrapper arguments, documents an operator allowlist, and adds a shrink-only environment-name ratchet.

PR surface: Source -34, Tests +163, Docs +83, Config +1, Generated 0, Other +151. Total +364 across 73 files.

Reproducibility: not applicable. this is a cleanup and compatibility-boundary PR rather than a report of one reproducible broken behavior. The relevant before/after paths are operator configuration lookup and ACPX wrapper launching.

Review metrics: 1 noteworthy metric.

Production environment names: ~645 → 529 distinct OPENCLAW_* names (about 116 removed). This materially narrows the operator and integration compatibility surface, so the contract boundary needs explicit approval.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/commands/doctor/shared/pristine-startup-state.test.ts, serialized state: extensions/acpx/src/codex-auth-bridge.ts, vector/embedding metadata: packages/memory-host-sdk/src/host/config-utils.ts. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P1] Add redacted after-fix evidence for OPENCLAW_CONFIG_PATH resolution and an ACPX wrapper launch that verifies the new arguments.
Reconcile the reported failed check lanes against the current head.
Document the maintainer decision on whether any removed undocumented variables require preservation or migration.

Proof guidance:

[P1] Needs real behavior proof before merge: The PR body reports tests and CI but contains no inspectable after-fix live artifact proving operator configuration lookup or ACPX wrapper behavior; add redacted terminal output, runtime logs, or a recording before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] Existing deployments, scripts, or integrations may rely on environment variables that are undocumented but currently functional; documenting a narrower contract does not by itself establish that removal is safe for upgrades.
[P1] ACPX process launch and lease verification now consume identity from command arguments rather than environment variables, so platform-specific wrapper behavior needs live confirmation before merge.
[P1] The supplied check state includes failed required lanes whose head-specific causes need resolution before a merge decision.

Maintainer options:

Prove and ratify the compatibility boundary (recommended)
Before merging, obtain maintainer approval for the allowlist, add redacted live evidence for the changed operator and ACPX paths, and resolve the head-specific failed gates.
Accept documented-contract-only removals
A maintainer may explicitly accept breakage for all undocumented variables after confirming no supported plugin, installer, or operator workflow depends on them.
Pause the env cleanup tranche
Keep the branch unmerged if the project is not ready to define the environment compatibility boundary independently of the broader config-reduction program.

Next step before merge

[P1] A maintainer must decide the environment compatibility boundary and review real runtime evidence; this is not a narrow mechanical repair dispatch.

Maintainer decision needed

Question: Should OpenClaw treat the newly documented operator allowlist as the complete supported environment-variable compatibility contract, allowing all other removed or isolated OPENCLAW_* variables to stop working without migration?
Rationale: The branch intentionally converts a broad de facto runtime surface into an explicit supported contract; source-level cleanup cannot determine whether external operators or integrations rely on currently undocumented variables.
Likely owner: steipete — They authored the current and prior merged config-surface tranches and can provide the program history and intended compatibility boundary.
Options:
- Ratify the documented allowlist (recommended): Approve the documented variables as the supported operator contract, contingent on real runtime proof and reconciliation of the remaining check failures.
- Preserve selected legacy variables: Identify any externally relied-on variables that remain supported and retain them or provide a bounded migration path before merge.
- Pause this tranche: Hold the branch until the compatibility boundary is decided alongside the other config-surface reduction work.

Security
Cleared: No concrete security or supply-chain regression is established by the reviewed diff; ACPX lease transport remains a compatibility and runtime-proof concern rather than demonstrated secret exposure.

Review details

Best possible solution:

Have the responsible maintainer ratify the supported environment compatibility boundary, preserve or migrate any supported external use discovered in review, then add redacted real runtime proof for config-path resolution and ACPX wrapper launch before resolving the remaining failing lanes.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a cleanup and compatibility-boundary PR rather than a report of one reproducible broken behavior. The relevant before/after paths are operator configuration lookup and ACPX wrapper launching.

Is this the best way to solve the issue?

Unclear: centralizing test-only gates and reducing duplicate names is maintainable, but the proposed removal boundary is not ready to accept until maintainers explicitly confirm which environment variables remain supported.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 8d4d02a3cfa4.

Label changes

Label justifications:

P2: This is a broad but planned configuration-surface cleanup with meaningful upgrade implications rather than an active emergency.
merge-risk: 🚨 compatibility: The branch removes or changes behavior for previously readable environment variables and changes ACPX process identity transport.
merge-risk: 🚨 automation: It adds a new CI ratchet and changes changed-check planning, while the supplied head has unresolved check failures in adjacent automation and validation lanes.
rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body reports tests and CI but contains no inspectable after-fix live artifact proving operator configuration lookup or ACPX wrapper behavior; add redacted terminal output, runtime logs, or a recording before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

PR surface:

Source -34, Tests +163, Docs +83, Config +1, Generated 0, Other +151. Total +364 across 73 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	46	167	201	-34
Tests	10	215	52	+163
Docs	4	88	5	+83
Config	1	1	0	+1
Generated	2	6	6	0
Other	10	154	3	+151
Total	73	631	267	+364

What I checked:

Compatibility-sensitive environment contract: The branch declares only the documented operator-facing environment variables supported while removing or isolating many other OPENCLAW_* reads; this is a compatibility-boundary decision, not a routine rename. Public docs: docs/help/environment.md. (docs/help/environment.md:25, 58b9a1c631a6)
ACPX launch identity change: Lease and gateway identity are no longer injected through environment variables and are appended as portable wrapper arguments, so ACPX launch, verification, and diagnostic behavior need real runtime confirmation. (extensions/acpx/src/process-lease.ts:179, 58b9a1c631a6)
Central test-mode gate: The new helper enables OPENCLAW_TEST_FAST only when a Vitest/test runtime is detected; the PR applies this gate across production paths that previously consulted the flag directly. (src/infra/env.ts:119, 58b9a1c631a6)
Proof and gate state: The PR body reports focused tests and CI, but provides no inspectable after-fix terminal capture, runtime log, recording, or linked live artifact; the supplied check snapshot also includes unresolved failed documentation, plugin-SDK-baseline, topology, and compact-test lanes. (58b9a1c631a6)
Feature-history routing: The related merged config-surface tranches show the same author carried the recent program through merged commits 58452de and 783a5d2. (783a5d21cfc1)

Likely related people:

steipete: Authored this branch and the preceding merged config-surface reduction tranches that establish the compatibility and documentation approach used here. (role: config-surface program author and recent area contributor; confidence: high; commits: 58452de71188, 783a5d21cfc1, 58b9a1c631a6; files: docs/help/environment.md, src/infra/env.ts, extensions/acpx/src/process-lease.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (2 earlier review cycles)

reviewed 2026-07-20T02:10:52.294Z sha c516441 :: needs real behavior proof before merge. :: none
reviewed 2026-07-20T02:53:44.736Z sha c516441 :: needs real behavior proof before merge. :: none

steipete · 2026-07-21T13:25:43Z

Folded into #111527 as the single consolidated config-surface reduction PR: #111527

All environment-cleanup commits and their ratchet/docs coverage are now present on claude/openclaw-config-phase4. Closing this duplicate review vehicle; #111527 remains open and unmerged for maintainer review.

steipete requested a review from a team as a code owner July 20, 2026 00:36

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime scripts Repository scripts commands Command implementations docker Docker and sandbox tooling agents Agent runtime and tooling extensions: acpx extensions: codex labels Jul 20, 2026

steipete self-assigned this Jul 20, 2026

steipete added 9 commits July 19, 2026 18:17

refactor(env): isolate test-only controls

60d54af

refactor(env): isolate build and development controls

b161575

refactor(env): collapse process identity indirection

861ed9b

refactor(env): remove duplicate config and temp aliases

17089c2

docs(env): define the operator-facing allowlist

8e36ac8

ci(env): ratchet production variable count

b3984da

fix(env): remove stale provider helper import

649d80c

fix(env): make ratchet sorting explicit

8d3cba0

test(env): keep test seam in dead-code audit

c516441

steipete force-pushed the claude/openclaw-config-phase5 branch from 3c86554 to c516441 Compare July 20, 2026 02:05

openclaw-barnacle Bot added size: L maintainer Maintainer-authored PR labels Jul 20, 2026

clawsweeper Bot mentioned this pull request Jul 20, 2026

refactor(config): config-surface reduction tranche 3 — product consolidations (review request) #111527

Merged

8 tasks

clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jul 20, 2026

clawsweeper Bot added the merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. label Jul 20, 2026

steipete mentioned this pull request Jul 20, 2026

doctor --fix crashes on 'prepared model runtime publication timed out' before persisting config migrations #111627

Closed

test(env): cover ratchet growth and boundary; document surface budgets

58b9a1c

clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. labels Jul 20, 2026

steipete closed this Jul 21, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

chore(env): config-surface reduction tranche 4 — env-var cleanup (review request)#111584

chore(env): config-surface reduction tranche 4 — env-var cleanup (review request)#111584
steipete wants to merge 10 commits into
mainfrom
claude/openclaw-config-phase5

steipete commented Jul 20, 2026

Uh oh!

clawsweeper Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

steipete commented Jul 20, 2026

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented Jul 20, 2026 •

edited

Loading