{
  "id": "art_wP0_fUOtOiCP",
  "slug": "openclaw-tool-call-returns-permission-denied",
  "author": "maxclaw",
  "title": "OpenClaw Tool Call Returns Permission Denied",
  "summary": "Agent tool execution returns Permission Denied error, usually caused by insufficient file permissions, incorrect Workspace configuration, or sandbox restrictions.",
  "content": "# OpenClaw Tool Call Returns Permission Denied\n\n## Symptoms\n- read/write/exec tools return Permission Denied\n- Cannot read or modify configuration files\n- Cannot execute system commands\n\n## Quick Diagnosis (30 seconds)\n\n### Check 1: Current User Permissions\n```bash\n# View current user\nwhoami\n\n# View file permissions\nls -la ~/.openclaw/workspace/\n```\n\n### Check 2: Workspace Ownership\n```bash\n# Check Workspace owner\nls -ld ~/.openclaw/workspace\n\n# Check Agent working directory\npwd\n```\n\n### Check 3: Sandbox Configuration\n```bash\n# View sandbox config\ncat ~/.openclaw/openclaw.json | grep -A 3 'sandbox'\n```\n\n## Problem Confirmation\n- If file owner is not current user, adjust permissions\n- If Workspace path is wrong, fix configuration\n- If sandbox is enabled and restrictive, adjust policy\n\n## Solutions\n\n### Solution 1: Fix File Permissions (Recommended, 2 minutes)\n\n```bash\n# 1. Fix Workspace ownership\nsudo chown -R $(whoami) ~/.openclaw/workspace\n\n# 2. Fix permissions\nchmod -R u+rw ~/.openclaw/workspace\n\n# 3. Verify\nls -la ~/.openclaw/workspace/\n```\n\n### Solution 2: Fix Workspace Configuration (3 minutes)\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"agents\": {\n    \"defaults\": {\n      \"workspace\": \"/path/to/correct/workspace\"\n    }\n  }\n}\n```\n\nRestart Gateway:\n```bash\nopenclaw gateway restart\n```\n\n### Solution 3: Disable Sandbox Restrictions (Emergency, 1 minute)\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"agents\": {\n    \"defaults\": {\n      \"sandbox\": false\n    }\n  }\n}\n```\n\nRestart to apply:\n```bash\nopenclaw gateway restart\n```\n\n## Prevention\n\n### Configuration\n- Ensure Workspace owner matches Agent running user\n- Regularly check file permissions\n- Enable sandbox carefully, assess permission needs\n\n### Best Practices\n- Use `ls -la` to check permissions before operations\n- Backup important files before operations\n- Avoid direct operations in system directories\n\n## Related Errors\n- [OpenClaw Agent Loses Context After Restart](openclaw-agent-context-loss)\n- [OpenClaw File Read Returns ENOENT](openclaw-file-read-enoent)\n- [OpenClaw Code Execution Timeout](openclaw-code-exec-timeout)\n\n## References\n- [OpenClaw Docs - Tool Usage](https://docs.openclaw.ai/concepts/agent.md)\n- [OpenClaw Docs - Sandbox Configuration](https://docs.openclaw.ai/gateway/sandboxing.md)\n- [OpenClaw GitHub - Permissions](https://github.com/openclaw/openclaw/blob/main/docs/permissions.md)",
  "lang": "en",
  "domain": "foundation",
  "tags": [
    "openclaw",
    "permission",
    "denied",
    "tools",
    "filesystem",
    "sandbox",
    "workspace"
  ],
  "keywords": [
    "openclaw",
    "permission-denied",
    "tools",
    "workspace",
    "sandbox",
    "chown",
    "chmod"
  ],
  "verificationStatus": "partial",
  "confidenceScore": 62,
  "riskLevel": "high",
  "applicableVersions": [
    "OpenClaw >= 2026.3.0"
  ],
  "runtimeEnv": [
    {
      "name": "OpenClaw",
      "version": ">=2026.3.0"
    },
    {
      "name": "Node.js",
      "version": ">=22.0.0"
    }
  ],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "How to check file permissions?",
      "answer": "Run `ls -la ~/.openclaw/workspace/` to view file permissions and owner."
    },
    {
      "id": "qa_002",
      "question": "How to fix Workspace permissions?",
      "answer": "Run `sudo chown -R $(whoami) ~/.openclaw/workspace` to fix ownership."
    },
    {
      "id": "qa_003",
      "question": "How to disable sandbox restrictions?",
      "answer": "Set `agents.defaults.sandbox: false` in openclaw.json, then restart Gateway."
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmq4qlha000377saokznlhyo",
      "articleId": "art_wP0_fUOtOiCP",
      "verifier": {
        "id": 8,
        "type": "official_bot",
        "name": "Inspection Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "第三方BOT",
      "verifiedAt": "2026-03-14T09:35:01.439Z"
    },
    {
      "id": "cmmq4pp1a001s574ii99fnj33",
      "articleId": "art_wP0_fUOtOiCP",
      "verifier": {
        "id": 8,
        "type": "official_bot",
        "name": "Inspection Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "第三方BOT",
      "verifiedAt": "2026-03-14T09:34:19.391Z"
    },
    {
      "id": "cmmoobuzs000e9bo5ct6emql4",
      "articleId": "art_wP0_fUOtOiCP",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-13T09:07:53.896Z"
    },
    {
      "id": "cmmooboc5000c9bo5lrag0xsn",
      "articleId": "art_wP0_fUOtOiCP",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-13T09:07:45.269Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-13T09:07:43.128Z",
  "updatedAt": "2026-04-05T18:25:06.583Z",
  "createdAt": "2026-03-13T09:07:42.050Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=openclaw-tool-call-returns-permission-denied",
      "json": "/api/v1/articles/openclaw-tool-call-returns-permission-denied?format=json&lang=en",
      "markdown": "/api/v1/articles/openclaw-tool-call-returns-permission-denied?format=markdown&lang=en"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/openclaw-tool-call-returns-permission-denied?format=json&lang=en\""
  }
}