### Clone and Run Setup Script

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Clone the n8n-claw repository and execute the setup script to install all dependencies and configure the project. The script will prompt for various API keys and configuration details.

```bash
git clone https://github.com/freddy-schuetz/n8n-claw.git && cd n8n-claw && ./setup.sh
```

--------------------------------

### Run Initial Setup Script

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/quick-reference.md

Execute the main setup script for initial project configuration.

```bash
sudo ./setup.sh
```

--------------------------------

### Bash Script for Installer Setup

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/hosting/hostinger.md

This bash script snippet demonstrates the 'ask' wrapper function used in setup.sh for interactive environment variable prompting. It checks if a variable is already set and skips the prompt if it's not a placeholder.

```bash
ask() {
  local var_name="$1"
  local prompt_text="$2"
  local default_value="$3"
  local is_placeholder="$(echo "$var_name" | grep -q "^your_" && echo "true" || echo "false")"

  if [ -n "${!var_name}" ] && [ "$is_placeholder" = "false" ]; then
    echo "$var_name is already set to '${!var_name}'. Skipping prompt."
  else
    read -rp "$prompt_text [$default_value]: " value
    eval "$var_name"="${value:-$default_value}"
  fi
}

```

--------------------------------

### Local Development Setup

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/browser-bridge/README.md

Commands to set up and run the browser-bridge service locally using Docker Compose. Includes building the image, starting services, and viewing logs.

```bash
docker compose up -d --build browser-bridge
docker logs -f n8n-claw-browser-bridge
curl http://localhost:3400/health   # if you exposed the port for dev
```

--------------------------------

### Developer and User Documentation

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/INDEX.md

Documentation files for developers and users, including a detailed developer guide and the main user-facing installation guide.

```markdown
CLAUDE.md
README.md
```

--------------------------------

### Copy Environment Example File

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/LOCAL_SETUP.md

Copies the example environment file to `.env`. This file will be populated with specific project configurations.

```bash
cp .env.example .env
```

--------------------------------

### Example Response Routing Configuration

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/webhook-api.md

Illustrates how to configure response routing using the `metadata._responseChannel` field. This example specifies that the response should be sent via a webhook.

```json
{
  "message": "What time is it?",
  "metadata": {
    "_responseChannel": "webhook",
    "_responseUrl": "https://my-app.com/api/reply"
  }
}
```

--------------------------------

### Example LLM Provider Configuration

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/database-schema.md

This JSON object shows an example configuration for an LLM provider, including the provider name, model, API key, and endpoint.

```json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "api_key": "sk-...",
  "endpoint": null
}
```

--------------------------------

### Run Setup Script

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/configuration.md

Execute the main provisioning script. Use the --force option to reimport workflows and reconfigure, or --upgrade-pg17 for PostgreSQL data migration.

```bash
sudo ./setup.sh
```

```bash
sudo ./setup.sh --force              # Reimport workflows + reconfigure
```

```bash
sudo ./setup.sh --upgrade-pg17       # Postgres 15 → 17 data migration
```

--------------------------------

### Re-run n8n-claw Setup Seed

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Execute this command to re-run the initial setup script for n8n-claw. This is useful for populating the database with seed data when the DB is empty or when 'Load Soul' returns no results. The script skips configuration steps that have already been set.

```bash
./setup.sh
```

--------------------------------

### Install Claude Code CLI on Host Machine

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Install the Claude Code CLI on the VPS host machine, not within the Docker container. This script fetches and installs the CLI.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### Skip Reverse Proxy Setup

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Set the SKIP_REVERSE_PROXY environment variable to true in your .env file if you are using your own reverse proxy. This skips the built-in nginx and Let's Encrypt installation.

```bash
SKIP_REVERSE_PROXY=true
```

--------------------------------

### User Sessions Response Example

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/browser-bridge.md

An example response detailing active sessions for a user. Each session object includes the domain, creation timestamp, last used timestamp, and the total number of tasks executed on that session.

```json
{
  "sessions": [
    {
      "domain": "github.com",
      "created_at": 1693478400.123,
      "last_used_at": 1693478600.456,
      "n_tasks": 3
    },
    {
      "domain": "example.com",
      "created_at": 1693478200.789,
      "last_used_at": 1693478300.012,
      "n_tasks": 1
    }
  ]
}
```

--------------------------------

### Search Memory Example Usage

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/database-schema.md

