AI Providers

Synthezer does not include its own AI model. Instead, it connects to an AI provider of your choice — either a cloud gateway through OpenClaw, or a local AI server running on your own machine. You can switch between providers at any time.

Two Connection Modes

OpenClaw (Cloud)

Connect to a remote AI gateway. You provide a gateway URL and API token. Synthezer proxies all AI requests through this gateway. Ideal when you want access to large cloud-hosted models.

Local AI (Offline)

Connect to an AI server running on your own computer. Supports Ollama, LM Studio, Jan, vLLM, llama.cpp, and any OpenAI-compatible endpoint. Ideal when you want full privacy or offline use.

Both modes use the same pipeline, the same chips, and the same 5-stage process. The only difference is where the AI model runs. You choose the provider in the AI panel — the sidebar that opens when you click the AI icon.

At the top of the AI panel, you will see two toggle buttons: OpenClaw and Local AI. Click either one to switch modes. The active mode determines which connection settings are used when you run a pipeline.

OpenClaw Gateway

What Is OpenClaw?

OpenClaw is a gateway proxy for cloud AI models. You host or have access to an OpenClaw gateway server, and Synthezer routes all AI requests through it. The gateway handles model selection, authentication, and the actual communication with the underlying AI provider.

When you submit a pipeline stage, Synthezer sends your prompt to its own local Express server. The server then forwards the request to your OpenClaw gateway using the URL and token you configured. The gateway processes the request with the selected model and returns the response. At no point does Synthezer connect to any AI service directly — everything goes through your gateway.

Setting Up OpenClaw

Follow these steps to connect Synthezer to your OpenClaw gateway:

