Reference

API reference for commands, tools, and configuration.

This page is written as a practical reference for users and contributors. SafeClaw’s public surface is currently the CLI, environment configuration, local tool contracts, and the Twilio-compatible WhatsApp webhook.

CLI commands

`safeclaw run TASK`

Runs one task and returns the final assistant response.

safeclaw run "search my workspace for installer docs" --session default --model gpt-4.1-mini --permission-profile readonly

`safeclaw chat`

Starts an interactive terminal loop. Built-in commands include exit, reset, and memory.

`safeclaw doctor`

Checks setup health. Use --strict in automation when failures should return a non-zero exit.

safeclaw doctor --port 8080 --strict

`safeclaw session-config`

Stores per-session model and permission metadata.

safeclaw session-config default --model llama3.2:3b --permission-profile readonly

Tool capabilities

Tools are exposed to the assistant and gated by permission profile before execution.

Tool	Capability	Risk class
`list_files`	List files inside the configured workspace.	Read
`read_file`	Read a workspace file with size trimming.	Read
`search_files`	Search names and optionally content inside the workspace.	Read
`write_file`	Create or overwrite a workspace file with backup behavior.	Write
`edit_file`	Replace text in a file, optionally all matches, with backup behavior.	Write
`apply_patch`	Apply a git-style patch after path and patch checks.	Write
`fetch_url`	Fetch a URL and trim output.	Network
`web_search`	Fetch search result data from a web endpoint.	Network
`shell`	Run shell commands when shell is enabled and profile permits it.	Shell
`send_whatsapp`	Send outbound WhatsApp messages through Twilio.	Messaging
`remember`	Save local memory for the current session.	Memory
`recall_memory`	Read local memory for the current session.	Memory
`search_memory`	Search saved local memory notes.	Memory
`forget`	Delete saved memory by id or matching text.	Memory
`session_status`	Show session message counts, memory counts, model, and permission settings.	Session

Environment variables

Name	Purpose
`OPENAI_API_KEY`	API key for the configured OpenAI-compatible provider. Use `ollama` as a dummy value for local Ollama.
`OPENAI_BASE_URL`	Optional provider base URL, for example `http://localhost:11434/v1`.
`OPENAI_MODEL`	Default model name.
`WORKSPACE`	Folder SafeClaw tools can access.
`SAFECLAW_PERMISSION_PROFILE`	Default profile: `readonly`, `workspace-write`, `network-allow`, `shell-ask`, `shell-allow`, or `messaging-allow`.
`SAFECLAW_APPROVAL_MODE`	Approval behavior: `ask`, `deny`, or `auto`.
`ALLOW_SHELL`	Must be true before shell commands can run.
`MAX_TOOL_STEPS`	Maximum number of tool-call rounds for a task.
`TWILIO_ACCOUNT_SID`	Twilio account identifier for WhatsApp.
`TWILIO_AUTH_TOKEN`	Twilio auth token.
`TWILIO_WHATSAPP_FROM`	Twilio WhatsApp sender, such as `whatsapp:+14155238886`.
`SAFECLAW_ALLOWED_SENDERS`	Comma-separated WhatsApp sender allowlist.

WhatsApp webhook

Run safeclaw whatsapp to expose a Twilio-compatible webhook. Configure Twilio to send inbound WhatsApp messages to:

POST https://your-public-url/whatsapp

Supported remote commands include /help, /status, /memory, /reset, /permissions, /permissions readonly, and /model MODEL.

Testing and live mode

SafeClaw’s test suite is mocked by default. Live/unmocked tests are opt-in so contributors can run normal tests without spending API calls or hitting real services.

python3 -m pytest
python3 -m pytest --cov=safeclaw --cov-report=term-missing
python3 -m pytest --run-live