docs(browser): document inbound upload refs

docs/cli/browser.md

@@ -205,6 +205,7 @@ File + dialog helpers:
 
 ```bash
 openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
+openclaw browser upload media://inbound/file.pdf --ref <ref>
 openclaw browser waitfordownload
 openclaw browser download <ref> report.pdf
 openclaw browser dialog --accept
@@ -215,6 +216,10 @@ Managed Chrome profiles save ordinary click-triggered downloads into the OpenCla
 downloads directory (`/tmp/openclaw/downloads` by default, or the configured temp
 root). Use `waitfordownload` or `download` when the agent needs to wait for a
 specific file and return its path; those explicit waiters own the next download.
+Uploads accept files from the OpenClaw temp uploads root and OpenClaw-managed
+inbound media, including `media://inbound/<id>` and sandbox-relative
+`media/inbound/<id>` references. Nested media refs, traversal, and arbitrary
+local paths remain rejected.
 When an action opens a modal dialog, the action response returns
 `blockedByDialog` with `browserState.dialogs.pending`; pass `--dialog-id` to
 answer it directly. Dialogs handled outside OpenClaw appear under

docs/tools/browser-control.md

@@ -191,6 +191,7 @@ openclaw browser select 9 OptionA OptionB
 openclaw browser download e12 report.pdf
 openclaw browser waitfordownload report.pdf
 openclaw browser upload /tmp/openclaw/uploads/file.pdf
+openclaw browser upload media://inbound/file.pdf
 openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
 openclaw browser dialog --accept
 openclaw browser dialog --dismiss --dialog-id d1
@@ -232,7 +233,12 @@ Notes:
 
 - `upload` and `dialog` are **arming** calls; run them before the click/press that triggers the chooser/dialog. If an action opens a modal, the action response includes `blockedByDialog` and `browserState.dialogs.pending`; pass that `dialogId` to respond directly. Dialogs handled outside OpenClaw appear under `browserState.dialogs.recent`.
 - `click`/`type`/etc require a `ref` from `snapshot` (numeric `12`, role ref `e12`, or actionable ARIA ref `ax12`). CSS selectors are intentionally not supported for actions. Use `click-coords` when the visible viewport position is the only reliable target.
-- Download, trace, and upload paths are constrained to OpenClaw temp roots: `/tmp/openclaw{,/downloads,/uploads}` (fallback: `${os.tmpdir()}/openclaw/...`).
+- Download and trace paths are constrained to OpenClaw temp roots: `/tmp/openclaw{,/downloads}` (fallback: `${os.tmpdir()}/openclaw/...`).
+- `upload` accepts files from the OpenClaw temp uploads root and
+  OpenClaw-managed inbound media. Managed inbound media can be referenced as
+  `media://inbound/<id>`, sandbox-relative `media/inbound/<id>`, or a resolved
+  path inside the managed inbound media directory. Nested media refs,
+  traversal, symlinks, hardlinks, and arbitrary local paths are still rejected.
 - `upload` can also set file inputs directly via `--input-ref` or `--element`.
 
 Stable tab ids and labels survive Chromium raw-target replacement when OpenClaw

extensions/browser/src/browser-runtime.ts

@@ -53,7 +53,11 @@ export {
   resolveGoogleChromeExecutableForPlatform,
 } from "./browser/chrome.executables.js";
 export { redactCdpUrl } from "./browser/cdp.helpers.js";
-export { DEFAULT_UPLOAD_DIR, resolveExistingPathsWithinRoot } from "./browser/paths.js";
+export {
+  DEFAULT_UPLOAD_DIR,
+  resolveExistingPathsWithinRoot,
+  resolveExistingUploadPaths,
+} from "./browser/paths.js";
 export { getBrowserProfileCapabilities } from "./browser/profile-capabilities.js";
 export { applyBrowserProxyPaths, persistBrowserProxyFiles } from "./browser/proxy-files.js";
 export {

extensions/browser/src/cli/browser-cli-actions-input/register.files-downloads.ts

@@ -3,9 +3,8 @@ import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runti
 import { callBrowserRequest, type BrowserParentOpts } from "../browser-cli-shared.js";
 import {
   danger,
-  DEFAULT_UPLOAD_DIR,
   defaultRuntime,
-  resolveExistingPathsWithinRoot,
+  resolveExistingUploadPaths,
   shortenHomePath,
 } from "../core-api.js";
 import { resolveBrowserActionContext, withBrowserActionTimeoutSlack } from "./shared.js";
@@ -13,11 +12,7 @@ import { resolveBrowserActionContext, withBrowserActionTimeoutSlack } from "./sh
 const DEFAULT_BROWSER_HOOK_TIMEOUT_MS = 120000;
 
 async function normalizeUploadPaths(paths: string[]): Promise<string[]> {
-  const result = await resolveExistingPathsWithinRoot({
-    rootDir: DEFAULT_UPLOAD_DIR,
-    requestedPaths: paths,
-    scopeLabel: `uploads directory (${DEFAULT_UPLOAD_DIR})`,
-  });
+  const result = await resolveExistingUploadPaths({ requestedPaths: paths });
   if (!result.ok) {
     throw new Error(result.error);
   }
@@ -91,7 +86,7 @@ export function registerBrowserFilesAndDownloadsCommands(
     .description("Arm file upload for the next file chooser")
     .argument(
       "<paths...>",
-      "File paths to upload (must be within OpenClaw temp uploads dir, e.g. /tmp/openclaw/uploads/file.pdf)",
+      "File paths to upload from OpenClaw temp uploads or managed inbound media (e.g. /tmp/openclaw/uploads/file.pdf or media://inbound/<id>)",
     )
     .option("--ref <ref>", "Ref id from snapshot to click after arming")
     .option("--input-ref <ref>", "Ref id for <input type=file> to set directly")

extensions/browser/src/cli/browser-cli-examples.ts

@@ -27,6 +27,7 @@ export const browserActionExamples = [
   "openclaw browser drag 10 11",
   "openclaw browser select 9 OptionA OptionB",
   "openclaw browser upload /tmp/openclaw/uploads/file.pdf",
+  "openclaw browser upload media://inbound/file.pdf",
   'openclaw browser fill --fields \'[{"ref":"1","value":"Ada"}]\'',
   "openclaw browser dialog --accept",
   'openclaw browser wait --text "Done"',

extensions/browser/src/core-api.ts

@@ -42,6 +42,7 @@ export {
   resolveBrowserConfig,
   resolveBrowserControlAuth,
   resolveExistingPathsWithinRoot,
+  resolveExistingUploadPaths,
   resolveProfile,
   resolveRequestedBrowserProfile,
   startBrowserControlServiceFromConfig,