OpenClaw + yt-dlp: Media Metadata, Subtitles and Bounded Downloads

What the install actually does

yt-dlp is a local CLI tool, not a remote service, so nothing is proxied through a third party. The dashboard downloads one pinned release of the standalone Linux build, verifies it against a recorded SHA-256 checksum, and places it in a versioned directory under the instance's tools/ path. Alongside the binary it writes a managed skill so the agent discovers the exact command path instead of guessing at a global yt-dlp that does not exist in the image.

Both the tool directory and the skill directory carry a marker file identifying the version the dashboard installed. That marker is what makes reinstall idempotent and what stops an upgrade from silently replacing a directory the dashboard does not own.

1. Install from Dashboard Tools

Open Dashboard Tools, pick a running instance, then install yt-dlp from its card. The install runs inside the container as a background job and reports installing, then installed or failed. No configuration fields are required — there is no endpoint and no credential, because the tool runs locally.

2. Ask for metadata before asking for bytes

Metadata extraction is fast, cheap, and answers most questions without writing a file at all. Ask the agent for a title, duration, available formats, or subtitle languages first.

The binary lives at a versioned managed path — on OpenClaw that is /home/node/.openclaw/tools/yt-dlp-<version>/yt-dlp, and the installed skill records it, so the agent calls the pinned binary rather than a global command that does not exist in the image. The examples below use yt-dlp as shorthand for that full path.

# Metadata only, no download
yt-dlp --dump-single-json URL

# Available formats for a single item
yt-dlp -F URL

The managed skill tells the agent to prefer --dump-single-json when only metadata is needed, which keeps the response inside the chat instead of filling the instance disk.

3. Keep downloads inside the workspace

Downloads belong under the instance workspace, where the files are visible to the file manager, to static site hosting, and to any later agent turn. The managed skill defaults to a downloads directory in the workspace unless you name another workspace path.

# One item, pre-muxed format, into the workspace
yt-dlp -f 'best[ext=mp4]/best' -o 'downloads/%(title)s.%(ext)s' URL

# Subtitles without the video
yt-dlp --write-auto-subs --skip-download URL

The FFmpeg constraint

This is the failure people hit first. yt-dlp's highest-quality selections usually mean a separate video stream and a separate audio stream that must be merged, and the merge is FFmpeg's job. The lightweight install does not bundle FFmpeg, so those selections fail at the post-processing step after a long download. Requesting a single pre-muxed format avoids the whole class of error, and the managed skill encodes that preference so the agent does not rediscover it every time.

Bounded by default, on purpose

• One item per request. A playlist or channel URL should only expand when the user explicitly asks for it.
• Instance disk is finite. Large video files compete with the workspace, logs, and the agent's own storage.
• Only fetch media the user owns or is authorized to download; respect each site's terms and applicable copyright.
• Keep the pinned version. Self-update breaks the managed marker and desynchronizes the dashboard's install state.

When the download is the wrong tool

If the goal is reading a page rather than saving media, a crawler is a better fit — see the Crawl4AI guide. If the goal is turning an existing document into text the model can read, use MarkItDown instead of downloading and re-parsing files by hand.

Frequently asked questions

Related guides

• yt-dlp in the tools catalog
• How OpenClaw skills install
• OpenClaw + Crawl4AI