Example of how to call the search_memory function with a specific embedding, threshold, count, and category filter.

```sql
SELECT * FROM search_memory(
  '[0.1, 0.2, 0.3, ...]'::vector,
  0.75,
  10,
  'person'
);
```

--------------------------------

### Example Docker Compose Configuration

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/hosting/hostinger.md

This snippet shows the structure of the docker-compose.yml file, outlining the services, network, and volumes used by the n8n-claw stack.

```yaml
services:
  n8n:
    image: "docker.io/n8nio/n8n:latest"
    container_name: "n8n"
    restart: "always"
    ports:
      - "5678:5678"
    volumes:
      - "n8n_data:/home/node/.n8n"
    environment:
      - N8N_HOST=n8n
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - WEBHOOK_URL=http://localhost:5678/webhook/callback
      - LOG_LEVEL=debug
      - N8N_ENCRYPTION_KEY
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - JWT_SECRET
      - COOKIE_SECRET
      - TZ=UTC
  postgres:
    image: "docker.io/postgres:15"
    container_name: "postgres"
    restart: "always"
    environment:
      POSTGRES_DB:
      POSTGRES_USER:
      POSTGRES_PASSWORD
    volumes:
      - "postgres_data:/var/lib/postgresql/data"
  redis:
    image: "docker.io/redis:7"
    container_name: "redis"
    restart: "always"
    volumes:
      - "redis_data:/data"
  email-bridge:
    build:
      context: "./email-bridge"
    container_name: "email-bridge"
    restart: "always"
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=debug
      - DOMAIN
      - TELEGRAM_BOT_TOKEN
      - TELEGRAM_CHAT_ID
      - N8N_API_KEY
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - JWT_SECRET
      - COOKIE_SECRET
      - TZ=UTC
  file-bridge:
    build:
      context: "./file-bridge"
    container_name: "file-bridge"
    restart: "always"
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=debug
      - DOMAIN
      - TELEGRAM_BOT_TOKEN
      - TELEGRAM_CHAT_ID
      - N8N_API_KEY
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - JWT_SECRET
      - COOKIE_SECRET
      - TZ=UTC
  discord-bridge:
    build:
      context: "./discord-bridge"
    container_name: "discord-bridge"
    restart: "always"
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=debug
      - DOMAIN
      - TELEGRAM_BOT_TOKEN
      - TELEGRAM_CHAT_ID
      - N8N_API_KEY
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - JWT_SECRET
      - COOKIE_SECRET
      - TZ=UTC
  searxng:
    image: "docker.io/searxng/searxng:latest"
    container_name: "searxng"
    restart: "always"
    ports:
      - "8080:8080"
    environment:
      - SEARXNG_BASE_URL=http://localhost:8080
      - SEARXNG_SECRET
    volumes:
      - "searxng_data:/etc/searxng"
volumes:
  n8n_data:
  postgres_data:
  redis_data:
  searxng_data:
networks:
  default:
    name: "n8n-claw-net"

```

--------------------------------

### Start Docker Containers

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/LOCAL_SETUP.md

Use this command to start all services defined in the Docker Compose file in detached mode. The first run may take time to download images.

```bash
docker compose up -d
```

--------------------------------

### Browser Profile Configuration

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/browser-bridge.md

These are critical Chromium startup arguments and profile settings for headless server execution. Without them, the browser may fail to start.

```python
BROWSER_PROFILE_KWARGS = dict(
    headless=True,
    chromium_sandbox=False,
    args=["--no-sandbox", "--disable-dev-shm-usage", "--disable-gpu"],
    timeout=120000,
    keep_alive=True,
)
```

--------------------------------

### Get OpenClaw API Key

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Run this command on the OpenClaw server to retrieve the API key for authentication. This is required for the API Token setup in n8n-claw.

```bash
grep -A2 'gateway:' ~/openclaw/config.yaml | grep api_key
```

--------------------------------

### Test Commands for n8n-claw Agent

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/LOCAL_SETUP.md

These are example commands to test the functionality of the n8n-claw agent in a local setup via Telegram. They cover task creation, retrieval, web searches, reminders, and information recall.

```plaintext
"What can you do?"
"Create a task: test n8n-claw, high priority"
"Show my tasks"
"Search the web for latest n8n news"
"Read this page: https://n8n.io/blog"
"Remind me in 2 minutes to check this"
"What's the weather in Rome?"
"Remember that I prefer morning meetings"
"What do you remember about me?"
```

