feat: add multi-workspace support to OpenClaw bridge

[khaliqgant]

Summary

• Add WorkspaceEntry and WorkspacesConfig types matching the broker's WorkspaceSource schema
• Add multi-workspace config layer (workspaces.json) with load/save/add/list/switch functions
• Add 3 new CLI commands: add-workspace, list-workspaces, switch-workspace
• Update setup to auto-register workspaces and wire RELAY_WORKSPACES_JSON + RELAY_DEFAULT_WORKSPACE to mcporter MCP env when multiple workspaces are configured
• Backward-compatible: single-workspace users see no change; multi-workspace activates only with 2+ entries
• Auto-migration: existing single .env config bootstrapped into workspaces.json on first add-workspace call

Test plan

• Run relay-openclaw setup <key> — verify workspaces.json is created alongside .env
• Run relay-openclaw add-workspace <second-key> --alias team-b — verify second entry added
• Run relay-openclaw list-workspaces — verify both entries shown with default marker
• Run relay-openclaw switch-workspace team-b — verify .env updated and message printed
• Verify RELAY_WORKSPACES_JSON env var is set in mcporter config when 2+ workspaces exist
• Verify single-workspace setup (no add-workspace) still works unchanged
• Type-check passes: npx tsc --noEmit

🤖 Generated with Claude Code

---

In general, to fix clear-text logging of sensitive information, avoid logging secrets at all, or log only non-sensitive identifiers (aliases, IDs) or properly redacted forms. Here, the problematic part is that label can fall back to a value derived from apiKey. Instead, we should construct a label that never uses apiKey directly, relying solely on non-sensitive metadata (alias or workspace ID), and if those are absent, use a generic placeholder. This keeps functionality (user feedback that a workspace was added) while ensuring no credential-derived string is logged.

Concretely, in runAddWorkspace in packages/openclaw/src/cli.ts, we should:

• Leave apiKey handling and addWorkspace call unchanged.
• After obtaining entry, build a label that prefers workspace_alias, then workspace_id, and otherwise falls back to a generic string like "(unnamed workspace)", rather than deriving anything from apiKey.
• Keep the rest of the logging intact, but now it will never include any part of the key.

No new imports or helper methods are needed; we just change the label computation.

In general, to fix clear-text logging of sensitive information, ensure that secrets (API keys, tokens, passwords, etc.) are never logged directly. If some user-facing indication is required, log only non-sensitive metadata (e.g., alias, workspace ID) or a minimally revealing, consistent representation (e.g., a constant mask, a hash, or an indication that a secret exists) that does not expose part of the actual secret string.

For this concrete case, the best fix without changing existing functionality is to stop slicing and showing the leading 12 characters of w.api_key. Instead, derive a non-sensitive representation, for example:

• Show only the length of the key, or
• Show a constant masked string like ******** or [redacted], or
• Show a deterministic hash (e.g., SHA-256) so users can distinguish keys without revealing them.

Given we must not add heavy new dependencies and must keep behavior close to current (showing that a key exists), a simple constant mask is adequate. We can replace:

const maskedKey = w.api_key.slice(0, 12) + '...';
...
console.log(`  ${alias}${wsId} — ${maskedKey}${defaultMarker}`);

with something like:

const maskedKey = '[api key hidden]';
...
console.log(`  ${alias}${wsId} — ${maskedKey}${defaultMarker}`);

This continues to show that a workspace has an associated API key while ensuring no part of the key is logged. All changes are within packages/openclaw/src/cli.ts around lines 287–293 and require no new imports or helpers.

In general, to fix clear-text logging of sensitive information, remove the sensitive value from the log entirely or replace it with a non-sensitive placeholder that does not reveal any part of the secret (or only reveals an explicitly approved, clearly non-sensitive fragment, like a generated identifier). Logs should convey that an operation succeeded without exposing credentials.

For this specific code, the best minimal-impact fix is: stop logging the Workspace key value (maskedApiKey) and instead log an informational message that tells the user how to retrieve or use the key without echoing it. This preserves functionality (the setup operation and API key issuance are unchanged) while eliminating sensitive data from the log. Concretely, in packages/openclaw/src/cli.ts, inside runSetup, remove the creation and logging of maskedApiKey (lines 115–116) and replace it with a message like “Workspace key generated. Keep it safe and share with other claws to join the same workspace.” That way, the user is still informed that a key exists and should be shared appropriately, but the key itself is not printed.

