PR #66831: fix(agents): respect OPENCLAW_WORKSPACE_DIR fallback

• Repository: openclaw/openclaw
• Author: briandevans
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/66831

Description (problem / solution / changelog)

Summary

• Problem: the default agent workspace fallback ignores OPENCLAW_WORKSPACE_DIR, so prompts and fallback workspace resolution can point at /home/node/.openclaw/workspace even when operators configured a different mounted workspace path.
• Why it matters: container and headless installs that bind a persistent workspace volume via OPENCLAW_WORKSPACE_DIR can miss bootstrap files and memory unless the agent manually rediscovers the env var.
• What changed: resolveDefaultAgentWorkspaceDir() now prefers OPENCLAW_WORKSPACE_DIR before OPENCLAW_PROFILE / default-home fallback logic, and regression coverage locks the behavior in at both the resolver seam and the default-agent consumer seam.
• What did NOT change (scope boundary): this does not change explicit per-agent workspace, agents.defaults.workspace, non-default agent fallback rules, or system-prompt rendering itself.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• Config / agent workspace resolution

Linked Issue/PR

• Closes #66786
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: resolveDefaultAgentWorkspaceDir() only considered OPENCLAW_HOME and OPENCLAW_PROFILE; it never read OPENCLAW_WORKSPACE_DIR, even though install docs use that env var as the source of truth for mounted workspaces.
• Missing detection / guardrail: there was no regression test asserting that the default-agent fallback path honors OPENCLAW_WORKSPACE_DIR.
• Contributing context (if known): the default agent fallback is shared across multiple entry points (prompt context, workspace-run fallback, CLI/gateway helpers), so the wrong path propagated broadly whenever config did not explicitly override it.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/workspace.test.ts, src/agents/agent-scope.test.ts
• Scenario the test should lock in: when OPENCLAW_WORKSPACE_DIR is set, the default workspace resolver and the default-agent workspace fallback both resolve to that path, even if OPENCLAW_PROFILE or OPENCLAW_HOME are also present.
• Why this is the smallest reliable guardrail: the bug lives in the shared fallback seam, so one resolver test plus one adjacent consumer test locks the contract in without pulling in a broader gateway or docker harness.
• Existing test that already covers this (if any): OPENCLAW_HOME fallback coverage existed; no prior OPENCLAW_WORKSPACE_DIR coverage did.

User-visible / Behavior Changes

Default-agent fallback workspace resolution now matches documented container/install behavior when OPENCLAW_WORKSPACE_DIR is configured. Prompts and fallback workspace consumers will point at the mounted workspace path instead of the baked-in home-directory default.

Repro + Verification

Environment

• OS: macOS (local validation), issue reported on Debian + Docker
• Runtime/container: Node 22 / pnpm
• Model/provider: N/A
• Integration/channel (if any): default agent workspace resolution / system prompt context
• Relevant config (redacted): OPENCLAW_WORKSPACE_DIR=/mnt/openclaw-state/.openclaw/workspace

Steps

1. Set OPENCLAW_WORKSPACE_DIR to a non-default workspace path.
2. Resolve the default agent workspace without an explicit configured workspace.
3. Observe the path injected into downstream default-agent consumers.

Expected

• Default fallback resolves to OPENCLAW_WORKSPACE_DIR.

Actual

• Before this PR, fallback ignored OPENCLAW_WORKSPACE_DIR and resolved to the home-directory default path.
• After this PR, fallback resolves to the configured workspace override.

Evidence

• Passing regression tests added for the resolver seam and default-agent consumer seam.
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: ran the focused agent/workspace Vitest slice locally and confirmed the new OPENCLAW_WORKSPACE_DIR assertions pass.
• Edge cases checked: confirmed the env override wins over OPENCLAW_PROFILE / OPENCLAW_HOME fallback logic, while existing OPENCLAW_HOME behavior remains covered.
• What you did not verify: I did not run a full Docker/EC2 end-to-end reproduction harness locally.

Review Conversations

• I will reply to and resolve every bot review conversation I address in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: changing the shared default-workspace resolver could affect other default-agent consumers.
  • Mitigation: the change is limited to an already-documented env var override, and I added a second seam test at the resolveAgentWorkspaceDir() consumer layer to catch shared-surface regressions.

AI Assistance

• AI-assisted: Yes (Codex)
• Testing degree: Fully tested for the affected seam
• Prompt/session summary: validated repo activity and contribution norms, selected #66786 as the smallest clear bug with no active competition, traced the bug to resolveDefaultAgentWorkspaceDir(), added a minimal env-override fix, reran focused tests and pnpm check, then opened this PR.
• Understanding confirmation: I understand this change only fixes default-agent fallback workspace resolution for the documented env override; it does not alter explicit workspace config precedence.

Verification Commands

• pnpm exec vitest run src/agents/workspace.test.ts src/agents/workspace.defaults.test.ts src/agents/agent-scope.test.ts src/agents/workspace-run.test.ts src/agents/system-prompt.test.ts
• git diff --check
• pnpm check

Changed files

• src/agents/agent-scope.test.ts (modified, +16/-0)
• src/agents/workspace.test.ts (modified, +10/-0)
• src/agents/workspace.ts (modified, +26/-1)