Secure Your Config Includes: Path Traversal Protection in OpenClaw 2026.2.17

OpenClaw's $include directive is a powerful feature that lets you split your config into modular files—keeping secrets separate, sharing common settings across agents, or organizing complex multi-channel setups. But with great power comes security responsibility.

The Risk: Config Include Path Traversal

Before v2026.2.17, a misconfigured or maliciously crafted $include path could potentially escape your config directory and read files from elsewhere on your system. If someone could influence your config (through a compromised skill, injected environment variable, or social engineering), they could use relative paths like ../../../etc/passwd or symlinks pointing outside your config directory.

This wasn't a remote exploit—it required local access or control over config inputs—but it represented a security gap that didn't need to exist.

The Fix: Confined Include Resolution

OpenClaw 2026.2.17 introduces strict containment for $include resolution:

1. Top-level directory confinement: All $include paths are now resolved relative to your config directory and cannot escape it—period.

2. Path traversal blocking: Attempts to use ../ sequences (even encoded variants) to climb out of the config directory are blocked.

3. Symlink hardening: Symlinks are validated to ensure they don't point outside the allowed config directory, with cross-platform-safe path containment checks.

4. Doctor hints: If you have invalid or escaped include paths in your config, openclaw doctor will now flag them with actionable guidance.

What You Need to Do

For most users: nothing. If your includes are already within your config directory (the expected setup), this change is transparent.

However, you should run openclaw doctor to verify your config is clean:

openclaw doctor

If you see warnings about include paths, review them. Common issues:

• Symlinks pointing outside config/: Move the target files into your config directory or copy them directly
• Paths using ../ to reach shared files: Restructure so shared config lives within your config tree
• Escaped special characters: Remove unnecessary escaping that might trigger false positives

Example: Proper Config Structure

Here's a recommended way to organize modular configs:

All paths stay within the config directory, making includes both secure and portable.

For Skill Developers

If you're building skills that generate or modify config files, ensure any $include paths you create are:

1. Relative to the user's config directory
2. Never constructed from user input without validation
3. Never using path traversal sequences

Technical Details

The fix (tracked in PR #18652) includes:

• Cross-platform path containment that works on Windows, macOS, and Linux
• Validation happens before file read, not after
• Clear error messages when containment checks fail

This is part of OpenClaw's ongoing security hardening, alongside other 2026.2.17 fixes like the OC-09 credential-theft patch and sandbox configuration safeguards.

TL;DR: Update to v2026.2.17, run openclaw doctor, and keep your $include paths within your config directory. The new containment checks protect you from path traversal attacks without changing how legitimate configs work.