--------------------------------

### Full Reconfigure n8n-claw

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Re-runs the setup wizard to change settings like personality, language, timezone, and proactive/reactive mode. Existing data and credentials are kept.

```bash
./setup.sh --force
```

--------------------------------

### Install n8n-nodes-claude-code-cli

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Install the community node for n8n to enable Claude Code CLI integration. This is done through the n8n UI.

```bash
n8n-nodes-claude-code-cli
```

--------------------------------

### Configure .env File for Local Setup

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/LOCAL_SETUP.md

Populates the `.env` file with essential configuration values for n8n, Supabase, and other services. Ensure to replace placeholders with your specific URLs and keys. Note that `N8N_API_KEY` should be left empty initially.

```env
# n8n — update with your ngrok URL from Step 2
N8N_URL=https://YOUR-NGROK-URL
N8N_INTERNAL_URL=http://172.17.0.1:5678
N8N_HOST=localhost
N8N_PROTOCOL=http
N8N_WEBHOOK_URL=https://YOUR-NGROK-URL
N8N_API_KEY=

# Generate any random string for these two
N8N_ENCRYPTION_KEY=localtest123xyz456abc
POSTGRES_PASSWORD=localtest123

# Supabase — use the same keys from Step 3
SUPABASE_URL=http://localhost:8000
SUPABASE_JWT_SECRET=super-secret-jwt-token-for-local-testing
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiJ9.ZopqoUt20nEV8rw6HtnRmNIyOFZE1dIknwpBI9gn06w
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIn0.M2d2z4SFn5C7HlJlaSLfrzuZim_14wxiQEyFBMeOkSQ

# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_key

# Timezone
TIMEZONE=Europe/Rome
```

--------------------------------

### Task Response Example

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/browser-bridge.md

This is an example of a successful response when running a browser automation task. It includes the task status, result, elapsed time, number of steps, and session persistence information.

```json
{
  "status": "completed",
  "result": "Newsletter signup form successfully submitted with email user@example.com",
  "elapsed_s": 18.3,
  "n_steps": 4,
  "session_persisted": true,
  "domain": "example.com",
  "error": null
}
```

--------------------------------

### POST /read-emails Successful Response Example

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/email-bridge.md

Example of a successful response from the /read-emails endpoint, containing a list of emails with their UIDs, sender, recipient, subject, date, and a snippet of the text body, along with the total count.

```json
{
  "emails": [
    {
      "uid": 12345,
      "from": "boss@company.com",
      "to": "user@gmail.com",
      "subject": "Project Update",
      "date": "2024-03-15T14:30:00Z",
      "text": "Here's the latest status on the Q2 initiative..."
    },
    {
      "uid": 12344,
      "from": "boss@company.com",
      "to": "user@gmail.com",
      "subject": "RE: Budget Request",
      "date": "2024-03-14T09:15:00Z",
      "text": "Approved. Please proceed with the procurement process."
    }
  ],
  "total": 47
}
```

--------------------------------

### Agent API Response Example

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/webhook-api.md

An example of a successful response from the agent API, showing the success status, the agent's reply, and the session ID.

```json
{
  "success": true,
  "response": "I'll check the weather for New York. Let me search for the current conditions.",
  "session_id": "session:john.doe:1",
  "metadata": {
    "_responseChannel": "webhook"
  }
}
```

--------------------------------

### cURL Example for POST /webhook/agent

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/webhook-api.md

Demonstrates how to send a POST request to the agent API using cURL, including the necessary headers, JSON payload, and authentication.

```bash
curl -X POST http://your-domain/webhook/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-webhook-secret" \
  -d '{
    "message": "What is the weather in New York?",
    "user_id": "user:john.doe",
    "session_id": "session:john.doe:1",
    "source": "custom_app",
    "metadata": {
      "_responseChannel": "webhook",
      "custom_field": "value"
    }
  }'
```

--------------------------------

### Start ngrok Tunnel

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/LOCAL_SETUP.md

Start an ngrok tunnel to expose a local service to the internet. This is required to obtain a public URL for webhook configurations. Keep this terminal open during the session.

```bash
ngrok http 5678
```

--------------------------------

### Example Generic Webhook Request using cURL

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/webhook-api.md

Demonstrates how to send a generic webhook request to the adapter using cURL. Includes the endpoint, content type, API key, and a sample JSON payload.

