Understanding OpenClaw's Permission and Access Controls

Clawpedia · For Humans

Configure fine-grained permissions to control what your OpenClaw agent can access and execute.

Who Can Do What?

OpenClaw has a granular permission system that controls what the agent, skills, and users can access. Understanding these controls is essential for running a secure and predictable AI assistant.

---

Permission Layers

OpenClaw has three layers of access control:

┌─────────────────────────────────┐
│  Layer 1: Agent Permissions     │  What the agent itself can do
├─────────────────────────────────┤
│  Layer 2: Skill Permissions     │  What each skill can access
├─────────────────────────────────┤
│  Layer 3: User Permissions      │  Who can interact with the agent
└─────────────────────────────────┘

---

Layer 1: Agent Permissions

Control what the OpenClaw agent is allowed to do at the system level:

agent:
  permissions:
    network: true          # Allow outbound network requests
    filesystem: read       # none, read, read-write
    shell: false            # Allow executing system commands
    memory: read-write      # none, read, read-write
    notifications: true     # Allow system notifications

Permission Levels

---

Layer 2: Skill Permissions

Each skill declares its required permissions in manifest.yaml:

permissions:
  - network
  - memory

The agent enforces these permissions at runtime:

[Skill: weather] Requesting network access... ✔ (declared in manifest)
[Skill: weather] Requesting filesystem access... ✘ DENIED (not in manifest)

Overriding Skill Permissions

security:
  skill_overrides:
    weather-forecast:
      network: true
      filesystem: false      # Deny even if manifest requests it
    server-manager:
      shell: true            # Allow (after careful review)
      filesystem: read       # Read-only access

Revoking Permissions

openclaw skills revoke weather-forecast filesystem
openclaw skills revoke server-manager shell

---

Layer 3: User Permissions

In multi-user setups, control who can use the agent and what they can do:

users:
  roles:
    admin:
      permissions:
        - manage_skills
        - manage_config
        - manage_memory
        - manage_users
        - execute_commands
    user:
      permissions:
        - chat
        - use_skills
        - read_memory
    guest:
      permissions:
        - chat

  accounts:
    - id: "telegram:123456789"
      name: Alex
      role: admin
    - id: "discord:987654321"
      name: Sarah
      role: user
    - id: "*"
      role: guest            # Default role for unknown users

Per-Skill User Restrictions

skill_access:
  server-manager:
    allowed_roles: [admin]
  weather-forecast:
    allowed_roles: [admin, user, guest]
  memory-manager:
    allowed_roles: [admin]

---

Permission Checks in Code

When writing custom skills, check permissions programmatically:

module.exports = {
  async execute(context) {
    // Check if user has permission
    if (!context.user.hasPermission("execute_commands")) {
      return { error: "You do not have permission to run this command." };
    }

    // Check if skill has filesystem access
    if (!context.permissions.has("filesystem")) {
      return { error: "This skill needs filesystem permission." };
    }

    // Proceed with operation
    const files = await context.fs.readdir("/app/data");
    return { text: `Found ${files.length} files.` };
  },
};

---

Auditing Permissions

# Show all permissions for all skills
openclaw security permissions --skills

# Show all user roles and permissions
openclaw security permissions --users

# Full security audit
openclaw security audit

Audit output:

Security Audit:
  Agent Permissions:
    network: ✔ enabled
    filesystem: read-only
    shell: ✘ disabled
    memory: read-write

  Skill Permissions:
    weather-forecast: [network] ✔
    server-manager: [network, shell, filesystem] ⚠ shell access
    customer-support: [network, memory] ✔

  User Roles:
    admin (1 user): full access
    user (3 users): chat + skills
    guest (default): chat only

  Warnings:
    ⚠ server-manager has shell access - review regularly
    ⚠ 2 skills have network access without domain restrictions

---

Default Permission Profiles

Quickly apply a set of permissions:

# Restrictive (recommended for production)
openclaw security profile apply restrictive

# Standard (balanced)
openclaw security profile apply standard

# Permissive (development only)
openclaw security profile apply permissive

---

Tips

• Start restrictive, then open up as needed — easier than locking down later.
• Never give shell access to untrusted skills — it is the highest risk permission.
• Use role-based access in multi-user environments.
• Audit permissions monthly with openclaw security audit.
• Log permission denials to catch misconfigured skills.

---

Troubleshooting