#19566: [AI-Assisted] feat: add openclaw sandbox run command

## Summary - **Problem:** Users lacked a way to manually test and debug sandbox environments without initiating a full agent session. - **Why it matters:** Simplifies dependency verification, permission debugging, and environment validation for developers and operators. - **What changed:** Added a new `openclaw sandbox run <command>` CLI command that mirrors agent-based `exec` tool execution. - **What did NOT change:** Existing agent execution logic and tool implementation remain untouched. ## Change Type (select all) - [ ] Bug fix - [x] Feature - [ ] Refactor - [x] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [x] Gateway / orchestration - [x] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [ ] API / contracts - [x] UI / DX - [ ] CI/CD / infra ## User-visible / Behavior Changes Added `openclaw sandbox run <command>` subcommand with support for: - `--agent <id>`: Target specific agent configurations (image, user, env). - `--session <key>`: Target specific session containers. - `--workdir <path>`: Auto-map host paths to container paths using existing mapping logic. ## Security Impact (required) - New permissions/capabilities? (`No`) - Secrets/tokens handling changed? (`No`) - New/changed network calls? (`No`) - Command/tool execution surface changed? (`Yes`) - Data access scope changed? (`No`) - **Risk + Mitigation:** Adds a CLI entry point to the existing tool execution surface. It enforces the same sandbox boundaries, user permissions, and filesystem policies as agent-invoked tools. ## Repro + Verification ### Environment - **OS:** Linux - **Runtime:** Docker/Podman - **Model/provider:** AI-assisted ([Gemini CLI](https://github.com/google/gemini-cli)) ### Steps 1. Run `openclaw sandbox run "ls -la"` to verify standard execution. 2. Run `openclaw sandbox run "whoami" --agent <custom-agent>` to verify user/image overrides. 3. Run `openclaw sandbox run "pwd" --workdir <host-path>` to verify host-to-container path mapping. ### Expected - Commands execute inside the designated container with correct isolation. - Exit codes are propagated to the host CLI. ### Actual - Commands executed successfully. - Exit codes correctly reflected status (e.g., `false` returns 1). - Path mapping correctly identified subdirectories within mounted volumes. ## Evidence - [x] E2E tests passing: `src/commands/sandbox-run.e2e.test.ts` - [x] Manual verification logs available in branch history. ## Human Verification (required) - **Verified scenarios:** Standard execution, agent image overrides, read-only workspace enforcement (`workspaceAccess: ro`), host-to-container path mapping. - **Edge cases checked:** Non-zero exit codes, large output handling, non-existent workdir warnings. - **What you did NOT verify:** Browser-specific container execution (focused on standard code sandboxes). ## Compatibility / Migration - Backward compatible? (`Yes`) - Config/env changes? (`No`) - Migration needed? (`No`) ## Failure Recovery (if this breaks) - **Revert:** Revert changes to `src/cli/sandbox-cli.ts` and delete `src/commands/sandbox-run.ts`. ## Risks and Mitigations - **Risk:** Accidental exposure of host paths via `--workdir`. - **Mitigation:** Uses existing `resolveSandboxWorkdir` logic which validates paths against the sandbox root and falls back to safe defaults if unauthorized.