OpenClaw Local Embedding Setup

Use this skill to enable local embedding for OpenClaw memory search on machines where outbound internet access is restricted to an HTTP CONNECT proxy. Do not use this skill for remote embedding providers (OpenAI, Gemini, Voyage, etc.) or for machines with direct internet access.

Target environment

• - Any Linux machine (cloud VM, on-premises server, or development workstation).
• CPU-only (no GPU required; embedding model is small enough for CPU inference).
• No direct internet access; outbound HTTPS requires an HTTP CONNECT proxy.
• OS: Ubuntu 20.04+ (GLIBC 2.31+).
• Node.js 22+ (required for NODE_USE_ENV_PROXY support).
• OpenClaw installed via npm install -g openclaw (no source build required).

Workflow

Follow these steps in order. Do not skip steps.

Step 1: Check if model is already cached

The default model is embeddinggemma-300m-qat-Q8_0.gguf (~313 MB). Check the standard cache directories:

CODEBLOCK0

If the model exists and is larger than 100 MB, skip to Step 4 (configuration).

Step 2: Resolve network and proxy

The model must be downloaded from HuggingFace. Machines without direct internet access need an HTTP CONNECT proxy.

Known proxy defaults

If the machine is a Kuaishou cloud VM and no proxy is configured, try the default above first. If a different proxy was used previously and recorded in ~/.openclaw/workspace/skills/openclaw-local-embedding/.proxy, load it automatically:

CODEBLOCK1

Strategy: progressive fallback.

1. 1. Test current environment first — the user may already have HTTPS_PROXY or a recorded proxy configured:

CODEBLOCK2

1. 2. If direct access fails, try proxies in this order:

a. Recorded proxy from previous run (.proxy file, see above).

b. Kuaishou cloud default: INLINECODE7

CODEBLOCK3

c. If neither works, ask the user for their proxy address.

1. 3. Once a working proxy is confirmed, record it for future runs:

CODEBLOCK4

Then set it only for the download process (not permanently):

CODEBLOCK5

These environment variables are process-scoped. They do not affect other processes or the gateway.

Important: NODE_TLS_REJECT_UNAUTHORIZED=0 disables TLS certificate verification. Only set it in the download script/process. Never persist it to shell profiles.

Step 3: Download and verify model

The skill includes a helper script (scripts/init-model.mjs) that handles proxy detection, model download, and verification automatically. Run it with the proxy env vars from Step 3 active (or let the script auto-detect):

CODEBLOCK6

The script will:

1. 1. Auto-detect the OpenClaw installation directory
2. Check if the model is already cached (idempotent — safe to re-run)
3. Probe network connectivity (recorded proxy → env proxy → direct → Kuaishou cloud default)
4. Record a working proxy to .proxy for future runs
5. Download the model via node-llama-cpp's INLINECODE12

Expected download size: ~313 MB. Speed through proxy: ~5–10 MB/s.

cmake troubleshooting

If node-llama-cpp cannot find a prebuilt binary (common on Ubuntu 20.04 with GLIBC < 2.32), it falls back to compiling llama.cpp from source. This requires cmake >= 3.19.

Check cmake version:

CODEBLOCK7

If cmake is < 3.19, install a newer version:

CODEBLOCK8

After cmake is available, re-run the model download. The compilation is automatic and one-time.

Step 4: Configure openclaw.json

INLINECODE15 (dot-notation path assignment) is a long-standing core feature available in all OpenClaw versions. Use it to apply settings and then verify:

CODEBLOCK9

Verify the result — the output must show all four fields set correctly:

CODEBLOCK10

Expected output:
CODEBLOCK11

Also run openclaw config validate to confirm the full config is well-formed. If it reports errors, fix them before proceeding.

If config set fails (e.g., exits with a non-zero code or config get shows wrong values), fall back to direct JSON editing. Open ~/.openclaw/openclaw.json and manually add the block under agents.defaults:

CODEBLOCK12

Do not set memorySearch at the top level. It must be nested under agents.defaults.

After manual editing, validate JSON syntax: INLINECODE23

Step 5: Restart gateway

The configuration change requires a gateway restart. Use the standard OpenClaw command:

CODEBLOCK13

This works regardless of how OpenClaw was installed (systemd, launchd, or Windows service). If the gateway is not registered as a supervised service, run it manually in foreground instead:

CODEBLOCK14

Step 6: Verify

After restart, the first memory_search tool call triggers model loading (~1.6 seconds, one-time). Subsequent calls use the in-memory model with no network access.

Check gateway status:

CODEBLOCK15

For deeper log inspection, use your system's service log viewer:

CODEBLOCK16

Resource expectations

Common issues

Model download hangs or times out

• - Verify proxy reachability: INLINECODE25

• - Check if a proxy was recorded from a previous run: INLINECODE28
• Ensure NODE_USE_ENV_PROXY=1 is set in the download process.
• If the download still fails with TLS errors, set NODE_TLS_REJECT_UNAUTHORIZED=0 — this is needed when the proxy performs TLS inspection (common in corporate/cloud environments).

llama.cpp compilation fails

• - Check cmake version: must be >= 3.19. Fix: pip3 install cmake.
• Check GCC: must be >= 9. Ubuntu 20.04 ships GCC 9.4 which is sufficient.
• Compilation is automatic and happens only once. The built binary is cached at <openclaw-node-modules>/node-llama-cpp/llama/localBuilds/.

GLIBC version mismatch

The prebuilt node-llama-cpp binary requires GLIBC >= 2.32. Ubuntu 20.04 has GLIBC 2.31. When this happens, node-llama-cpp automatically falls back to source compilation (requires cmake >= 3.19).

Gateway crash or high memory after enabling

• - RSS of ~880 MB is expected and stable. The model weights are memory-mapped.
• If the machine has less than 2 GB available RAM, do not enable local embedding. Use a remote provider instead.
• Memory does not grow over time — the model is loaded once and reused.

Security notes

• - Never persist NODE_TLS_REJECT_UNAUTHORIZED=0 in shell profiles or system-wide configuration. It disables TLS verification for all Node.js processes.
• The proxy environment variables (HTTPS_PROXY, NODE_USE_ENV_PROXY) should only be set in the download script, not in the gateway runtime.
• After model download completes, the gateway runs fully offline. No proxy or network configuration is needed.