No new methods or imports are needed; the change is confined to adjusting the logging statements in runSetup.

In general, the fix is to ensure that any value that may contain an API key is either not logged at all or is logged only in a masked/obfuscated form. For this specific case, we should avoid ever storing the raw API key into default_workspace, and ensure that anything logged as a “workspace label” cannot resolve to the full key.

The best fix without changing existing functionality is to change normalizeWorkspaceLabel in config.ts so that if it would otherwise return workspace.api_key, it instead returns a masked version (e.g., first 12 chars + ..., consistent with runListWorkspaces). This ensures that config.default_workspace never contains the full key, removing the underlying taint. Then, in cli.ts, we can safely log config.default_workspace as-is. Additionally, we can mirror the masking behavior used elsewhere when logging the default workspace to make the intent explicit and keep behavior consistent.

Concretely:

• In packages/openclaw/src/config.ts, update normalizeWorkspaceLabel so that workspace.api_key is never returned in full; return a masked value instead.
• In packages/openclaw/src/cli.ts, when logging the default workspace, still log config.default_workspace but format it as a label (no change in semantics, but we know it is now safe). To be extra defensive and consistent with runListWorkspaces, we can compute and log the label the same way as right above: derive it from entry with slicing the API key when used as a fallback.

No new imports or external dependencies are required; only local helper logic and string slicing are involved.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 8 additional findings in Devin Review.

[devin-ai-integration]

🟡 SKILL.md documents wrong JSON shape for stored workspaces.json file

The SKILL.md at line 120 says "Stored shape (when ≥2 workspaces):" and then shows a JSON structure with "memberships" and "default_workspace_id" keys. However, the actual file written by saveWorkspacesConfig (packages/openclaw/src/config.ts:367) serializes a WorkspacesConfig object, which uses "workspaces" and "default_workspace" as its keys (packages/openclaw/src/types.ts:87-92). The memberships/default_workspace_id format is only used in the broker payload built by buildWorkspacesJson (packages/openclaw/src/config.ts:476-484), not in the stored file. Since SKILL.md is an agent-facing document, an agent following this documentation would produce or expect the wrong JSON structure when working with workspaces.json.

Suggested change

	Stored shape (when ≥2 workspaces):
	```json
	{
	"memberships": [
	{ "api_key": "rk_live_ABC", "workspace_alias": "team-a" },
	{ "api_key": "rk_live_DEF", "workspace_alias": "team-b", "workspace_id": "ws_..." }
	],
	"default_workspace_id": "team-a"
	}
	```
	Stored shape (when ≥2 workspaces):
	```json
	{
	"workspaces": [
	{ "api_key": "rk_live_ABC", "workspace_alias": "team-a" },
	{ "api_key": "rk_live_DEF", "workspace_alias": "team-b", "workspace_id": "ws_..." }
	],
	"default_workspace": "team-a"
	}

<!-- devin-review-badge-begin -->
<a href="https://app.devin.ai/review/agentworkforce/relay/pull/536" target="_blank">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
    <img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open in Devin Review">
  </picture>
</a>
<!-- devin-review-badge-end -->

---
*Was this helpful? React with 👍 or 👎 to provide feedback.*

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.

[devin-ai-integration]

🔴 Corrupt workspaces.json returns empty config instead of null, causing silent data loss

When workspaces.json exists but contains invalid JSON, loadWorkspacesConfig returns { workspaces: [], default_workspace: undefined } instead of null. This non-null empty config causes addWorkspace (packages/openclaw/src/config.ts:380) to skip the .env bootstrap path (which only runs when config is null), then proceed to overwrite the corrupt file with only the newly-added workspace entry. All previously-stored workspace data is silently lost.

The warning at line 359 says "Existing workspace config will not be modified" but this is incorrect — the returned empty config flows into addWorkspace → saveWorkspacesConfig, which overwrites the file. Returning null instead would trigger the .env bootstrap fallback, preserving at least the current single-workspace setup.

Suggested change

	return { workspaces: [], default_workspace: undefined };
	return null;

---

Was this helpful? React with 👍 or 👎 to provide feedback.