What this page covers: workspace folders, not model APIs
Searches for “OpeClaw local files” or “workspace folder” usually mean the client already opens, but connecting a machine directory fails—permission prompts finish and reads still fail, or the path looks right yet access is denied.
This article covers local-folder / workspace attach, in-app and OS permissions, path checks, and a read-failure order. It does not cover Ollama / LM Studio Base URLs or how to install Skills packages—those queries have their own pages.
Exact menu names, button copy, and grant granularity follow your current Settings UI and built-in permission dialogs. This page does not invent unpublished “one-click mount entire disk” features.
Before attach: pick the workspace, then grant access
Treat the workspace as the boundary directory you allow OpeClaw to read or write—not a random Desktop shortcut. A wrong path makes every later “cannot read file” look like a product bug.
Fixed order: confirm the folder exists and you can open it in Finder / Explorer → open the Settings entry for workspace / local folder / project directory (labels vary by build) → pick the folder with the system file picker → when a built-in permission dialog appears, read it before allowing.
Release status and installer source start on the download page. A half-updated or wrong build can hide the entry or scramble grant state—verify version before re-picking the same path forever.
- Open the target folder directly in the OS file manager first.
- Avoid granting an entire Downloads tree and hoping nested projects appear.
- On managed PCs that block document access, ask IT—do not disable antivirus as a workaround.
Permission dialogs: keep the scope small
Attaching a local folder often triggers an in-app prompt and may involve OS folder access (macOS Privacy & Security, Windows Controlled Folder Access, and similar). Follow the dialog you see; do not assume hidden toggles that are not shown.
Prefer: authorize only the current project directory; widen one level when subfolders are required; keep secrets, credentials, and production configs out of the default writable workspace. Before “Allow always” or full-disk style options, confirm the dialog or release notes actually require them and that you can revoke later in OS settings.
If the dialog flashes away and Settings show no granted path, quit the client fully, reopen, and re-run folder selection. If it stays blank, check the update-fail guide for leftover config before wiping the whole machine.
Path checks when files will not read
First: was the folder moved, renamed, or left as a cloud “online-only” placeholder while the workspace still points at an old absolute path? Second: case, spaces, and non-ASCII paths can amplify script-step failures—trust the path returned by the file picker instead of hand-typing.
Third: symlinks and shortcuts—confirm whether you selected the link or the real directory; a broken link looks like “entry exists, content empty.” Fourth: another app may lock the file (Office, sync clients)—close the lock and retry.
Minimum proof: drop a short, non-sensitive text file in the authorized folder and run a read-only step on that file only. When that works, expand to the real project. Pointing at the whole disk first makes failures untraceable.
How this splits from Skills, local LLMs, and updates
Directory granted and short text readable, but an extension will not install or enable → use the Skills install guide; this page will not repeat source checks.
Files readable, but the model will not connect or you need Ollama / LM Studio → use the local LLM setup guide; 401/429 go to the API key article. Do not edit Base URL inside workspace settings.
Folder entry missing, grants wiped after an update, or a half-finished update → start with update failure / clean reinstall. Moving machines or reinstalling and needing Providers plus the config folder → config backup & migrate. Scenario boundaries → FAQ. Installer entry points always return to Download.
Local file attach table (no new claims)
This table only restates the order above. It does not change “pick workspace before grants,” “no invented mount features,” or the split that keeps model APIs and Skills on their own URLs.
| Symptom | Safer action | Common mistake |
|---|---|---|
| No attach entry in Settings | Match current build UI and Download page | Running a chat-group “universal mount” script |
| Still cannot read after prompts | Re-select folder; check OS privacy grants | Granting full disk without rechecking the path |
| Path listed but content empty | Check moves, sync placeholders, symlinks | Blaming the model and rotating API keys |
| Only one Skill fails to read | Skills guide for extra permissions | Deleting and recreating the same folder forever |
| Grants gone after update | Update-fail guide, then re-attach | Reinstalling from unknown mirrors to “restore paths” |
Menu names, dialog copy, and grantable scope follow the current client; this page does not promise unpublished features or support SLAs.
Local folders & workspace FAQ
OpeClaw cannot read local files—is the model API wrong?
Usually not. Start with whether the workspace path still exists, whether the permission dialog was granted, and whether the target is inside the allowed scope. Model connection or 401/429 issues belong on the local-LLM and API key guides.
Does authorizing a local folder mean full-disk access?
It should not by default. Confirm each built-in permission prompt and grant only the directories the task needs. Menu labels and grant scope follow your current build—avoid “Allow always” if you cannot revoke it later.
Skills are installed but project files still fail—which guide first?
Confirm the workspace folder is selected and OS permissions allow it, then check whether that Skill needs extra path or script rights. Source and install steps stay on the Skills article; this page covers directories and file reads.
After an update, the old folder suddenly cannot be accessed—what now?
Compare About-page version with the download page, rule out a half-finished update, then re-run folder selection and permission prompts. Channel problems belong on the update-fail guide—do not grab unknown installers first.
Config restored on a new PC but every workspace path is dead—what next?
Config usually stores path references only. Re-select the real folders and finish permission dialogs on the new machine. How to back up and migrate the whole config folder is on the config backup guide; this page covers directories and reads.
Use this with an OpeClaw workflow
Check the current OpeClaw download status first, then save this guide as part of your setup, review, or troubleshooting workflow.