Troubleshooting OpenClaw

Plugin not intercepting tool calls

Symptom: Tool calls execute without going through Faramesh.

Checks:

Verify the plugin is loaded: Check OpenClaw startup logs for "Loaded plugin: faramesh".
Verify the Faramesh server is running: faramesh status or curl http://127.0.0.1:8000/health.
Check the plugin configuration: Ensure base_url points to the correct Faramesh server.

If using the HTTP gateway: The gateway bypass fix must be applied. Check that tools-invoke-http.ts calls runBeforeToolCallHook before tool execution.

"Faramesh unreachable (fail-closed)" errors

Symptom: All tool calls are blocked with a "Faramesh unreachable" message.

Cause: The Faramesh server is not running or not reachable.

Fix:

# Start the server
faramesh serve

# Or use a different URL
export FARAMESH_BASE_URL

# Start the server
faramesh serve

# Or use a different URL
export FARAMESH_BASE_URL

# Start the server
faramesh serve

# Or use a different URL
export FARAMESH_BASE_URL

Workaround: Set fail_closed: false in the plugin config to allow tool calls when Faramesh is down (fail-open mode). This is not recommended for production.

Actions stuck in "pending_approval"

Symptom: Tool calls are blocked waiting for approval, but nobody is notified.

Checks:

Check approval channels: faramesh status — are Slack and/or email configured?
For Slack: Set FARA_SLACK_WEBHOOK_URL in your environment.
For email: Set FARA_SMTP_HOST, FARA_SMTP_USER, FARA_SMTP_PASSWORD, and FARA_SMTP_FROM.

Quick fix: Approve manually:

# Find the pending action
faramesh list

# Approve it

# Find the pending action
faramesh list

# Approve it

# Find the pending action
faramesh list

# Approve it

Policy not applying

Symptom: Actions are allowed/denied differently than expected.

Checks:

View the current policy: faramesh policy show
Check if a per-agent policy exists: faramesh policy show --agent-id <agent-id>
The simple policy is checked first. If one exists, the advanced (YAML/JSON) policy is skipped.
Verify the tool category mapping: Check the "Tools Seen" table on the Policies page.

Dashboard not showing actions

Symptom: The Vue dashboard at 0.0.0.0:3000 doesn't show any actions.

Checks:

Ensure the Faramesh server is running at 127.0.0.1:8000.
Check CORS: The server allows all origins by default (*).
Check browser console for network errors.
Try the server console directly: http://127.0.0.1:8000.

Slow tool calls

Symptom: Tool calls take longer than usual.

Cause: Each tool call makes an HTTP round-trip to the Faramesh server.

Fixes:

Ensure the server is running locally (same machine) to minimize latency.
Increase the timeout: timeout_ms: 10000 in the plugin config.
For frequently-allowed categories, set them to Allow in the simple policy — the check is still made but returns faster.

Database issues

# Reset the database
rm data/actions.db
faramesh migrate

# Switch to Postgres for production
export FARA_DB_BACKEND=postgres
export FARA_POSTGRES_DSN

# Reset the database
rm data/actions.db
faramesh migrate

# Switch to Postgres for production
export FARA_DB_BACKEND=postgres
export FARA_POSTGRES_DSN

# Reset the database
rm data/actions.db
faramesh migrate

# Switch to Postgres for production
export FARA_DB_BACKEND=postgres
export FARA_POSTGRES_DSN

Getting help

Dashboard: http://0.0.0.0:3000 → Help section
Server console: http://127.0.0.1:8000
CLI: faramesh --help
API docs: http://127.0.0.1:8000/docs (Swagger)

Table of content