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.

✓ Tool calling / MCP
✓ Read-only vs. mutating
✓ Approval-scoped
✓ audit trails

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.

RBAC · approvals · safety

Call
structured
Exec
Gateway
Gate
Approval
Log
audit

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

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.

Write

Filesystem writes

Examples: Create, overwrite, delete outside tmp.

NB: Wrong path = data loss; approval + mount boundaries.

DB

Database writes

Examples: INSERT/UPDATE/DELETE via tool or API wrapper.

NB: Almost never autonomous on production; read-only replica for agents.

Browser

Browser submits

Examples: Form submit, checkout, admin actions in logged-in session.

NB: Prompt injection → UI action; approvals + domain scope.

Shell

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

Plan

Hallucinated actions

Agent calls non-existent tool or incorrect parameters — Gateway must log fail-closed.

Select

Choosing the wrong tool

Mail triage agent selects shell tool — allowlist too broad, not just a model error.

Retry

Retries & runaway

Same mutating step 20× after timeout — rate limits and max retries per workflow.

Browser

Browser failures

Stale DOM, session expired, CAPTCHA — looks like “broken AI”, is often session/tool state.

Shell

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.
⚠️ No protocol deep dive

Focus on production: which tools are exposed, who approves, and what you log. Adding MCP servers = new callable surface — same review as native tools.

Production

Tooling
checklist

Combine with Docker isolation and workflow-scopes per agent.

📋 Agent tools production

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.

FAQ

Agent tools —
direct answer

Tool execution, risks and governance — briefly first.

Architecture question →

Short answer: Callable capabilities on the OpenClaw Gateway — browser, shell, filesystem, API, mail — that the model can call via tool-calling/MCP with structured arguments.

Nuance: execute tools; the response in chat is not a substitute for governance on that execution.

Follow-up: workflows · Hub

Short answer: Shell, filesystem write/delete, browser submit, mail send/delete, mutating API, production DB writes, config/credential tools.

Cause: irreversible or compliance-critical side effects.

Follow-up: safety · approvals

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: Minimum allowlist, approvals on mutating, RBAC, isolated sessions, logging, retry limits, deny config-write.

Cause: misuse = overly broad tools + no audit.

Follow-up: logs incident problems

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.

✓ Tool governance
✓ Deployment audit
✓ Capability boundaries