```bash
curl -X POST http://your-domain/webhook/adapter \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-webhook-secret" \
  -d '{
    "message": "Create a task to review the report",
    "user_id": "app:user123",
    "session_id": "app:session:user123:001",
    "source": "custom_app",
    "metadata": {
      "_responseChannel": "webhook",
      "_responseUrl": "https://my-app.com/webhook/reply"
    }
  }'
```

--------------------------------

### Run Browser Automation Task

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/browser-bridge.md

Use this endpoint to initiate a browser automation task. Specify the user ID, task description, and optionally a starting URL, domain for session pooling, maximum steps, and timeout.

```bash
curl -X POST http://localhost:3400/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "telegram:123456789",
    "task": "Fill out the newsletter signup form with email user@example.com",
    "url": "https://example.com/newsletter",
    "domain": "example.com",
    "max_steps": 10,
    "timeout_s": 120
  }'
```

--------------------------------

### Upgrade Postgres Version

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/configuration.md

Use this command to upgrade the PostgreSQL version when encountering compatibility issues during setup.

```bash
sudo ./setup.sh --upgrade-pg17
```

--------------------------------

### Webhook API Response Example

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/CLAUDE.md

The agent responds to webhook requests with a success status, the agent's response, and session/metadata information.

```json
{ "success": true, "response": "...", "session_id": "...", "metadata": {} }
```

--------------------------------

### Switch LLM Provider

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/configuration.md

Change the LLM provider by running the setup script with the --force flag. The script will prompt for the new provider and API key, then re-patch workflows.

```bash
sudo ./setup.sh --force
```

--------------------------------

### Generate Kong Deployed Configuration

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/LOCAL_SETUP.md

Generates the `kong.deployed.yml` file by replacing placeholder keys in `kong.yml` with development keys. This file is crucial for the Kong container to start.

```bash
sed 's/{{SUPABASE_ANON_KEY}}/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiJ9.ZopqoUt20nEV8rw6HtnRmNIyOFZE1dIknwpBI9gn06w/g; s/{{SUPABASE_SERVICE_KEY}}/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIn0.M2d2z4SFn5C7HlJlaSLfrzuZim_14wxiQEyFBMeOkSQ/g' supabase/kong.yml > supabase/kong.deployed.yml
```

--------------------------------

### Webhook API Request Example

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/CLAUDE.md

External systems can interact with the agent via this HTTP POST request. Ensure the 'X-API-Key' header is set with your webhook secret.

```json
POST {{N8N_URL}}/webhook/agent
Header: X-API-Key: {{WEBHOOK_SECRET}}
Body: { "message": "...", "user_id": "...", "session_id": "...", "source": "...", "metadata": {} }
```

--------------------------------

### MCP Builder Workflow Architecture

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/docs/mcp-builder.md

This diagram outlines the sequence of operations performed by the MCP Builder workflow, from starting the process to registering the final MCP tool.

```mermaid
graph TD
    Start --> Search_API_Docs[Search API Docs (SearXNG)]
    Search_API_Docs --> Fetch_Docs[Fetch Docs (Jina Reader)]
    Fetch_Docs --> BuildPrompt[BuildPrompt (LLM prompt with docs)]
    BuildPrompt --> Generate_Tool[Generate Tool (Claude)]
    Generate_Tool --> Assemble_Deploy[Assemble & Deploy]
    Assemble_Deploy --> Create_Sub_Workflow[Create Sub-Workflow (Code node with actual logic)]
    Create_Sub_Workflow --> Activate_Sub_Workflow[Activate Sub-Workflow]
    Activate_Sub_Workflow --> Build_MCP_JSON[Build MCP JSON]
    Build_MCP_JSON --> Create_MCP_Workflow[Create MCP Workflow (mcpTrigger + toolWorkflow)]
    Create_MCP_Workflow --> Test_MCP[Test MCP (actual MCP protocol call)]
    Test_MCP --> Register_Supabase[Register in Supabase mcp_registry]
    Register_Supabase --> Update_Agent[Update agent mcp_instructions]
```

--------------------------------

### Get OpenClaw Gateway Port

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Run this command on the OpenClaw server to find the port configured for the gateway. This is needed for the Gateway URL setup in n8n-claw.

```bash
grep -A2 'gateway:' ~/openclaw/config.yaml | grep port
```

--------------------------------

