OpenClaw TOOLS.md Guide
TOOLS.md describes your environment — the tools, services, and infrastructure your OpenClaw agent can access. It includes SSH hosts, database connections, API endpoints, local applications, and hardware details. This file helps your agent understand what's available without trial-and-error discovery, saving tokens and avoiding failed operations.
Quick Answer: TOOLS.md is a plain markdown file that configures what tools and capabilities your OpenClaw agent has access to. It defines which tools are enabled (terminal, file system, web, database), what permission level each has (read, write, execute, admin, disabled), and security boundaries like path restrictions and command allowlists. It is part of OpenClaw's three-layer identity architecture — specifically the configuration layer.
This guide covers TOOLS.md configuration, permission levels, security best practices, and a ready-to-use template for production deployments.
What is TOOLS.md?
Tool Configuration
Define which tools the agent can use — terminal, file system, web browsing, API calls, database queries, and more. Enable only what the agent needs for its specific tasks.
Permission Control
Set granular permission levels for each tool. Read-only file access, execute-only terminal, write access to specific directories. Fine-grained control over every capability.
Security Boundaries
Define what the agent cannot do. Blacklist sensitive directories, block specific commands, restrict network access to approved domains. Security through explicit boundaries.
Configuration Layer
Part of OpenClaw's three-layer identity architecture. TOOLS.md sits in the configuration layer alongside USER.md and openclaw.json, defining what the agent can do (not who it is).
How Do You Configure Tool Access in TOOLS.md?
TOOLS.md is organized by tool category. Each section defines a tool, its permission level, and any specific restrictions. Here is the structure.
File System
Control read, write, and delete access to the filesystem. Define allowed and blocked directory paths. Set maximum file sizes and restrict operations to specific file types.
Terminal / Shell
Control command execution. Define allowed and blocked commands. Set working directory restrictions, execution timeouts, and whether the agent can chain commands.
Web / HTTP
Control network access. Define allowed domains (whitelist), blocked domains, request size limits, and whether the agent can upload data to external services.
Database
Control database operations. Define allowed query types (SELECT, INSERT, UPDATE), blocked operations (DROP, TRUNCATE), connection strings, and result limits.
Ready-to-Use TOOLS.md Templates
Copy one of these templates and customize it for your setup. Each one is designed for a specific use case and follows best practices for token efficiency.
Home Automation Setup
For smart home agents managing Home Assistant, lights, locks, thermostats, and cameras.
# TOOLS.md — Home Automation Setup
## Smart Home Platform
- Hub: Home Assistant (http://homeassistant.local:8123)
- Protocol: Z-Wave + Zigbee via HUSBZB-1 stick
- Voice: Alexa integration active
## Devices
- Cameras: Ring Doorbell Pro, Wyze Cam v3 (garage, backyard)
- Lights: Philips Hue (living room, bedroom, office)
- Thermostat: Ecobee Smart Thermostat Premium
- Locks: August Wi-Fi Smart Lock (front door, side door)
- Sensors: Aqara motion sensors (hallway, basement, garage)
## Automations
- "Goodnight" routine: Lock doors, arm cameras, set thermostat to 68°F, turn off lights
- "Away" mode: Enable all cameras, lock all doors, set thermostat to eco mode
- Motion alerts: Only from 11pm-6am
## Network
- Router: UniFi Dream Machine Pro
- IoT VLAN: 192.168.2.0/24 (isolated from main network)
- Smart devices DNS: Pi-hole at 192.168.1.53
## Restrictions
- Never unlock doors without explicit confirmation
- Camera feeds are private — never share or describe footage
- Temperature range: 65°F-78°F onlyDeveloper Environment
For software development agents with SSH access, multiple repositories, databases, and CI/CD pipelines.
# TOOLS.md — Developer Environment
## SSH Hosts
- staging: ssh deploy@staging.example.com -p 2222
- production: ssh deploy@prod.example.com -p 2222 (READ ONLY — no deploy commands)
- dev-server: ssh dev@192.168.1.100
## Repositories
- Main app: github.com/myorg/main-app (Node.js + React)
- API: github.com/myorg/api-service (Python FastAPI)
- Infrastructure: github.com/myorg/terraform-configs
- Docs: github.com/myorg/internal-wiki
## Databases
- PostgreSQL (dev): localhost:5432/myapp_dev
- PostgreSQL (staging): staging-db.example.com:5432/myapp_staging (read-only)
- Redis: localhost:6379
## CI/CD
- GitHub Actions for all repos
- Staging: auto-deploy on merge to `develop`
- Production: manual approval required after staging verification
- Monitoring: Datadog dashboards at app.datadoghq.com
## Local Tools
- Docker Desktop: Running Postgres, Redis, Elasticsearch locally
- Node.js: v20 LTS via nvm
- Python: 3.12 via pyenv
- IDE: VS Code with extensions list in .vscode/extensions.jsonBusiness Tools Setup
For business automation agents managing CRM, email platforms, project management, and analytics.
# TOOLS.md — Business Tools Setup
## CRM
- Platform: GoHighLevel
- Account: [agency].gohighlevel.com
- Sub-accounts: One per client
- API: REST API via API key (stored in env vars)
## Email Platforms
- Instantly: For cold outreach campaigns
- Gmail/Google Workspace: For warm communication
- Mailgun: For transactional emails
## Project Management
- ClickUp: Workspace at app.clickup.com/[workspace-id]
- Spaces: Client Work, Internal, Marketing
- Automations: Task creation on new lead, status updates on milestones
## Communication
- Slack: Internal team communication
- Zoom: Client meetings (auto-record and transcribe)
- Loom: Async updates and tutorials
## Analytics & Reporting
- Google Analytics 4: For client websites
- Google Data Studio: Monthly reporting dashboards
- CallRail: Call tracking for local clients
## Financial
- Stripe: Payment processing
- QuickBooks: Invoicing and accounting
- Note: Never access payment details directly — use dashboard links onlyWhat Permission Levels Does TOOLS.md Support?
TOOLS.md supports five permission levels. Each level defines a different scope of access for a given tool. Always start with the lowest level needed.
read
READAgent can view and read but cannot modify, create, or delete. Ideal for monitoring, analysis, and reporting tasks.
write
WRITEAgent can create new files and modify existing ones within allowed paths. Cannot execute commands or delete critical resources.
execute
EXECUTEAgent can run shell commands and scripts. Most powerful standard permission — use with caution and pair with command allowlists.
admin
ADMINFull unrestricted access to the tool. No permission checks, no path restrictions, no command filtering. Use only in trusted, isolated environments.
disabled
DISABLEDTool is completely blocked. The agent cannot access it under any circumstances, even if a skill or prompt requests it.
Token Budget Warning
TOOLS.md loads into every session. What you write here costs tokens before your agent does any actual work.
TOOLS.md Loads on Every Session Start
Every line in your TOOLS.md is loaded into the context window at the start of each session, alongside AGENTS.md, SOUL.md, MEMORY.md, and other config files. This happens before you type a single message.
Baseline Token Cost
~2,825
tokens consumed by all config files combined before any user input
Total Character Limit
150,000
max characters across all OpenClaw config files combined
- Keep TOOLS.md under 100 lines — 30-80 lines is ideal
- Only list tools your agent actually uses in regular sessions
- A bloated TOOLS.md burns context on tools that never get called
- Every line you add is a line your agent reads before it starts helping you
How to Keep TOOLS.md Concise
A lean TOOLS.md gives your agent more room to think. Follow these practices to avoid context bloat.
Only include tools you use regularly
If you haven't used a tool in the past two weeks, it probably doesn't need to be in TOOLS.md. Remove seasonal or project-specific tools when you're not actively using them.
Use shorthand for connection details
Instead of full connection strings with all parameters, use the minimal form: hostname, port, and database name. Your agent can infer the rest or ask when needed.
Group related tools together
Use headers to group tools by category (Databases, APIs, SSH Hosts). A well-organized file is easier to maintain and easier to prune when you do quarterly cleanups.
Remove tools you no longer use
Schedule a monthly review of TOOLS.md. Deleted a service? Remove it. Switched CRM platforms? Update the entry. Stale entries confuse your agent and waste tokens.
Reference external docs instead of copying them in
Instead of pasting an entire API reference into TOOLS.md, write one line: 'Docs at docs.example.com/api'. Your agent can fetch the docs when needed — don't pre-load them.
Store secrets in environment variables, not TOOLS.md
Connection strings with embedded credentials bloat your file and create security risks. Use env var references (e.g., 'API key in env vars') to keep TOOLS.md both lean and safe.
What Are the Security Best Practices for TOOLS.md?
TOOLS.md is your primary security control for OpenClaw agents. Misconfigured tools are the number one cause of agent-related security incidents. Follow these practices.
Principle of Least Privilege
Start with all tools disabled and enable only what the agent needs. Every additional permission increases the attack surface. A reporting agent does not need terminal access. A code review agent does not need file write access.
Path Restrictions
Always define explicit directory allowlists. Whitelist only the directories the agent should access (e.g., ./src, ./data) and blacklist sensitive paths (.env, ~/.ssh, /etc). Never allow access to the entire filesystem.
Command Allowlists
When granting execute permission, pair it with a command allowlist. Instead of allowing all shell commands, specify exactly which commands are permitted (e.g., 'git', 'npm test', 'docker compose'). Block dangerous commands like rm -rf, curl to unknown domains, and sudo.
Network Restrictions
Define which domains and APIs the agent can connect to. An agent that only needs to call OpenAI's API should not have access to arbitrary URLs. Restrict outbound network access to a whitelist of approved domains.
Audit Logging
Enable tool usage logging in TOOLS.md. Every tool invocation should be logged with timestamps, parameters, and results. This creates an audit trail for reviewing what the agent did and detecting suspicious behavior.
Environment-Specific Configs
Maintain separate TOOLS.md files for development, staging, and production. Development can be permissive for productivity. Production must be locked down. Use environment variables or file swapping to load the correct TOOLS.md.
What Does a Production-Ready TOOLS.md Template Look Like?
A security-hardened TOOLS.md template following the principle of least privilege. Customize the allowed paths, commands, and domains for your specific use case.
File System Access
- Permission: read-write
- Allowed paths: ./src, ./data, ./config, ./docs
- Blocked paths: .env, .env.*, ~/.ssh, /etc, node_modules
- Max file size: 10MB per operation
- Cannot delete files outside of ./data/temp
Terminal Access
- Permission: execute
- Allowed commands: git, npm, node, docker compose, pytest
- Blocked commands: rm -rf, sudo, curl (use HTTP tool instead), ssh
- Working directory: restricted to project root
- Max execution time: 60 seconds per command
Web / HTTP Access
- Permission: read
- Allowed domains: api.openai.com, api.anthropic.com, github.com
- Blocked: all other domains (explicit allowlist only)
- Max request size: 5MB
- No file uploads to external services
Database Access
- Permission: read-write
- Allowed operations: SELECT, INSERT, UPDATE
- Blocked operations: DROP, TRUNCATE, ALTER, DELETE (use soft-delete)
- Connection: ./data/agent.db (SQLite only)
- Max query results: 1000 rows
TOOLS.md in the Three-Layer Architecture
OpenClaw's identity architecture has three layers. TOOLS.md lives in the configuration layer, controlling what the agent can do.
- Layer 1 — Soul: SOUL.md defines who the agent is (personality, values, decision-making)
- Layer 2 — Configuration: TOOLS.md + USER.md + openclaw.json define what the agent can do and how
- Layer 3 — Skills: ClawHub skills extend capabilities with pre-built automation packages
- TOOLS.md restricts skills too — a skill cannot access tools that TOOLS.md has disabled
- BOOT.md runs after all layers are loaded, using the tools TOOLS.md has permitted
- Permissions cascade: openclaw.json sets global limits, TOOLS.md refines per-tool access
- Version control TOOLS.md — track permission changes with git for audit trails
- Review TOOLS.md before deploying any new skill from ClawHub
What Are the Most Common TOOLS.md Questions?
Your Competitors Are Already Automating. Are You?
Every week we send one automation that saves 10+ hours of manual work — the same playbooks our clients use to run their businesses on autopilot. Miss a week, miss the edge.
Get the Automation Playbook (Free)
One deploy-ready automation every week. Same strategies our clients pay thousands for. 400+ business owners already inside.
Need it done for you?
Book a Free Strategy Call See what we've built for real businesses →Related OpenClaw Configuration Guides
OpenClaw MD Files Hub
Overview of all OpenClaw configuration files and how they work together as a system.
AGENTS.md Guide
Define your agent's operating contract — priorities, workflows, and behavioral rules.
ClawHub Skills Guide
Extend your agent's capabilities with pre-built automation packages from ClawHub.
Bootstrap & BOOT.md Guide
Configure the startup sequence that runs every time your agent initializes.