Open Synthezer and click the AI icon in the sidebar to open the AI panel.
Make sure the OpenClaw toggle is active at the top of the panel.
Go to the Connection tab.
Enter your Gateway URL in the first field. This is the base URL of your OpenClaw server (e.g., https://your-gateway.example.com).
Enter your Gateway Token in the second field. This is the API key or bearer token your gateway expects.
Click Connect. Synthezer will ping the gateway, verify the connection, and discover available models (agents).

If the connection succeeds, you will see a green status indicator and a list of discovered agents/models below the connection fields. The status panel at the bottom of the Connection tab will show your gateway URL and the number of available agents.

Choosing Models

After connecting, Synthezer queries your gateway's /v1/models endpoint to discover available models. These appear in the agent list in the Connection tab and in the model dropdown at the top of the AI panel.

The model dropdown groups models by provider. Cloud models from OpenClaw appear under the Cloud (OpenClaw) section header. Select a model from the dropdown to use it for all pipeline stages. The selected model is remembered across sessions.

You can set a default agent by clicking on an agent card in the Connection tab. The default agent is used when no specific model is selected in the dropdown.

How Credentials Are Stored

Your gateway URL and token are stored in your browser's localStorage under the key synthezer_oc. They are never sent to any Synthezer server, never uploaded, and never included in profile exports.

When you export your profile (via the Profile tab), gateway credentials are explicitly excluded from the export file. This means you can safely share your profile backup without exposing your API keys.

Credentials only leave your browser when Synthezer's local server proxies a request to your gateway. The request goes from your browser to localhost:8090, and then from the local server to your gateway. No third party is involved.

Tailscale Integration

If your OpenClaw gateway is running on another machine on your Tailscale network, you can use the Tailscale tab in the AI panel to connect to it directly.

Install Tailscale on both machines and log in with the same account.
Open the Tailscale tab in the AI panel.
Enter the device name or Tailscale IP of the machine running OpenClaw.
Enter the port (default: 3456).
Click Test Connection to verify connectivity.
Click Use for OpenClaw to auto-fill the Connection tab with the Tailscale URL.

The Tailscale CGNAT range (100.64.0.0/10) is explicitly allowed through Synthezer's proxy validation, so Tailscale IPs work as gateway URLs.

Troubleshooting OpenClaw

"Gateway unreachable"

The Synthezer server could not reach your gateway URL. Check that the URL is correct, the gateway is running, and there are no firewall rules blocking the connection. If using Tailscale, verify both machines are connected to the same Tailscale network.

"Invalid gateway URL"

Synthezer validates gateway URLs to prevent server-side request forgery (SSRF). Private IP ranges like 192.168.x.x, 10.x.x.x, and 127.0.0.1 are blocked for cloud gateways. If your gateway is on your local network, use Local AI mode instead, or connect through Tailscale.

HTTP 401 or 403

Your gateway token is invalid or expired. Double-check the token in the Connection tab. Make sure you are using the correct token for the specific gateway URL.

Timeout errors

Synthezer allows up to 2 hours (7,200,000ms) per AI request. If you are still getting timeouts, the gateway or the upstream AI model may be overloaded. Try a smaller or faster model.

No models discovered

Synthezer queries /v1/models on your gateway to discover available models. If this endpoint returns an empty list or an error, no agents will appear. Check that your gateway has at least one model configured.

Local AI

What Is Local AI?

Local AI mode lets you run Synthezer completely offline by connecting to an AI model running on your own machine. Instead of sending prompts to a remote gateway, Synthezer talks to a local server that hosts the model directly.

This is the most private way to use Synthezer. Your prompts, your data, and the AI responses never leave your computer. There is no network traffic to any external service.

Supported Providers

Synthezer works with any server that exposes an OpenAI-compatible /v1/chat/completions endpoint. The following providers are tested and have built-in presets:

Provider	Default Port	Notes
Ollama	`11434`	Most popular choice. Run `ollama serve` to start. Supports many open models.
LM Studio	`1234`	GUI application. Start the local server from the LM Studio interface.
Jan	`1337`	Desktop AI app with built-in server. Enable the API server in settings.
GPT4All	`4891`	Local model runner. Enable the API server from the GPT4All application settings.
text-generation-webui	`5000`	Gradio-based web UI. Launch with `--api` flag to enable the API.
vLLM	`8000`	High-throughput inference server. Best for GPU-heavy workloads.
llama.cpp / LocalAI	`8080`	Lightweight C++ inference. Start with `--server` flag.
Any OpenAI-compatible server	Varies	Any server with a `/v1/chat/completions` endpoint will work. Enter the host and port manually.

Setting Up Local AI

Here is a complete walkthrough using Ollama as an example. The process is similar for all providers.

Step 1: Install a Local AI Provider

Download and install Ollama (or your preferred provider). Then pull a model:

ollama pull llama3.2

Make sure the server is running. For Ollama, it starts automatically after installation. You can verify by running:

ollama list

Step 2: Open the Local AI Tab

In Synthezer, click the AI icon in the sidebar, then click the Local AI toggle at the top of the panel. Switch to the Local AI tab.

Step 3: Connect to Your Provider

You have two options:

Auto-Detect

Click the Detect button. Synthezer will scan all known default ports on localhost and show which providers are online. Click Use next to any detected provider to auto-fill the connection fields and connect.

Manual Configuration

Select a provider from the Preset dropdown (which auto-fills the default port), or enter the host and port manually. The host is typically 127.0.0.1. Then click Connect.

Step 4: Select a Model

After connecting, Synthezer queries the provider's /v1/models endpoint to discover available models. The models appear in the Local AI tab and are added to the global model dropdown at the top of the AI panel. Local models are prefixed with local: in the dropdown and appear under the Local AI section header. Selecting a local model automatically switches your provider mode to Local AI.

Auto-Detection

When you open the Local AI tab for the first time, or when you click Detect, Synthezer scans the following ports on 127.0.0.1:

Ollama               → port 11434
LM Studio            → port 1234
Jan                  → port 1337
GPT4All              → port 4891
text-generation-webui → port 5000
vLLM                 → port 8000
llama.cpp / LocalAI  → port 8080

For each port, Synthezer sends a request to /v1/models with a 3-second timeout. If the server responds, it is marked as Online and the available models are listed. If the server does not respond, it is marked as Offline. Detection is non-blocking — all ports are scanned in parallel.

Connection Info Panel

Once connected, the info panel at the bottom of the Local AI tab shows: the detected provider name, the connection URL, the number of available models, and the last sync timestamp. You can click Refresh to re-query the provider for updated model lists.

Testing Your Connection

After connecting, click the Test button. Synthezer sends a short test prompt to the /v1/chat/completions endpoint using the first available model. If the model responds, the test passes and you are ready to run pipelines. If the test fails, check that the model is loaded and the server is running.

Switching Between Providers

You can switch between OpenClaw and Local AI at any time using the toggle buttons at the top of the AI panel. Switching does not disconnect your existing configuration — both sets of credentials are saved independently and remain available.

Toggle Buttons

Click OpenClaw or Local AI at the top of the AI panel. The active button turns white; the inactive one dims. The status indicator updates to show whether the selected provider is connected.

Model Dropdown

Selecting a model from the dropdown also switches your provider mode automatically. If you pick a model under the Cloud (OpenClaw) header, Synthezer switches to OpenClaw mode. If you pick a model under the Local AI header, it switches to Local AI mode.

Pipeline Behavior

When you advance a pipeline stage, Synthezer reads the current provider mode and sends credentials accordingly. If Local AI mode is active and a local URL is configured, the request goes to the local server. Otherwise, it uses OpenClaw credentials. There is no need to restart the application when switching.

The provider mode is saved in localStorage under the key synthezer_ai_provider_mode. The value is either openclaw or local. This setting persists across sessions.

Security

Local AI URL Validation

When Synthezer proxies requests to a local AI provider, it validates that the URL resolves to localhost only. The allowed hostnames are:

localhost
127.0.0.1
[::1] (IPv6 loopback)
0.0.0.0

Any other hostname or IP address is rejected with a 400 error. This prevents an attacker from tricking Synthezer into making requests to external servers through the local AI proxy endpoint. This check is enforced server-side in the isUrlLocalOnly() function and cannot be bypassed from the frontend.

OpenClaw URL Validation

For OpenClaw gateway URLs, Synthezer applies the opposite rule: private/internal IP ranges are blocked to prevent server-side request forgery (SSRF). The following are rejected:

localhost, 127.0.0.1, [::1], 0.0.0.0
169.254.x.x (link-local / cloud metadata)
10.x.x.x (private class A)
192.168.x.x (private class C)
172.16.x.x through 172.31.x.x (private class B)

The exception is the Tailscale CGNAT range (100.64.0.0/10), which is explicitly allowed because it represents your own Tailscale network. This is enforced server-side in the isUrlSafeForProxy() function.

Credential Isolation

Storage

OpenClaw credentials (synthezer_oc) and Local AI configuration (synthezer_local_ai) are stored exclusively in your browser's localStorage. They never touch the SQLite database.

Profile Export

When you export your profile, gateway credentials are never included. The export skips synthezer_oc, Tailscale configuration, chat history, and session data. Only safe keys like templates, model preferences, and subagent configuration are exported.

CORS

The Synthezer server restricts CORS to same-origin requests only (localhost on the configured port). External websites cannot make requests to your Synthezer server.

Tips & Recommendations

Recommended Models for Structured Output

Synthezer expects the AI to return valid JSON responses. The pipeline prompts ask for specific JSON structures at each stage. Not all models handle this reliably. Here are some guidelines:

Best Results

Large instruction-tuned models (70B+ parameters) produce the most consistent JSON output. Examples: Llama 3.1 70B, Qwen 2.5 72B, Mixtral 8x22B. These models follow complex prompt instructions reliably and rarely produce malformed JSON.

Good Results

Medium models (7B–30B parameters) work well for most tasks. Examples: Llama 3.2 11B, Qwen 2.5 14B, Mistral 7B. They may occasionally return improperly formatted JSON, but Synthezer's parser handles common issues like markdown code blocks and whitespace.

Minimal Models

Small models (under 7B parameters) may struggle with Synthezer's multi-step structured output format. They tend to lose track of the required JSON schema across long prompts. Use these only if hardware is limited.

Performance Considerations

GPU acceleration — Local models run much faster with GPU offloading. For Ollama, this is automatic if you have a supported GPU. For llama.cpp, use the -ngl flag to set the number of GPU layers.
Context length — Synthezer's pipeline prompts can be long, especially with many chips selected. Make sure your model supports sufficient context length (8K minimum, 16K+ recommended).
Temperature — Synthezer uses a temperature of 0.3 for all AI requests. This low temperature prioritizes consistency and structured output over creativity.
Timeout — Both local and cloud requests have a 2-hour timeout. Large models on CPU may need several minutes per response. The timeout is generous to accommodate this.

Optional: API Key for Local Providers

Most local providers do not require an API key. However, some providers like text-generation-webui support optional API key authentication. If your provider requires one, enter it in the API Key field in the Local AI tab. The key is forwarded as an Authorization header to the local server. Leave this field blank if your provider does not require authentication.