### Set up HTTPS with a Domain

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Configure HTTPS for your n8n instance using Let's Encrypt and nginx. Ensure your domain's DNS A record points to the VPS IP before running.

```bash
DOMAIN=n8n.yourdomain.com ./setup.sh
```

--------------------------------

### Project Configuration and Scripts

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/INDEX.md

Core project scripts and configuration files, including the automated provisioning script, Docker Compose for service orchestration, and environment variable templates.

```shell
setup.sh
docker-compose.yml
.env.example
```

--------------------------------

### Create Task Tool

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/quick-reference.md

Call the Task Create tool with a title, description, priority, and due date.

```javascript
// Call Task Create tool with:
{
  title: "Review quarterly report",
  description: "Finance team waiting for feedback",
  priority: 5,
  due_date: "2024-03-30"
}
```

--------------------------------

### Enable Discord Bridge

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/configuration.md

Configure the Discord bridge by setting the DISCORD_BOT_TOKEN and COMPOSE_PROFILES environment variables in the .env file, then restart the stack.

```bash
echo "DISCORD_BOT_TOKEN=your-token" >> .env
echo "COMPOSE_PROFILES=discord" >> .env
```

```bash
docker compose up -d
```

--------------------------------

### GET /health

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/browser-bridge.md

Performs a health check on the Browser Bridge service.

```APIDOC
## GET /health

### Description
Health check endpoint.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Service is operational
- **browser_use_version** (string) - Browser Use SDK version (or "unknown")
- **active_sessions** (integer) - Count of sessions currently in pool

#### Response Example
```json
{
  "ok": true,
  "browser_use_version": "0.12.6",
  "active_sessions": 2
}
```

### Request Example
```bash
curl http://localhost:3400/health
```
```

--------------------------------

### GET /health

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/discord-bridge.md

Health check endpoint to verify if the bot is connected and ready.

```APIDOC
## GET /health

### Description
Health check endpoint.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - True if bot is connected and ready
- **bot** (string | null) - Bot username + discriminator (e.g. "MyBot#1234"), or null if not connected

#### Response Example
```json
{
  "ok": true,
  "bot": "n8n-claw#0123"
}
```

### Example:
```bash
curl http://localhost:3300/health
```
```

--------------------------------

### Auto-Generated Environment Variables

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/quick-reference.md

These environment variables are typically generated during the setup or deployment process. They are crucial for security and specific functionalities.

```env
N8N_ENCRYPTION_KEY
POSTGRES_PASSWORD
SUPABASE_JWT_SECRET
WEBHOOK_SECRET
CRAWL4AI_API_TOKEN
SEARXNG_SECRET_KEY
```

--------------------------------

### Run Task

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/browser-bridge/README.md

Initiates a browser task and waits for its completion. If a domain is specified, the browser session is pooled and can be reused for subsequent tasks with the same user_id and domain.

```APIDOC
## POST /tasks

### Description
Runs a browser task synchronously, waiting for it to complete. Supports pooled sessions for reuse when a `domain` is provided.

### Method
POST

### Endpoint
/tasks

### Parameters
#### Request Body
- **user_id** (string) - Required - Identifier for the user initiating the task.
- **task** (string) - Required - The description of the task to be performed by the browser.
- **url** (string) - Required - The starting URL for the browser task.
- **domain** (string) - Optional - The domain associated with the task. If provided, enables session pooling.
- **max_steps** (integer) - Optional - Maximum number of steps the task can execute.
- **timeout_s** (integer) - Optional - Timeout in seconds for the task completion.

### Request Example
```json
{
  "user_id": "telegram:1810565648",
  "task": "Sign up for the newsletter with email X",
  "url": "https://jens.marketing/",
  "domain": "jens.marketing",
  "max_steps": 25,
  "timeout_s": 300
}
```

### Response
#### Success Response (200)
- **result** (string) - The outcome or result of the completed task.

#### Response Example
```json
{
  "result": "Task completed successfully."
}
```
```

--------------------------------

### POST /read-emails Error Response (500)

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/email-bridge.md

Example error response for a server-side error, such as connection failures or authentication issues.

```json
{
  "error": "Error message from IMAP client"
}
```

--------------------------------

### Verify API Key

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/configuration.md

Check your API key stored in the .env file to ensure it is correct for your LLM provider.

```bash
cat .env | grep API_KEY
```

--------------------------------

### Access Supabase Studio UI

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/quick-reference.md

Open the Supabase Studio UI in your browser to manage the database. Replace YOUR-IP with your server's IP address.

