```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

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

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

- `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

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 {

} from "./browser/client.js";

export { resolveBrowserConfig, resolveProfile } from "./browser/config.js";

export { DEFAULT_AI_SNAPSHOT_MAX_CHARS } from "./browser/constants.js";

export { DEFAULT_UPLOAD_DIR, resolveExistingPathsWithinRoot } from "./browser/paths.js";

export { resolveExistingUploadPaths } from "./browser/paths.js";

export { getBrowserProfileCapabilities } from "./browser/profile-capabilities.js";

export { applyBrowserProxyPaths, persistBrowserProxyFiles } from "./browser/proxy-files.js";

export {

};

});

const pathValidationMocks = vi.hoisted(() => ({

resolveExistingUploadPaths: vi.fn<

(args: {

requestedPaths: string[];

}) => Promise<{ ok: true; paths: string[] } | { ok: false; error: string }>

>(async ({ requestedPaths }) => ({

ok: true as const,

paths: requestedPaths,

})),

}));

const sessionTabRegistryMocks = vi.hoisted(() => ({

touchSessionBrowserTab: vi.fn(),

trackSessionBrowserTab: vi.fn(),

},

readStringParam,

readStringValue,

resolveExistingPathsWithinRoot: vi.fn(async ({ requestedPaths }) => ({

ok: true,

paths: requestedPaths,

})),

resolveExistingUploadPaths: pathValidationMocks.resolveExistingUploadPaths,

resolveNodeIdFromList: (nodes: Array<Record<string, unknown>>, requested: string) => {

const node = nodes.find(

(entry) => entry.nodeId === requested || entry.displayName === requested,

expect(browserActionsMocks.browserAct).toHaveBeenCalledTimes(1);

});

});

describe("browser tool upload inbound media fallback (#83544)", () => {

beforeEach(resetBrowserToolMocks);

afterEach(() => vi.restoreAllMocks());

it("resolves upload paths before arming the file chooser", async () => {

const inboundPath = "/home/user/.openclaw/media/inbound/report.pdf";

pathValidationMocks.resolveExistingUploadPaths.mockResolvedValue({

ok: true,

paths: [inboundPath],

});

browserActionsMocks.browserArmFileChooser.mockResolvedValue({ ok: true });

const tool = createBrowserTool();

const result = await tool.execute?.("call-upload-1", {

action: "upload",

paths: [inboundPath],

ref: "file-input-1",

});

expect(pathValidationMocks.resolveExistingUploadPaths).toHaveBeenCalledWith({

requestedPaths: [inboundPath],

});

expect(result?.content[0]).toHaveProperty("type", "text");

});

it("rejects files outside both uploads and inbound media directories", async () => {

pathValidationMocks.resolveExistingUploadPaths.mockResolvedValue({

ok: false as const,

error: "path outside allowed directories",

});

const tool = createBrowserTool();

await expect(

tool.execute?.("call-upload-2", {

action: "upload",

paths: ["/etc/passwd"],

ref: "file-input-1",

}),

).rejects.toThrow("path outside allowed directories");

});

});

import {

type AnyAgentTool,

type NodeListNode,

DEFAULT_UPLOAD_DIR,

BrowserToolSchema,

applyBrowserProxyPaths,

browserAct,

readStringParam,

readStringValue,

resolveBrowserConfig,

resolveExistingUploadPaths,

resolveRuntimeImageSanitization,

resolveExistingPathsWithinRoot,

resolveNodeIdFromList,

resolveProfile,

selectDefaultNodeFromList,

if (paths.length === 0) {

throw new Error("paths required");

}

const uploadPathsResult = await resolveExistingPathsWithinRoot({

rootDir: DEFAULT_UPLOAD_DIR,

requestedPaths: paths,

scopeLabel: `uploads directory (${DEFAULT_UPLOAD_DIR})`,

});

if (!uploadPathsResult.ok) {

throw new Error(uploadPathsResult.error);

const resolvedResult = await resolveExistingUploadPaths({ requestedPaths: paths });

if (!resolvedResult.ok) {

throw new Error(resolvedResult.error);

}

const normalizedPaths = uploadPathsResult.paths;

const normalizedPaths = resolvedResult.paths;

const ref = readStringParam(params, "ref");

const inputRef = readStringParam(params, "inputRef");

const element = readStringParam(params, "element");