How AI agents
real tools
to use
Tool execution on the OpenClaw Gateway: browser, shell, filesystem, API, and mail — with capability isolation, approvals, and logging before production-side effects.
direct answer
What are tools
within OpenClaw?
Short answer: Tools are executable capabilities that call the Gateway on behalf of an agent — browser actions, shell, files, HTTP/API, mail — via structured tool calling (including MCP-like integrations), not just text in chat.
Nuance: The model chooses the tool + arguments; the Gateway enforces policies, approvals, RBAC, and the sandbox. Without governance, “more tools” is just more attack surface — no productivity.
Capabilities
Which tools AI agents use
No tool marketplace — operational types on a self-hosted gateway.
Browser tools
Navigate, click, type, submit in Chromium — uses real cookies. See Browser automation.
Terminal execution
Running shell tools as Gateway user: package installs, scripts, curl — highest blast radius on host.
Filesystem tools
Read/write/list on paths that the Gateway is allowed to see — .env Read is a credential leak.
API tools
HTTP calls to CRM, webhooks, internal services — mutating endpoints are side effects.
Mailbox tools
Read, send, forward, delete on linked mailbox — compliance and reputational risk.
Monitoring tools
Gateway status, channel probe, healthz — low risk, essential for debugging. See logs & monitoring.
Search / retrieval
RAG, docs, ticket search — read-only-like but can put PII in context; log queries.
Risk classes
Read-only vs. mutating tools
In short: Read-only entails lower risk, but is not risk-free; mutating requires approvals and tight scopes.
Read-only (relatively safe)
Examples: Logs, <code>gateway status</code>, read-only API GET, mail read without send, DOM read without submit.
NB: Read on secrets paths; injection that subsequently triggers mutating tool.
Filesystem writes
Examples: Create, overwrite, delete outside tmp.
NB: Wrong path = data loss; approval + mount boundaries.
Database writes
Examples: INSERT/UPDATE/DELETE via tool or API wrapper.
NB: Almost never autonomous on production; read-only replica for agents.
Browser submits
Examples: Form submit, checkout, admin actions in logged-in session.
NB: Prompt injection → UI action; approvals + domain scope.
Terminal commands
Examples: Arbitrary shell via tool runtime.
NB: RCE surface; deny-by-default on prod, approval + allowlist.
governance
Tool governance in production
approval scopes
Mutating tool-calls wait in queue until scoped approver approves — see approvals.
RBAC & tool allowlists
Which workflow may which tool — RBAC & permissions.
least privilege
Minimal toolset per agent; no “super-agent” with all capabilities.
Isolated tools
Browser profile, container, separate API key per tool context — capability isolation.
audit trails
Tool name, payload summary, approver ID, correlation ID in logs.
logging
openclaw logs --follow + central retention — without logs, no post-mortem in case of misuse.
Failures
When tool execution goes wrong
Hallucinated actions
Agent calls non-existent tool or incorrect parameters — Gateway must log fail-closed.
Choosing the wrong tool
Mail triage agent selects shell tool — allowlist too broad, not just a model error.
Retries & runaway
Same mutating step 20× after timeout — rate limits and max retries per workflow.
Browser failures
Stale DOM, session expired, CAPTCHA — looks like “broken AI”, is often session/tool state.
Terminal mistakes
Plausible command, destructive path — approvals show exact line before exec.
Debug: OpenClaw Problems · Log first, do not wipe.
MCP & tool-calling
Structured execution,
not automatically safe
Short answer: MCP and tool-calling make integrations predictable — governance remains at the Gateway level (policies, approvals, RBAC).
- → Model ↔ tool: The LLM selects a tool + structured arguments; the Gateway executes and returns the result — no more “text-only” boundary.
- → Structured execution: MCP and tool-calling standardize schemas — useful for integrations, not a security layer in themselves.
- → Why governance: More tools = more callable surface; protocol has no “safe” — only policies, RBAC, and sandbox.
- → Why approvals: Human-in-the-loop before irreversible tool results — especially browser submit and shell.
Focus on production: which tools are exposed, who approves, and what you log. Adding MCP servers = new callable surface — same review as native tools.
Overexposure
When agents get too many tools
Short answer: Broad allowlists increase the risk of incorrect tool selection, injection chains, and approval fatigue.
Privilege escalation
Agent with config-write or credential tool can broaden itself — deny on prod.
Browser misuse
Admin session + wide navigate tool = injection becomes account takeover.
Filesystem damage
Delete/sync tools without path allowlist — one hallucination = incident.
Secrets leakage
Read tool on home dir + agent pastes output into channel.
Approval bypass risk
Too many auto-approve “small” writes — attacker chaining small steps.
Short answer: Without a gate, every tool call is direct execution — error plan or injection becomes action.
Nuance: Read-only tools may be lighter; destructive ones may not.
Follow-up: approvals
Short answer: Tools that do not have a mutating side effect — logs, status, read-only GET, DOM read without submit.
Cause: read-only ≠ secure: secrets and PII can still be leaked.
Advice: path-allowlist + audit.
Short answer: Yes, if the shell tool is in scope — as a Gateway user on a host or in a container.
Cause: The shell is the RCE surface; the most restrictive tool in production.
Follow-up: approval + RBAC + no root.
Short answer: They use logged-in sessions and can execute submit/click — prompt injection becomes a UI action.
Cause: no text-only sandbox.
Follow-up: Browser automation · domain allowlist · approvals on submit.
Tooling
Safe tooling &
agent architecture
We review tool allowlists, MCP exposure, approval policies, and logging on your Gateway — deployment audits for self-hosted teams, not an AI skills marketplace.