```bash
open http://YOUR-IP:3001
```

--------------------------------

### Connect to PostgreSQL Database via psql

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/configuration.md

Connect to your local PostgreSQL database using the psql command-line client. Ensure PGPASSWORD is set correctly.

```bash
# Via psql
PGPASSWORD=pw psql -h localhost -U postgres -d postgres
```

--------------------------------

### Read Emails: Filter by Sender

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/email-bridge.md

Illustrates filtering emails from a specific sender address. This example targets emails from 'boss@company.com' on a Gmail IMAP server.

```bash
curl -X POST http://localhost:3100/read-emails \
  -H "Content-Type: application/json" \
  -d '{
    "host": "imap.gmail.com",
    "port": 993,
    "user": "user@gmail.com",
    "password": "app-specific-password",
    "from": "boss@company.com",
    "limit": 5
  }'
```

--------------------------------

### Commit and Push to n8n-claw-templates

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/CLAUDE.md

Use this command sequence to add, commit, and push changes specifically within the n8n-claw-templates subdirectory. Ensure you are in the correct directory and using the 'master' branch.

```bash
cd n8n-claw/n8n-claw-templates/
git add <files>
git commit -m "message"
git push origin master          # default branch: master
```

--------------------------------

### Perform Full n8n-claw Service Restart

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/quick-reference.md

Bring down all services and then bring them back up in detached mode for a full restart.

```bash
docker compose down && docker compose up -d
```

--------------------------------

### POST /read-emails Error Response (400)

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/email-bridge.md

Example error response for a bad request, typically due to missing required fields like host, user, or password.

```json
{
  "error": "Missing required fields: host, user, password"
}
```

--------------------------------

### View n8n-claw Container Logs

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Use these commands to view logs for the n8n, PostgreSQL database, and PostgREST services within the n8n-claw Docker environment.

```bash
docker logs n8n-claw        # n8n
```

```bash
docker logs n8n-claw-db     # PostgreSQL
```

```bash
docker logs n8n-claw-rest   # PostgREST
```

--------------------------------

### Browser Task Parameters

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/types-and-models.md

Define parameters for browser-based tasks. This includes the natural-language task, an optional starting URL, domain for session pooling, and limits for steps and timeout.

```typescript
{
  task: string;                    // Natural-language task
  url?: string;                    // Starting URL
  domain?: string;                 // For session pooling
  max_steps?: integer;             // Max steps (1-100, default 25)
  timeout_s?: integer;             // Timeout (10-900, default 300)
}
```

--------------------------------

### Rollback PostgreSQL 17 Upgrade

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Reverts the n8n-claw installation to PostgreSQL 15 by stopping services, restoring the old data directory, removing the override file, and restarting services.

```bash
docker compose down
sudo rm -rf ./volumes/db/data
sudo mv ./volumes/db/data.bak.pg15 ./volumes/db/data
sudo rm -f docker-compose.override.yml
docker compose up -d
```

--------------------------------

### File Storage Layout

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/file-bridge.md

Illustrates the directory structure for storing binary file data and associated metadata JSON files.

```text
/data/
├── files/
│   ├── file-1a2b3c4d5e6f7890      # Binary file data (may be gzipped)
│   ├── file-9a8b7c6d5e4f3210      # Binary file data
│   └── ...
└── meta/
    ├── file-1a2b3c4d5e6f7890.json  # Metadata for each file
    ├── file-9a8b7c6d5e4f3210.json
    └── ...
```

--------------------------------

### Repository Structure Overview

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/CLAUDE.md

Provides a hierarchical view of the n8n-claw project's directories and files, indicating the purpose of each component.

