#Agent refers to documentation

1 messages · Page 1 of 1 (latest)

naive radishBOT
#

You don’t need to “load” the Git docs into context at all. OpenClaw only injects the workspace bootstrap files (AGENTS.md, SOUL.md, etc.). Your copied documentation can just sit on disk and the agent will read files on-demand when needed via the read tool (and optionally exec to search).

Option A (simplest): put the docs inside the agent workspace

  1. Copy your Git docs into your agent workspace, e.g.
  • ~/.openclaw/workspace/docs/git/...
  1. Add a tiny hint to AGENTS.md (don’t paste the docs themselves), e.g.
  • “Git docs live in ./docs/git. When answering Git questions, search there first and cite filenames.”

Nothing under ./docs/git is automatically added to the prompt; it’s only read if the agent calls read.

Option B (recommended if you use sandboxing): bind-mount the docs read-only

If you have sandboxing on and workspaceAccess: "none", the read tool is sandbox-rooted, so your host folder won’t be visible unless you mount it.

Add a read-only bind mount:

# 
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: [
            "/absolute/path/to/your/git-docs:/docs/git:ro",
          ],
        },
      },
    },
  },
}

Then put in AGENTS.md (or a skill) that the docs are at /docs/git.

#

Docs: https://docs.openclaw.ai/gateway/sandboxing

Make sure the agent is allowed to use the right tools

  • Minimum: allow read (group:fs)
  • Nice-to-have: allow exec (group:runtime) so it can rg/search quickly

Docs: https://docs.openclaw.ai/tools (tool allow/deny + groups)

Optional: wrap the “where are the docs + how to use them” into a skill

Create a small skill (shared or per-workspace) that just tells the agent where the docs are and to consult them before answering. Skills are prompt instructions only — they still won’t load your docs into context.

Docs: https://docs.openclaw.ai/tools/skills

If you tell me (a) whether you’re sandboxing and (b) the path where you stored the Git docs + whether they’re HTML or Markdown, I can suggest the cleanest mount location + the exact AGENTS.md/skill snippet.

naive radishBOT
#

Best practice (not sandboxing): store the docs inside the agent’s workspace, and give the agent a small, explicit retrieval rule (“search + open the relevant file(s) before answering”). Whether that rule lives in AGENTS.md or a Skill is mostly about maintainability.

My usual recommendation is:

  1. Docs live in the workspace (so file access is predictable and doesn’t widen the blast radius)
  2. The retrieval rule lives in a Skill (clean, reusable, doesn’t bloat AGENTS.md)
  3. AGENTS.md only contains a 1–2 line pointer (“Git docs are in …; use the git-docs skill workflow”)

You can do only (A) AGENTS.md and skip the skill; it’s fine for a single agent and fastest to set up.

Step 0 — confirm your workspace path

Default is ~/.openclaw/workspace, but check yours:

# 
openclaw config get agents.defaults.workspace
# and if you have per-agent workspaces:
openclaw config get agents.list

Docs: https://docs.openclaw.ai/cli/config

Step 1 — put the Git docs under the workspace

Pick a stable folder name. Example:

