前言

当你给 AI Agent 访问文件系统的能力时，安全性就成了首要考虑的问题。你肯定不想让 AI 误删重要文件，或者意外修改敏感配置。OpenClaw 提供了多层权限控制机制，让你可以精确控制 Agent 能做什么、能访问什么。

本文将从最简单的配置开始，逐步深入到完整的权限控制体系。

快速入门：三个常用配置

如果你只是想快速限制文件操作，记住这三个配置就够了：

1. 只读模式 - 能看不能改

{
  agents: {
    defaults: {
      sandbox: {
        workspaceAccess: "ro"
      }
    }
  }
}

配置后，Agent 只能读取文件，无法创建、修改或删除。

2. 完全隔离 - 看不到你的文件

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        workspaceAccess: "none"
      }
    }
  }
}

Agent 完全看不到你的文件系统，只能在自己的沙箱中操作。

3. 禁用特定工具 - 精确控制

{
  tools: {
    deny: ["write", "edit", "apply_patch"]
  }
}

只禁止修改类工具，Agent 仍然可以读取和执行命令。

深入理解：三层控制机制

OpenClaw 的权限控制分为三层，从外到内分别是：

┌─────────────────────────────────────────────┐
│           1. 工具策略 (Tool Policy)          │  ← 第一道门：哪些工具可用
│  ┌───────────────────────────────────────┐  │
│  │        2. 沙箱机制 (Sandbox)          │  │  ← 第二道门：在哪里运行
│  │  ┌─────────────────────────────────┐  │  │
│  │  │   3. 工作区访问 (Workspace)      │  │  │  ← 第三道门：能看到什么
│  │  └─────────────────────────────────┘  │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

第一层：工具策略 (Tool Policy)

控制 哪些工具可用。这是最直接的控制方式。

{
  tools: {
    // 白名单模式：只允许这些工具
    allow: ["read", "web_search", "message"],
    
    // 黑名单模式：禁止这些工具
    deny: ["write", "edit", "apply_patch"],
    
    // 使用工具组简化配置
    // group:fs = read, write, edit, apply_patch
    // group:runtime = exec, bash, process
    // group:sessions = sessions_list, sessions_spawn 等
  }
}

规则：

  • deny 优先级最高，被禁止的工具永远不可用
  • 如果 allow 非空，则只允许列表中的工具
  • 工具策略是硬性限制，无法通过会话指令绕过

第二层：沙箱机制 (Sandbox)

控制 工具在哪里运行。

{
  agents: {
    defaults: {
      sandbox: {
        // 何时启用沙箱
        mode: "non-main",  // off | non-main | all
        
        // 沙箱作用域
        scope: "session",  // session | agent | shared
        
        // 后端类型
        backend: "docker", // docker | ssh | openshell
      }
    }
  }
}

mode 选项：

值含义
off所有会话都在主机运行
non-main只有非主会话使用沙箱（推荐）
all所有会话都使用沙箱

scope 选项：

值含义
session每个会话独立容器
agent每个 Agent 共享一个容器
shared所有会话共享一个容器

第三层：工作区访问 (Workspace Access)

控制 沙箱能看到什么文件。

{
  agents: {
    defaults: {
      sandbox: {
        workspaceAccess: "rw"  // none | ro | rw
      }
    }
  }
}
值能读能写说明
none❌❌完全隔离，只能访问沙箱内部
ro✅❌只读访问，挂在到 /workspace
rw✅✅读写访问，挂在到 /workspace

实战场景配置

场景一：安全的代码审查助手

需求：让 AI 审查代码，但不能修改任何文件。

{
  tools: {
    deny: ["write", "edit", "apply_patch"]
  },
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        workspaceAccess: "ro"
      }
    }
  }
}

场景二：隔离的测试环境

需求：让 AI 在隔离环境中运行测试，完全不影响主机。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "session",
        workspaceAccess: "none"
      }
    }
  }
}

场景三：受信任的开发助手

需求：主会话有完整权限，群聊/频道中的请求受限制。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // 群聊使用沙箱
        workspaceAccess: "ro"
      }
    }
  }
}

场景四：允许特定目录访问

需求：只允许访问项目目录，其他目录不可见。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        workspaceAccess: "none",
        docker: {
          binds: [
            "/home/user/projects:/workspace:rw"
          ]
        }
      }
    }
  }
}

自定义绑定挂载

当你需要让沙箱访问特定主机目录时，使用 binds 配置：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: [
            "/home/user/source:/source:ro",   // 只读挂载
            "/var/data:/data:rw",             // 读写挂载
          ]
        }
      }
    }
  }
}

安全注意：

  • 绑定挂载会绕过沙箱文件系统隔离
  • 敏感目录（如 SSH 密钥、配置文件）应使用 :ro
  • OpenClaw 会阻止危险挂载（如 /etc、/proc、Docker socket）

调试与排查

当你遇到权限问题时，使用以下命令诊断：

# 查看当前沙箱配置
openclaw sandbox explain

# 查看特定 Agent 的配置
openclaw sandbox explain --agent work

# JSON 格式输出
openclaw sandbox explain --json

输出示例：

Sandbox Mode: non-main
Current Session: sandboxed (non-main session)
Workspace Access: ro
Effective Tool Policy:
  - write: denied by sandbox tool policy
  - edit: denied by sandbox tool policy

常见问题

Q: 我配置了只读模式，为什么还是不能修改文件？

A: 检查是否有其他限制：

  1. 工具策略是否禁止了 write/edit
  2. 是否使用了 workspaceAccess: "none"
  3. 使用 openclaw sandbox explain 查看完整配置

Q: 群聊中的请求为什么被沙箱了？

A: 在 mode: "non-main" 模式下，群聊/频道会话被视为非主会话，会自动使用沙箱。这是推荐的安全配置。

Q: 如何临时禁用沙箱？

A: 不推荐这样做，但如果需要：

  1. 修改 sandbox.mode 为 "off"
  2. 或使用 tools.elevated 配置提升权限

Q: 沙箱会影响性能吗？

A: Docker 沙箱启动需要几秒钟，但运行时性能影响很小。对于频繁操作，可以使用 scope: "shared" 减少容器创建。

配置文件位置

所有配置都在 ~/.openclaw/config.json5 文件中：

# 查看当前配置
cat ~/.openclaw/config.json5

# 编辑配置
vim ~/.openclaw/config.json5

修改配置后，需要重启 OpenClaw Gateway：

openclaw gateway restart

总结

OpenClaw 的文件权限控制是一个分层的安全体系：

控制层级控制什么配置位置
工具策略哪些工具可用tools.allow/deny
沙箱模式在哪里运行sandbox.mode
工作区访问能看到什么sandbox.workspaceAccess
绑定挂载额外目录sandbox.docker.binds

推荐配置（兼顾安全与便利）：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session", 
        workspaceAccess: "rw"
      }
    }
  }
}

这样主会话有完整权限，群聊和子会话在沙箱中运行，既安全又实用。

相关文档：