```tree
n8n-claw/
├── workflows/              # n8n workflow JSON files (source of truth)
│   ├── n8n-claw-agent.json         # Main agent workflow
│   ├── mcp-builder.json            # Builds new MCP Server workflows
│   ├── mcp-client.json             # Calls tools on MCP servers (sub-workflow)
│   ├── mcp-library-manager.json    # Installs/removes skills from template catalog
│   ├── mcp-weather-example.json    # Example MCP server (Open-Meteo)
│   ├── credential-form.json        # HTTPS form for secure credential entry
│   ├── oauth-callback.json         # Handles OAuth2 redirects (Google services)
│   ├── reminder-factory.json       # Creates reminders (inserts into reminders table)
│   ├── reminder-runner.json        # Polls reminders table every minute, executes due reminders
│   ├── memory-consolidation.json   # Nightly: summarizes daily log → long-term memory + extracts behavior patterns into category='insight' memories (v1.5.0)
│   ├── workflow-builder.json       # Builds general n8n automations (Claude Code CLI)
│   ├── sub-agent-runner.json       # Runs expert sub-agents with dynamic personas
│   ├── agent-library-manager.json  # Install/remove expert agents from catalog
│   ├── heartbeat.json              # Recurring actions + proactive reminders (every 5 min) + open-loop pings after 3 days (v1.5.0, throttled to 24h via heartbeat_config.last_open_loop_check)
│   ├── background-checker.json     # Silent monitoring, notifies only on new findings
│   ├── error-notification.json     # Global error handler: Telegram alert + logs failures to memory_long via PostgREST
│   ├── browser-use.json            # Sub-workflow: routes agent calls to the browser-bridge REST API
│   └── adapters/
│       └── webhook-adapter.json    # Unified adapter: Slack + Teams + Paperclip + Generic
│
├── supabase/
│   ├── migrations/
│   │   ├── 000_extensions.sql  # PostgreSQL extensions (uuid-ossp, vector)
│   │   ├── 001_schema.sql      # Full DB schema (tables, functions, roles)
│   │   ├── 002_seed.sql        # Base seed data (not used directly — setup.sh handles seeding)
│   │   ├── 003_oauth_support.sql # OAuth2 token storage for Google services
│   │   ├── 004_knowledge.sql   # Knowledge graph: kg_entities, kg_relations, enriched memory
│   │   ├── 005_hybrid_search.sql # Hybrid search RPC: semantic + fulltext + entity + time decay
│   │   ├── 006_mcp_bridge.sql  # mcp_registry auth columns for bridge templates
│   │   ├── 007_pg17_compat.sql # PG17 forward-compatibility (immutable_unaccent search_path)
│   │   ├── 008_fitness_schema.sql # Fitness Buddy schema (9 fitness_* tables)
│   │   └── 009_agents_rename.sql # Renames app table agents -> claw_agents (avoids n8n >= 2.21.4 core Agents collision, Issue #35)
│   └── kong.yml            # Kong API gateway config (generated by setup.sh)
│
├── setup.sh                # Automated setup script (see below)
├── file-bridge/            # Binary file passthrough REST API (Node.js, session-bound temp files)
├── email-bridge/           # IMAP/SMTP REST API microservice (Node.js)
├── discord-bridge/         # Discord Gateway ↔ webhook bridge (Node.js, optional — compose profile "discord")
├── browser-bridge/         # Browser Use REST wrapper (Python FastAPI, agentic browser actions)
├── searxng/                # SearXNG web search engine config
├── docker-compose.yml      # All services: n8n, postgres, postgrest, kong, studio, meta, searxng, crawl4ai, email-bridge, discord-bridge (optional)
├── .env.example            # Environment variable template
├── README.md               # User-facing installation guide
└── CLAUDE.md               # This file

```

--------------------------------

### IMAP Date Filtering Example

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/email-bridge.md

Use ISO 8601 dates for 'since' and 'before' parameters. Note that IMAP search criteria are date-only and times are normalized to UTC midnight.

```text
since: "2024-03-01"   → emails on or after 2024-03-01 00:00:00 UTC
before: "2024-03-31"  → emails before 2024-03-31 00:00:00 UTC
```

--------------------------------

### Health Check (GET /health)

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/browser-bridge.md

This endpoint provides a health status of the Browser Bridge service. It returns whether the service is operational, the SDK version, and the count of active sessions.

```bash
curl http://localhost:3400/health
```

--------------------------------

### Check MAX_FILE_SIZE_MB

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/_autodocs/configuration.md

Verify the MAX_FILE_SIZE_MB setting in your .env file to troubleshoot file upload failures.

```bash
cat .env | grep MAX_FILE_SIZE_MB
```

--------------------------------

### Configure n8n-claw MCP Server in .mcp.json

Source: https://github.com/freddy-schuetz/n8n-claw/blob/main/README.md

Configure the n8n-claw MCP server by adding its details, including the HTTP URL and authorization header, to your .mcp.json file.

```json
{
  "mcpServers": {
    "n8n-claw": {
      "type": "http",
      "url": "https://<your-n8n-domain>/mcp-server/http",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```