#4222: fix: canvas root should respect agents.defaults.workspace
gateway
Cluster:
Workspace Path Fixes
## Summary
When `canvasHost.root` is not explicitly configured, the canvas directory defaults to `~/clawd/canvas` regardless of the user's `agents.defaults.workspace` setting. This PR derives the default from the workspace directory instead, so users with a custom workspace (e.g. `~/Bot`) get `~/Bot/canvas` automatically.
Closes #2282
- Pass `defaultWorkspaceDir` into `createGatewayRuntimeState`
- Use `path.join(defaultWorkspaceDir, "canvas")` as fallback when `canvasHost.root` is unset
- Update doc comment in `CanvasHostConfig` to reflect the new default
Backward compatible: if workspace is not customized, the default remains `~/clawd/canvas`.
## Test plan
- Set `agents.defaults.workspace` to a custom dir (e.g. `~/Bot`), leave `canvasHost.root` unset → canvas mounts at `~/Bot/canvas`
- Explicitly set `canvasHost.root` → that value is used (unchanged behavior)
- No workspace or canvas config → defaults to `~/clawd/canvas` (unchanged behavior)
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This change threads the resolved default agent workspace directory (`defaultWorkspaceDir`) into gateway runtime initialization and uses it to derive the canvas host root when `cfg.canvasHost.root` is unset. Specifically, `createGatewayRuntimeState` now falls back to `path.join(defaultWorkspaceDir, "canvas")` rather than an implicit hardcoded workspace path, so users customizing `agents.defaults.workspace` get a matching default canvas directory.
The behavior for an explicitly configured `canvasHost.root` remains unchanged; only the implicit default changes.
<h3>Confidence Score: 4/5</h3>
- This PR is low risk and changes a single default path derivation without altering explicit configuration behavior.
- Changes are localized to gateway startup/runtime wiring and a nullish-coalescing fallback for `canvasHost.root`; the main risk is around documentation clarity and how “workspace” is defined (default agent vs per-agent) rather than runtime correctness.
- src/config/types.gateway.ts (comment accuracy)
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#17757: fix(agents): resolve relative workspace paths against state dir, no...
by Phineas1500 · 2026-02-16
77.3%
#22917: fix: Use agent's configured workspace when spawned as subagent
by jriff · 2026-02-21
76.1%
#23085: fix(workspace): respect OPENCLAW_STATE_DIR for workspace paths, fix...
by charojo · 2026-02-22
75.2%
#7851: feat: secure sandbox defaults for new installs
by ichbinlucaskim · 2026-02-03
74.8%
#19560: docs: refactor agent workspace default location & bootstrap configu...
by ashinkuniyil · 2026-02-17
74.5%
#11740: fix(gateway): remove IP-based canvas auth fallback
by coygeek · 2026-02-08
74.1%
#10185: fix: pass effective workspace as cwd to Pi SDK createAgentSession
by Yida-Dev · 2026-02-06
74.1%
#17488: fix(agents): skip workspace deletion when shared with other agents
by soumikbhatta · 2026-02-15
74.1%
#20991: fix(sandbox): fall back to gateway UID:GID when no user is configur...
by cluster2600 · 2026-02-19
74.0%
#4467: fix: DEFAULT_SANDBOX_WORKSPACE_ROOT respects STATE_DIR
by Aphroq · 2026-01-30
73.7%