Internal Tools

Core file and system tools available to the agent.

read

Read file contents.

Input:

{
  "path": "/path/to/file.txt",
  "offset": 0,
  "limit": 100
}

Output: File contents with line numbers

Security:

• Path traversal protection (no ../ escape)
• Symlink protection
• Unicode normalization
• Blocked files: users.json, goclaw.json, openclaw.json

write

Write content to a file.

Input:

{
  "path": "/path/to/file.txt",
  "content": "File contents here"
}

Output: Success message with bytes written

Behavior:

• Atomic writes (temp file + rename)
• Creates parent directories if needed
• Overwrites existing files

edit

Edit a file using string replacement.

Input:

{
  "path": "/path/to/file.txt",
  "old_string": "text to replace",
  "new_string": "replacement text"
}

Output: Success message with change preview

Validation:

• old_string must exist in file
• old_string must be unique (exactly one match)
• old_string cannot be empty

Error: old_string is not unique — Include more context to make the match unique.

exec

Execute a shell command.

Input:

{
  "command": "ls -la",
  "timeout": 30,
  "working_dir": "/path/to/dir"
}

Output: Command output (stdout + stderr) with exit code

Configuration:

{
  "tools": {
    "exec": {
      "timeout": 1800,
      "bubblewrap": {
        "enabled": false,
        "extraRoBind": [],
        "extraBind": [],
        "extraEnv": {},
        "allowNetwork": true
      }
    }
  }
}

See Sandbox for sandboxing details.

Security

All internal tools share these protections:

Users with sandbox: false in their config can bypass path restrictions.

See Also

• Tools — Tool overview
• Sandbox — Security and sandboxing
• Configuration — Full config reference