Mount Data Directories

Pinchy agents can only access files inside the /data/ directory in the container. To make your documents available, you mount host directories into subdirectories of /data/ using Docker volumes.

The /data/ convention

All agent-accessible files live under /data/ inside the OpenClaw container. Pinchy's pinchy-files plugin runs inside OpenClaw and reads files from that path. The pinchy-data named volume is mounted there by default, but you can bind-mount additional host directories as subdirectories.

This convention provides a clear boundary: anything under /data/ is potentially accessible to agents (depending on their permissions), and nothing outside /data/ is.

Adding volumes in docker-compose.yml

To mount a local folder, add a bind mount under the openclaw service's volumes section:

services:
  openclaw:
    volumes:
      - openclaw-config:/root/.openclaw
      - openclaw-secrets:/openclaw-secrets
      - pinchy-workspaces:/root/.openclaw/workspaces
      - openclaw-extensions:/root/.openclaw/extensions
      - pinchy-data:/data
      - pinchy-pdf-cache:/var/cache/pinchy-files
      # Add your data directories here:
      - /path/on/host/hr-policies:/data/hr-policies:ro
      - /path/on/host/engineering-docs:/data/engineering-docs:ro

The :ro suffix mounts the directory as read-only, which is recommended since agents only need to read files.

After updating docker-compose.yml, restart the OpenClaw container:

docker compose up -d --no-deps openclaw

Examples

Local folder

Mount a folder from your host machine:

volumes:
  - /home/admin/company-docs:/data/company-docs:ro

NAS or network drive

If your NAS is mounted on the host at /mnt/nas/shared, mount a subdirectory:

volumes:
  - /mnt/nas/shared/legal:/data/legal:ro
  - /mnt/nas/shared/finance:/data/finance:ro

Mount the share for the container user. The pinchy container runs as uid 999. A network share mounted without an owner mapping belongs to root, so Pinchy can't read it — and indexing then fails with a permission error that never mentions the mount. For an SMB/CIFS share, pass uid=999,gid=999:

//fileserver/share/suppliers /mnt/suppliers cifs ro,_netdev,credentials=/etc/smb.cred,uid=999,gid=999,iocharset=utf8,vers=3.0 0 0

_netdev matters just as much: it holds the mount back until the network is up, so a reboot doesn't leave the containers pointing at an empty directory.

Mount the share read-only — ro on both the host mount and the Compose volume. Pinchy never writes to /data/, and a read-only mount makes that structural rather than a promise.

Multiple directories

You can mount as many directories as you need:

volumes:
  - /srv/docs/hr:/data/hr:ro
  - /srv/docs/engineering:/data/engineering:ro
  - /srv/docs/compliance:/data/compliance:ro

Each mounted directory appears as a separate selectable option in the Permissions tab when configuring an agent.

How directories appear in the UI

When you configure an agent's permissions in the Permissions tab of Agent Settings, Pinchy scans /data/ for subdirectories and displays them as selectable options. Each mounted directory shows up by name — for example, /data/hr-policies appears as "hr-policies".

Only top-level subdirectories of /data/ are listed. Nested directories within those are accessible to the agent but are not listed separately in the directory picker.

Verifying your mounts

To check that your directories are correctly mounted, you can exec into the running container:

docker compose exec openclaw ls /data/

You should see your mounted directories listed.

Supported file types

Two different paths read the files under /data/, and they support different formats. The distinction matters when you plan a corpus, so it's worth knowing before you mount one.

Knowledge Base search (knowledge_search) indexes text-based PDFs, plain text and Markdown. Scanned PDFs and Office documents are not indexed today — see Create a Knowledge Base Agent — Scope in this release.

Reading a file directly (the agent's file tools) additionally handles Word documents (.docx) and scanned PDFs, which are analyzed using the configured model's vision capabilities.

So a scanned certificate under /data/ can be opened and read on request, but it won't come back as a search hit — the agent has to be pointed at it. If a large part of your corpus is scans, the reindex report tells you so: it counts them under unsearchable rather than indexed.

Knowledge Base vs. workspace files

Directories mounted under /data/ are admin-curated and read-only for agents — they hold your organization's reference documents and are not writable by agents under any configuration.

This is intentional: it keeps your authoritative documents separate from anything an agent might generate or derive. An agent that has the Write files permission saves results to its own workbench/ workspace, not to /data/. (The legacy uploads/ directory stays writable for backward compatibility, but new agents should write to workbench/.) See Agent Permissions for details on the workspace write capability.