mkdir -p ~/.openclaw/workspace/docs/git
# then copy your docs in (example)
# 
cp -R /path/to/your/git-docs/* ~/.openclaw/workspace/docs/git/

Why: OpenClaw does not auto-load that directory into prompt context; it’s only used when the agent calls read.

Option A (quick + good enough): put the rule in AGENTS.md

Edit ~/.openclaw/workspace/AGENTS.md and add something like:

## Local reference docs

Git documentation is available at: `docs/git/` (relative to this workspace).
# 
When answering Git questions:
1) Search the local docs first (prefer `rg` if available).
2) Open the most relevant file(s) with the `read` tool.
3) Quote/cite filenames when possible. If you didn’t check the docs, say so.

That’s it. This is the lowest-friction setup.

Option B (my preferred long-term): create a Skill for the retrieval workflow

B1) Create the skill folder

If you want it only for this agent/workspace:

# 
mkdir -p ~/.openclaw/workspace/skills/git-docs-local

If you want it shared across all agents on this machine:

mkdir -p ~/.openclaw/skills/git-docs-local

Docs: https://docs.openclaw.ai/tools/skills

B2) Create SKILL.md

Create SKILL.md in that folder with:

# 
---
name: git-docs-local
description: Use local Git docs in docs/git/ as the source of truth when answering Git questions.
user-invocable: false
---

When the user asks about Git (commands, flags, behaviors, workflows):

- The local Git docs live at `docs/git/` (relative to the workspace).
- Do NOT guess when the docs likely contain the answer.
- First, locate the right page (use `exec` + ripgrep if allowed; otherwise browse likely files).
- Then use the `read` tool to open the relevant file(s).
- Answer using what you found; include the filename/path you used.

B3) (Optional) Add one small pointer in AGENTS.md

# 
Git docs are in `docs/git/`. Follow the `git-docs-local` skill workflow when answering Git questions.

That keeps AGENTS.md clean and makes the behavior portable.

One practical note: searching

To “access relevant files when necessary”, the agent needs a way to find them:

  • If you allow exec, having rg installed makes this dramatically better (search by keyword, then read).
  • If you don’t allow exec, it can still work, but you’ll want the docs to have a clear TOC/index structure.

If you tell me whether you currently allow the exec tool (and whether rg is installed), I can recommend the cleanest “search” setup for your risk tolerance.

naive radishBOT
#

You don’t have to move them for this to work (any agent can usually read an absolute path on the host when you’re not sandboxing), but if you want “available to all agents” to be clean + future-proof, I’d move them out of one agent’s workspace into a shared location and then create a shared skill in ~/.openclaw/skills.

Below are copy/paste commands for the “recommended” setup.

0) Sanity checks (see what you’re working with)

openclaw config get agents.defaults.workspace
openclaw config get agents.list
openclaw config get tools.fs.workspaceOnly
  • If tools.fs.workspaceOnly comes back true, stop and tell me — that setting intentionally blocks reads outside each agent’s workspace, so “one shared folder for all agents” needs a different approach.
#

1) Copy your docs into a shared folder (non-destructive)

I’m assuming your current docs are here:

  • OLD=/home/claw/.openclaw/workspace/docs

And we’ll put shared docs here:

  • NEW=/home/claw/.openclaw/shared/docs/git

Commands:

OLD="/home/claw/.openclaw/workspace/docs"
NEW="/home/claw/.openclaw/shared/docs/git"
# 
mkdir -p "$NEW"

# copy everything (keeps OLD intact)
rsync -a "$OLD"/ "$NEW"/

# quick verification
du -sh "$OLD" "$NEW"
ls -la "$NEW" | head

Optional (only after you’ve verified the new copy works): rename the old folder as a backup:

mv "$OLD" "${OLD}.bak"
#

2) Create a shared skill (available to all agents)

SKILL_DIR="/home/claw/.openclaw/skills/git-docs-local"
mkdir -p "$SKILL_DIR"

cat > "$SKILL_DIR/SKILL.md" <<'EOF'
---
name: git-docs-local
description: Consult local Git documentation on disk before answering Git questions.
user-invocable: false
---

Local Git docs live at:
# 

- /home/claw/.openclaw/shared/docs/git

When the user asks about Git:

1) Prefer checking the local docs before answering.
2) If exec is allowed, search the docs tree for keywords (e.g. "rebase", "worktree", "config", "submodule") and then open the best match.
3) Use the read tool to open the relevant file(s).
4) Answer based on what you found and cite the file path(s) you used.
If you didn't check the docs, say so.
EOF

This skill being in ~/.openclaw/skills/... makes it eligible for all agents automatically.

Docs: https://docs.openclaw.ai/tools/skills

#

3) Make sure skills hot-reload is on (optional, but nice)

openclaw config set skills.load.watch true

(Regardless, skills are snapshotted when a session starts, so you usually want a new session anyway.)

4) Start a fresh session so the skill is picked up

In chat with your agent, run:

  • /new
#

(Or restart the gateway if you prefer.)

If you paste the output of:

openclaw config get agents.list
openclaw config get tools.fs.workspaceOnly

…I can tell you whether any of your agents will fail to see /home/claw/.openclaw/shared/docs/git and what the clean fix is.

#

Copying the docs into each agent workspace is the cleanest move if tools.fs.workspaceOnly: true — and it preserves the security benefit of that setting. I’d keep workspaceOnly enabled unless you have a strong reason to open up host-wide reads.

Why this is the “right” easy path

  • With workspaceOnly: true, the agent literally cannot read /home/claw/.openclaw/shared/... or any other out-of-workspace path.
  • Copying keeps each agent self-contained and avoids surprises later (or after enabling sandboxing).

Recommended layout

Put the Git docs in the same relative path inside every workspace, e.g.:

  • <workspace>/docs/git/...

Then you can use one shared skill (in ~/.openclaw/skills/...) that always says “docs are at docs/git/ relative to the workspace”, and it will work for every agent.

#

Commands (sync from one workspace to the other)

  1. First, grab your agent workspaces:
openclaw config get agents.list

From that output, identify the two workspace paths (call them WS_A and WS_B below).

  1. Assume your docs are currently in workspace A at docs/git/. Sync them into workspace B:
WS_A="/path/to/workspace-A"
WS_B="/path/to/workspace-B"

mkdir -p "$WS_B/docs/git"
# 
rsync -a --delete "$WS_A/docs/git/" "$WS_B/docs/git/"

du -sh "$WS_A/docs/git" "$WS_B/docs/git"

Notes:

  • --delete keeps the target in sync (remove it if you want “copy only, never delete”).

Shared skill (works with workspaceOnly)

Create (or update) a shared skill that points to the relative path:

SKILL_DIR="/home/claw/.openclaw/skills/git-docs-local"
# 
mkdir -p "$SKILL_DIR"

cat > "$SKILL_DIR/SKILL.md" <<'EOF'
---
name: git-docs-local
description: Consult local Git docs under docs/git/ (workspace-relative) before answering Git questions.
user-invocable: false
---

Local Git docs live at: `docs/git/` (relative to the current agent workspace).

When asked about Git:
1) Search within `docs/git/` (use exec+rg if allowed) to find the right page.
2) Open the relevant file(s) with the read tool.
3) Answer grounded in what you read; cite file paths.
# 
EOF

Then start a fresh session (/new) so the skill snapshot is refreshed.

If you paste the agents.list output here, I’ll rewrite the rsync commands with your exact workspace paths filled in so you can just paste-run them.

#

Here are a few quick, reliable ways to confirm it’s working (and that you’re not accidentally loading the whole docs folder into context).

1) Confirm the skill is actually loaded (and lightweight)

In chat with your agent, run:

  • /context list
  • /context detail

You should see your git-docs-local skill in the injected skills list, and you should not see your whole docs/ tree being injected (only the skill text + normal bootstrap files).

Docs: https://docs.openclaw.ai/concepts/context

2) “Prove it read from disk” test (best manual check)

Run this in a terminal to pick a real file that exists:

# 
cd /home/claw/.openclaw/workspace
find docs/git -type f | head -n 20

Pick one of the files it prints (call it docs/git/<something>), then ask your agent:

“Open docs/git/<that-file> using the read tool and paste the first ~30 lines. Also include the exact path you read.”

If it can do that, the plumbing is correct: workspace-only path restriction, file access, and tool usage.

3) “Grounded answer with citation” test (behavior check)

Ask something where the docs clearly contain the answer, and require a citation:

“Using the local Git docs under docs/git/, explain what --force-with-lease does. Quote the relevant passage and include the file path.”

#

Pass criteria:

  • It quotes a snippet (not just paraphrases)
  • It names the file path it read

4) If it fails: the two most common causes

  • No exec tool available (so it can’t search filenames). That’s OK if you give it an exact file path, but discovery/search will be weaker.
  • Docs not in the workspace you’re chatting with (since tools.fs.workspaceOnly: true).

If you paste the output of:

openclaw config get agents.list

…I can tell you exactly which workspaces need the copy and what paths the agent should be using.

#

That message is coming from the workspace-only filesystem guardrail:

  • With tools.fs.workspaceOnly: true, the agent’s “perimeter” is essentially the agent workspace directory.
  • File tools (read/write/edit/apply_patch, and some auto-load paths) are only allowed if the resolved real path is inside that workspace.
  • If there are symlinks involved (common when people try to “share” a docs folder), the realpath can point outside the workspace, and you’ll get “escapes the secure perimeter” even if the string path looks inside.

1) View what the perimeter is (which workspace the agent is actually using)

Run:

openclaw config get agents.defaults.workspace
openclaw config get agents.list
openclaw config get tools.fs.workspaceOnly

In-chat, you can also do:

  • /context detail (shows injected workspace bootstrap + skill list; often enough to confirm which workspace you’re in)
#

2) Diagnose why that specific path is considered “escaping”

Replace with your real username/path:

WS="/home/claw/.openclaw/workspace-x"

ls -la "$WS"
ls -la "$WS/docs"
ls -la "$WS/docs/nostr.md" || true

readlink -f "$WS"
readlink -f "$WS/docs"
readlink -f "$WS/docs/nostr.md"

If readlink -f "$WS/docs" (or the file) resolves to something like /home/claw/.openclaw/shared/..., that’s the escape.

#

3) Redefine the perimeter (your options)

Option A (recommended): keep workspaceOnly: true and make the docs real files inside each workspace

Don’t symlink docs/ to a shared folder; copy it in.

If docs/ is currently a symlink, replace it with a real directory + copy:

WS="/home/claw/.openclaw/workspace-x"

# backup whatever is there (safe)
mv "$WS/docs" "$WS/docs.BAK"

# recreate as a real dir
mkdir -p "$WS/docs"

# copy in from the backup target (or from your canonical source)
# 
rsync -a --copy-links "$WS/docs.BAK/" "$WS/docs/"

(Repeat per agent workspace.)

Option B: broaden/disable the guardrail (not my first pick)

If you truly want one shared docs folder for all agents without copying, you can disable the guardrail:

openclaw config set tools.fs.workspaceOnly false
openclaw config validate
openclaw gateway restart

That makes the “perimeter” effectively the whole host filesystem (so be sure you’re comfortable with that).

#

If you paste your openclaw config get agents.list output (just the workspace paths), I’ll give you the exact rsync commands for each workspace and we’ll make sure none of them are symlink-escaping.

#

Yeah—there can be a permissions issue, but with the exact error you quoted (“escapes the secure perimeter”), the usual causes are not Unix perms. It’s almost always one of these:

  1. you’re giving an absolute path and workspaceOnly is forcing workspace-relative paths, or
  2. you’re talking to a different agent / different workspace than you think (common in multi-agent + Discord thread bindings), or
  3. a directory in the path is a symlink (realpath resolves outside the workspace), or
  4. you are sandboxed for that session (even if you didn’t intend to be).

Here’s how to pinpoint it quickly.

1) First try the simplest fix: use a workspace-relative path

In the chat, ask the agent to open:

  • docs/nostr.md (NOT /home/x/.openclaw/workspace-x/docs/nostr.md)

With tools.fs.workspaceOnly: true, relative paths are the “happy path”.

#

2) Confirm you’re in the agent/workspace you think you are (Discord)

In the same thread, run:

  • /status
  • /agents (lists which agent/session this thread is bound to)

If /status shows agent work but you copied docs into the home workspace, it’ll look “correct on disk” but be outside that agent’s perimeter.

Then on the host:

openclaw config get agents.list

Make sure the agent id from /status is pointing at the workspace that contains the docs.

#

3) Check for symlink “escape” (very common)

Even if docs/nostr.md appears inside the workspace, if docs is a symlink to a shared folder, it will be rejected.

Run:

WS="/home/x/.openclaw/workspace-x"

ls -la "$WS/docs"
readlink -f "$WS"
readlink -f "$WS/docs"
readlink -f "$WS/docs/nostr.md"

If readlink -f "$WS/docs" resolves to something outside $WS, that’s the reason.

#

Fix: make docs/ a real directory (copy contents in), not a symlink.

4) Verify you’re really not sandboxing (per-session / non-main can surprise you)

Check config:

openclaw config get agents.defaults.sandbox.mode
openclaw config get agents.list

If sandbox mode is "non-main" or "all" for that agent, the tool filesystem view may differ from what you’re browsing on the host.

If you paste: