Which OpenClaw Files Need a Permission Audit on a Gateway Host?

June 26, 2026 · Security

An OpenClaw Gateway can listen safely on loopback and still expose a provider token to another local account. The reverse is possible too: a file may be private while a service, backup job, synced folder, or custom agent directory creates a second path to the same data.

Short answer: audit the resolved state directory, the active config and its include files, channel and model credentials, shared and per-agent databases, session and log files, configured workspaces and agent roots, TLS private keys, service environment files, and every backup or synced copy. OpenClaw documents 700 for private directories and 600 for private files as the basic hardening posture. Confirm the owner and effective ACLs as well as the mode bits.

The permission audit follows the Gateway trust boundary

OpenClaw stores its own state on the Gateway host, but that does not mean every prompt stays there. The project documentation says sessions, memory, configuration, and workspace data are local by default, while requests sent to model providers and messages handled by chat platforms leave the host. File permissions therefore protect the local half of the system: credentials, policy, transcripts, and the instructions an agent reads before it acts. The disk layout reference is the starting point for finding those paths.

The upstream security policy makes the operating-system boundary explicit. Anyone who can modify OpenClaw state or configuration, including openclaw.json, is treated as an effectively trusted operator. That is why a group-writable configuration file is more serious than an untidy cache. A second local user who can rewrite the file may change authentication, tool policy, provider routing, or agent behavior before the Gateway starts its next turn.

Begin with the process that actually runs the Gateway. The default state path is ~/.openclaw, but OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, profiles, custom agentDir roots, and remote mode can move important data elsewhere. In remote mode, the session store that matters is on the remote Gateway host, not on the laptop used to connect. An audit that checks the wrong home directory is a clean report about the wrong installation.

Map the files before changing their modes

The useful question is not whether every file under the installation looks private. Ask what another account could gain by reading or changing each surface.

The first five rows are represented directly in the OpenClaw security audit catalog. TLS key files, supervisor environment files, and backup destinations need a host-level review because they sit around the Gateway rather than inside one standard state path.

Run the built-in audit, then read the findings

OpenClaw documents this sequence:

openclaw security audit
openclaw security audit --json
openclaw security audit --deep --json

The plain audit stays on the cold configuration and filesystem path. The deep form adds best-effort live Gateway probes and plugin-owned security collectors. For a permission review, the plain audit is the first useful result; deep mode is an additional check, not a replacement for reading the host filesystem.

Several findings deserve particular attention:

• fs.state_dir.perms_world_writable is critical because other users or processes can modify the full state directory. Group-writable and readable state directories receive their own findings.
• fs.config.perms_writable is critical because another account could change authentication, tools, or policy. Group-readable and world-readable configuration files expose tokens and settings.
• fs.config_include.* applies the same concern to files referenced by the main configuration.
• fs.auth_profiles.* and fs.credentials_dir.* cover stored model credentials, channel credentials, and pairing state.
• fs.sessions_store.perms_readable and fs.log_file.perms_readable flag private conversation and diagnostic data.
• fs.state_dir.symlink and fs.config.symlink identify another trust boundary. The catalog does not offer an automatic fix for these findings.
• fs.synced_dir warns when state or configuration sits in a synced folder.

openclaw security audit --fix is deliberately narrow. The CLI documentation says it can tighten state, config, include, credential, agent database, and legacy session permissions. It does not rotate tokens, disable tools, change Gateway exposure, or remove plugins. Run the audit again after a configuration edit, update, restore, or service change. A one-time chmod result is not a durable baseline until the next write and restart have been checked.

Inspect resolved paths without opening secrets

Use the same host, service account, profile, and environment that launch the Gateway. First record the resolved state directory, active config path, configured workspaces, custom agent roots, TLS paths, and supervisor environment files. Do not discover those paths by dumping the full configuration into a ticket.

The following are proposed host checks. They inspect names, owners, modes, parent-directory traversal, and symlinks without printing file contents. Substitute the real resolved path for STATE_DIR.

STATE_DIR=/path/to/resolved/state

# Linux
stat -c '%a %U:%G %n' $STATE_DIR $STATE_DIR/openclaw.json
namei -l $STATE_DIR/openclaw.json
find $STATE_DIR -type l -print
getfacl -p $STATE_DIR/openclaw.json

# macOS
stat -f '%A %Su:%Sg %N' $STATE_DIR $STATE_DIR/openclaw.json
ls -lde $STATE_DIR $STATE_DIR/openclaw.json
find $STATE_DIR -type l -print

# Windows
icacls C:\path\to\resolved\state

Check the parent directories as well as the final file. A private file under a traversable shared directory may still be exposed through another path. Review ACLs where the operating system supports them; mode bits alone do not describe every effective grant.

Repeat the check for custom agent roots and workspaces. The documentation allows agent directories outside the default state directory, and a workspace is separate from ~/.openclaw. A clean state-directory result says nothing about an external directory that contains an agent database, memory file, skill, or local .env.

Choose the baseline by deployment type

For a personal Gateway on a single-user machine, the documented 700 directory and 600 file baseline is a sensible floor for state, credentials, config, sessions, and logs. Keep a private workspace private when it contains personal memory or documents. Full-disk encryption still matters because file modes do not protect data from someone who bypasses the running operating system.

For a shared host, use a dedicated OS account for the Gateway and remove group access unless the group is part of the deliberate trust model. Give each Gateway its own state directory, config path, credentials, service identity, and backup destination. If users are adversarial or need real isolation, the upstream guidance points to separate Gateways and preferably separate OS users or hosts. A different session identifier or chat role is not a substitute for filesystem separation.

Do not flatten every file to 600 without checking how the service uses it. A public certificate, static asset, or package file has a different role from a private key or auth database. The decision is about least privilege and correct ownership, not a number applied without understanding the path.

Failure paths and limits

The audit checks one profile while the service runs another

This is the most ordinary failure. The interactive shell may use the default profile while a supervisor starts a named profile with a different OPENCLAW_STATE_DIR or config path. Compare the service definition, environment, process owner, and Gateway host before changing permissions. The OpenClaw FAQ documents this mismatch as a common reason an operator edits one config while the service reads another.

A custom root sits outside the directory you secured

Moving an agent database or workspace can be useful for storage, but it creates another path to review. Record the owner, parent-directory permissions, ACLs, symlinks, mounts, and backup behavior for every configured root. If the path is on a shared or synced volume, treat the volume as part of the security boundary.

A symlink makes the ownership story unclear

The audit catalog warns about symlinked state and config. The file may look private at the path you typed while its target belongs to another user, mount, or synchronization system. Either point OpenClaw at the intended real file or document the target and its owner as an explicit exception. Do not accept a warning merely because the link is convenient.

The backup is correct but becomes the new leak

OpenClaw warns that backups contain auth profiles, channel and provider credentials, and session history. The backup guide also says not to copy live SQLite files directly because a running database can be incomplete or corrupt. Use a supported backup command, verify the result, restrict the destination, and rotate credentials if the archive may have escaped. A verified archive proves recoverability; it does not make the archive safe to share.

The file audit passes but the host is still too trusted

File modes do not isolate root, the account that owns the Gateway, a malicious process running as that account, a trusted plugin, or a browser profile already logged into personal services. OpenClaw's secure file operations guidance describes its filesystem helpers as guardrails, not a sandbox. Host permissions, OS users, containers, and tool policy still determine the blast radius.

Keep a small acceptance record

After the review, retain the verification date, Gateway host, service account, profile, config path, state directory, agent roots, workspace paths, TLS key location, backup destination, modes, owners, ACL results, and unexplained audit findings. Remove credentials and private message content from the record.

1. The service and the operator CLI resolve the same config and state paths.
2. Sensitive directories are user-only, and sensitive files are not group- or world-readable.
3. Unexpected symlinks, synced folders, external agent roots, and supervisor environment files have an owner and a reason.
4. The built-in audit has no unexplained filesystem findings after the next config write or restart.
5. A recovery copy exists, is protected like live state, and was made through a supported backup path.

The answer is therefore broader than chmod 600 ~/.openclaw/openclaw.json. Start with that file and its parent directory, then follow every path that can authenticate the Gateway, change its policy, reveal its conversations, or restore its state. That is the permission audit that matches the system you are actually running.

Sources

Sources were accessed on September 13, 2026. The opened documentation pages did not state publication dates.

• Security audit checks: filesystem check IDs, severities, symlink findings, credential paths, session stores, logs, and synced directories.
• Secrets, storage, and logs: credential storage map, default file modes, transcript contents, redaction, and host trust.
• Where things live on disk: state-directory defaults, workspace separation, remote session location, and stored data paths.
• Security CLI: audit modes, JSON output, safe fixes, and limits of --fix.
• Backups: SQLite backup safety, sensitive archive contents, symlink behavior, and recovery paths.
• Configuration: gateway: custom state and config paths, multiple Gateway isolation, and TLS private-key handling.
• Secure file operations: filesystem guardrails and the distinction between path safety and sandbox isolation.
• OpenClaw security policy: the trusted-host assumption and one-Gateway trust model.