Advanced Configuration

📘 Guide Status: This page covers expert-level settings. For basic setup, see the Quick Start Guide and the configuration file guide.

Overview

Advanced configuration lets you tune your OpenClaw deployment for security, performance, and extensibility. After you have OpenClaw installed and a working config file, you can add MCP (Model Context Protocol) servers, control custom skills and tool access, enable sandbox mode, adjust performance and timeouts, and configure logging and audit.

This guide covers:

Prerequisites

Gateway and Network Settings

The OpenClaw Gateway is the daemon that manages connections, routing, and the agent lifecycle. For security, the gateway should bind to localhost only by default so it is not exposed on the public network. Use a VPN (e.g. Tailscale) or SSH tunneling for remote access.

  • Bind address: Set the listen address (e.g. 127.0.0.1). Avoid binding to 0.0.0.0 unless you are behind a firewall and understand the risks.
  • Port: Default gateway port can be changed if needed; ensure firewall rules match.

For full hardening steps, see our security best practices and network isolation guides.

MCP Servers (Model Context Protocol)

OpenClaw supports MCP (Model Context Protocol) to attach external tools and context to your agent. MCP servers can provide extra data sources, APIs, or capabilities that the agent can call during conversations. This is useful for integrating databases, internal APIs, or custom tooling.

In your config you typically define MCP servers by name, transport (stdio or SSE), and command or URL. Each server can expose resources and tools that the LLM can use. Refer to the official OpenClaw documentation for the exact schema and examples for your version.

After adding or changing MCP servers, restart the gateway and verify with openclaw status. If the agent does not see the new tools, check gateway logs and MCP server startup output.

Custom Skills and Allowlists

Skills extend your agent with new capabilities. You can install community skills from the ClawHub marketplace or create custom skills. In advanced config you can:

  • Skill paths: Point to local skill directories or specific versions.
  • Environment variables: Pass secrets or config into skills via env (never hardcode secrets in config).
  • Allowlists: Restrict which skills are loaded; only enable skills you trust. Audit third-party skills for credential leaks-see skills security and security best practices.

Run openclaw security audit (or the equivalent in your version) to check for known issues in installed skills.

Tool Policies and Sandbox Mode

To reduce risk from prompt injection or malicious use, you can restrict which tools the agent is allowed to use. Sandbox mode and tool allowlists/denylists limit file system access, shell commands, browser control, and other high-privilege actions.

  • Sandbox: Enable in config to restrict tool execution; the agent can still chat and use allowlisted tools.
  • Tool policy: Define allowed or denied tools by name; block dangerous commands (e.g. raw shell) in production.
  • Execution approval: Some setups support requiring human approval for sensitive actions; see official docs for your version.

Recommended for production: enable sandbox, use allowlists, and follow our security guide and security checklist.

Performance Tuning

If you see slow responses or timeouts, adjust these areas:

  • Model timeouts: Increase request timeout for slow or large-context models (in model provider config).
  • Concurrency: Limit parallel requests to the LLM or channels if you hit rate limits or resource caps.
  • Memory: The memory system can be tuned for context length and retention; very long contexts may increase latency.
  • Gateway resources: On constrained hardware (e.g. Raspberry Pi), ensure enough RAM and swap; consider reducing concurrent sessions or disabling heavy skills.

For high-load or multi-user setups, see hosting optimization and the official docs.

Logging and Audit

Logging is essential for debugging and security. Configure log level (e.g. debug, info, warn), log file path, and rotation so logs do not fill disk. Enable audit logging for sensitive deployments to record who did what and when.

Best practices: use info or warn in production; turn on debug only when troubleshooting. Set up log rotation and monitor for anomalies. For details, see monitoring and logging and security best practices.

Channel-Specific Advanced Options

Each messaging channel supports extra options beyond the basics (e.g. bot token, app ID). Examples:

  • Telegram: Webhook URL vs long polling; allowed chat IDs; rate limits.
  • WhatsApp: Webhook URL; allowed numbers; multi-device session path.
  • Discord: Allowed guilds; default prefix; permissions.
  • Slack: Signing secret for events; allowed channels.
  • Signal, iMessage, Teams: Similar channel-specific settings (tenant ID, allowed teams, etc.).

Configure these in your config file under the relevant channel block. For step-by-step channel setup, see the channel setup hub and the guides for Telegram, WhatsApp, Discord, and Slack. Exact keys and values are in the official channel documentation.

Quick Configuration Workflow

  1. Ensure OpenClaw is running: openclaw status
  2. Edit config: openclaw config edit (or edit the config file directly in the path shown in file structure)
  3. Apply changes: restart the gateway (e.g. openclaw gateway restart or restart the service)
  4. Verify: openclaw status and check logs; test the agent on a channel

For validation errors or schema issues, see the troubleshooting guide and the official docs.

Common Issues

Issue Solution
Gateway won't start after config change Check config schema and YAML/JSON syntax; run openclaw doctor; see troubleshooting
MCP tools not visible to agent Confirm MCP server starts (check logs); verify server name and transport in config; restart gateway
Connection failed / unauthorized Verify bind address and firewall; ensure CLI and gateway use same token/config; check network isolation
Authentication or API errors Verify API keys and credentials in environment or config; see model providers and troubleshooting
Slow responses or timeouts Increase model timeout; reduce context length; check performance tuning and hosting resources
Skill fails or credential leak Audit the skill; use openclaw security audit; restrict with allowlists; see skills security

For more solutions, see our full troubleshooting guide.

Best Practices

  • Follow security hardening: bind gateway to localhost, use firewall, manage credentials safely
  • Enable sandbox and tool allowlists in production
  • Audit skills before enabling; pin versions and review updates
  • Back up config and session data regularly; test config changes in a dev environment first
  • Keep OpenClaw and skills updated; monitor logs and set up rotation

Next Steps

Related Resources

FAQ

Where do I configure MCP servers? In your main OpenClaw config file, under the section used for MCP (exact key name depends on version). Use openclaw config edit or edit the file manually; see the official docs for the current schema.

Should I enable sandbox in production? Yes. Sandbox mode limits the agent’s ability to run dangerous tools and is recommended for production. Combine it with tool allowlists and the rest of our security best practices.

How do I expose OpenClaw only on localhost? Set the gateway bind address to 127.0.0.1 (or equivalent) in config. Do not bind to 0.0.0.0 unless you have network isolation; for remote access use VPN or SSH tunneling. See network isolation.