feat(gateway): add embeddings proxy endpoint (#1068)

## Summary

- Add new embeddings proxy API at `/api/gateway/embeddings` (and
`/api/openrouter/embeddings`) that routes embedding requests to the
correct upstream provider (OpenRouter, Mistral direct, OpenAI direct)
with full BYOK, rate limiting, balance checking, and microdollar usage
tracking.
- Introduce `getEmbeddingProvider` for model-based provider routing:
`mistralai/*` → Mistral API, `openai/*` → OpenAI API, all others →
OpenRouter, with Vercel AI Gateway override when BYOK keys are
available.
- Add `buildUpstreamBody` to translate and strip provider-specific
fields (e.g. Mistral's `output_dimension` vs OpenAI's `dimensions`),
`parseEmbeddingUsageFromResponse` with a known-pricing table for
direct-provider cost computation, and `extractEmbeddingPromptInfo` for
audit logging.
- KiloClaw: add `Dockerfile.local` and `push-dev.sh --local` flag for
testing custom OpenClaw builds from local tarballs, install QMD
globally, bump Node.js to 22.22.1.

## Verification

- [X] Manual code review of all 3 commits
- [X] Unit tests exist for `buildUpstreamBody`, `stripModelPrefix`,
`extractEmbeddingPromptInfo`, `parseEmbeddingUsageFromResponse`,
`getEmbeddingProvider`, and `checkOrganizationModelRestrictions`

<img width="2411" height="1008" alt="image"
src="https://github.com/user-attachments/assets/b59fae3b-9a57-4aa0-801a-08c7a8ef9515"
/>

## Test Calls

OpenRouter (default — e.g. Google embedding model):
```bash
curl -X POST http://localhost:3000/api/gateway/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "model": "google/text-embedding-004",
    "input": "The quick brown fox jumps over the lazy dog"
  }'
```
Mistral direct:
```bash
curl -X POST http://localhost:3000/api/gateway/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "model": "mistralai/mistral-embed",
    "input": ["Hello world", "Embedding test"]
  }'
```
OpenAI direct:
```bash
curl -X POST http://localhost:3000/api/gateway/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "Test embedding input"
  }'
```

## Reviewer Notes

- The embeddings route mirrors the chat-completions proxy pattern (auth
→ rate limit → BYOK → balance → provider routing → upstream fetch →
usage tracking) but is non-streaming only.
- Direct-provider cost computation uses a hardcoded pricing table in
`EMBEDDING_PRICING`; for OpenRouter the `cost` field from the response
is used instead.
- `Dockerfile.local` is a near-copy of `Dockerfile` with the npm install
swapped for a `COPY` + local tarball install — intended for dev/testing
only.

Author: catrielmuller

kiloclaw/DEVELOPMENT_LOCAL.md

@@ -271,6 +271,56 @@ request falls through to the proxy, which returns a bare `401 Unauthorized`
 instead of the expected `controller_route_unavailable` code. This surfaces as a
 `GatewayControllerError: Unauthorized` in the worker logs.
 
+## Testing a Custom OpenClaw Build
+
+To test a local OpenClaw fork (e.g., a feature branch with embeddings support),
+use `Dockerfile.local` which installs OpenClaw from a tarball in `openclaw-build/`
+instead of npm.
+
+### 1. Build and pack your fork
+
+```bash
+cd /path/to/openclaw
+pnpm build && npm pack
+```
+
+This produces a file like `openclaw-2026.3.9.tgz` in the repo root.
+
+### 2. Copy the tarball
+
+```bash
+cp /path/to/openclaw/openclaw-*.tgz kiloclaw/openclaw-build/
+```
+
+The `openclaw-build/` directory is git-ignored for `.tgz` files, so tarballs
+won't be committed.
+
+### 3. Build and push with `--local`
+
+```bash
+# From kiloclaw/
+./scripts/push-dev.sh --local
+```
+
+This uses `Dockerfile.local` instead of the default `Dockerfile`. The script
+validates that a tarball exists in `openclaw-build/` before building. Everything
+else (tagging, pushing, `.dev.vars` updates) works the same as a normal push.
+
+### 4. Deploy
+
+1. Restart the KiloClaw worker: `pnpm run dev`
+2. From the dashboard (`localhost:3000`), destroy your existing instance
+   (Settings tab → Destroy), then create/provision a new one.
+3. The new instance will run your custom OpenClaw build.
+
+### Notes
+
+- `OPENCLAW_VERSION` in `.dev.vars` is extracted from the main `Dockerfile`'s
+  pinned npm version, so it won't reflect your fork's version. This is cosmetic.
+- Clean up old tarballs from `openclaw-build/` before copying a new one --
+  the `COPY openclaw-build/openclaw-*.tgz` glob must match exactly one file.
+- Remember to `fly auth docker` before pushing (token expires after 5 minutes).
+
 ## Provisioning and Using an Instance
 
 ### From the dashboard (`localhost:3000`):

kiloclaw/Dockerfile

@@ -1,7 +1,7 @@
 FROM debian:bookworm-slim
 
 # Install Node.js 22 (required by OpenClaw)
-ENV NODE_VERSION=22.13.1
+ENV NODE_VERSION=22.22.1
 RUN apt-get update \
     && apt-get install -y --no-install-recommends \
        ca-certificates curl gnupg git xz-utils unzip jq ripgrep rsync zstd \
@@ -48,6 +48,9 @@ RUN npm install -g openclaw@2026.3.8 \
 # Install ClawHub CLI
 RUN npm install -g clawhub
 
+# Install QMD
+RUN npm install -g @tobilu/qmd
+
 # Install mcporter (MCP server tooling)
 RUN npm install -g mcporter@0.7.3
 

kiloclaw/Dockerfile.local

@@ -0,0 +1,135 @@
+FROM debian:bookworm-slim
+
+# Install Node.js 22 (required by OpenClaw)
+ENV NODE_VERSION=22.22.1
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       ca-certificates curl gnupg git xz-utils unzip jq ripgrep rsync zstd \
+       build-essential python3 ffmpeg tmux chromium \
+    && ARCH="$(dpkg --print-architecture)" \
+    && case "${ARCH}" in \
+         amd64) NODE_ARCH="x64" ;; \
+         arm64) NODE_ARCH="arm64" ;; \
+         *) echo "Unsupported architecture: ${ARCH}" >&2; exit 1 ;; \
+       esac \
+    && curl -fsSL https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz -o /tmp/node.tar.xz \
+    && tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1 \
+    && rm /tmp/node.tar.xz \
+    && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+       -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=${ARCH} signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+       > /etc/apt/sources.list.d/github-cli.list \
+    && curl -fsSL https://downloads.1password.com/linux/keys/1password.asc \
+       | gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg \
+    && echo "deb [arch=${ARCH} signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/${ARCH} stable main" \
+       > /etc/apt/sources.list.d/1password.list \
+    && mkdir -p /etc/debsig/policies/AC2D62742012EA22/ \
+    && curl -fsSL https://downloads.1password.com/linux/debian/debsig/1password.pol \
+       | tee /etc/debsig/policies/AC2D62742012EA22/1password.pol > /dev/null \
+    && mkdir -p /usr/share/debsig/keyrings/AC2D62742012EA22 \
+    && curl -fsSL https://downloads.1password.com/linux/keys/1password.asc \
+       | gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends gh 1password-cli=2.32.1-1 \
+    && apt-get purge -y xz-utils \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/* \
+    && node --version \
+    && npm --version
+
+# Install pnpm globally
+RUN npm install -g pnpm
+
+# Install OpenClaw from local tarball (see openclaw-build/README)
+COPY openclaw-build/openclaw-*.tgz /tmp/openclaw.tgz
+RUN npm install -g /tmp/openclaw.tgz \
+    && rm /tmp/openclaw.tgz \
+    && openclaw --version
+
+# Install ClawHub CLI
+RUN npm install -g clawhub
+
+# Install QMD
+RUN npm install -g @tobilu/qmd
+
+# Install mcporter (MCP server tooling)
+RUN npm install -g mcporter@0.7.3
+
+# Install summarize (web page summarization CLI)
+RUN npm install -g @steipete/summarize@0.11.1
+
+# Install Go (available at runtime for users to `go install` additional tools)
+ENV GO_VERSION=1.26.0
+RUN ARCH="$(dpkg --print-architecture)" \
+    && curl -fsSL https://dl.google.com/go/go${GO_VERSION}.linux-${ARCH}.tar.gz -o /tmp/go.tar.gz \
+    && EXPECTED_SHA256="$(curl -fsSL https://dl.google.com/go/go${GO_VERSION}.linux-${ARCH}.tar.gz.sha256)" \
+    && echo "${EXPECTED_SHA256}  /tmp/go.tar.gz" | sha256sum -c - \
+    && tar -xzf /tmp/go.tar.gz -C /usr/local \
+    && rm /tmp/go.tar.gz
+# IMPORTANT: A Fly Volume is mounted at /root at runtime, which shadows
+# everything the image layer writes under /root.
+# - Pre-installed tools use GOBIN=/usr/local/bin so they survive the mount.
+# - At runtime, Go defaults to GOBIN=/root/go/bin (on the persistent volume),
+#   so user-installed tools persist across restarts and are included in snapshots.
+# - npm/Node (installed to /usr/local) and apt packages (/usr/bin) are unaffected.
+ENV PATH="/usr/local/go/bin:/root/go/bin:$PATH"
+RUN GOBIN=/usr/local/bin go install github.com/steipete/gogcli/cmd/gog@v0.11.0 \
+    && GOBIN=/usr/local/bin go install github.com/steipete/goplaces/cmd/goplaces@v0.3.0 \
+    && GOBIN=/usr/local/bin go install github.com/Hyaxia/blogwatcher/cmd/blogwatcher@v0.0.2 \
+    && GOBIN=/usr/local/bin go install github.com/xdevplatform/xurl@v1.0.3 \
+    && GOBIN=/usr/local/bin go install github.com/steipete/gifgrep/cmd/gifgrep@v0.2.3 \
+    && go clean -cache -modcache
+
+# Install uv (Python package manager, available at runtime).
+# Install to /usr/local/bin so the binary survives the Fly Volume mount at /root.
+RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh \
+    && uv --version
+
+# Install pinned Bun (build-time only) and compile the controller bundle.
+ARG BUN_VERSION=1.2.4
+RUN curl -fsSL https://bun.sh/install | bash -s "bun-v${BUN_VERSION}"
+ENV PATH="/root/.bun/bin:$PATH"
+
+ARG CONTROLLER_COMMIT=unknown
+# Changing this ARG value invalidates the COPY + RUN layers below it,
+# forcing a controller rebuild even when Docker thinks the source is unchanged.
+ARG CONTROLLER_CACHE_BUST=1
+COPY controller/ /tmp/controller-build/
+RUN cd /tmp/controller-build \
+    && bun install --frozen-lockfile \
+    && CONTROLLER_VERSION="$(date -u +'%Y.%-m.%-d')" \
+    && bun build src/index.ts --outfile=/usr/local/bin/kiloclaw-controller.js --target=node --minify \
+       --define "KILOCLAW_CONTROLLER_VERSION=\"${CONTROLLER_VERSION}\"" \
+       --define "KILOCLAW_CONTROLLER_COMMIT=\"${CONTROLLER_COMMIT}\"" \
+    && rm -rf /tmp/controller-build
+
+# Create OpenClaw directories
+# When a Fly Volume is mounted at /root, these dirs persist across restarts.
+RUN mkdir -p /root/.openclaw \
+    && mkdir -p /root/clawd \
+    && mkdir -p /root/clawd/skills
+
+# Copy startup script
+# Build cache bust: 2026-03-11-v60-tools-md
+RUN echo "9"
+COPY start-openclaw.sh /usr/local/bin/start-openclaw.sh
+COPY openclaw-pairing-list.js /usr/local/bin/openclaw-pairing-list.js
+COPY openclaw-device-pairing-list.js /usr/local/bin/openclaw-device-pairing-list.js
+RUN chmod +x /usr/local/bin/start-openclaw.sh
+RUN ls -l /usr/local/bin/start-openclaw.sh \
+    && head -n 1 /usr/local/bin/start-openclaw.sh | cat -v \
+    && od -An -t x1 -N 4 /usr/local/bin/start-openclaw.sh \
+    && ls -l /bin/bash
+
+# Copy custom skills
+COPY skills/ /root/clawd/skills/
+
+# Stage TOOLS.md outside /root so it survives the Fly Volume mount.
+# start-openclaw.sh copies it to /root/.openclaw/workspace/TOOLS.md on first boot.
+COPY container/TOOLS.md /usr/local/share/kiloclaw/TOOLS.md
+
+# Expose the gateway port
+EXPOSE 18789
+
+# Entrypoint: start the KiloClaw controller daemon
+CMD ["/usr/local/bin/start-openclaw.sh"]

kiloclaw/openclaw-build/.gitignore

@@ -0,0 +1 @@
+*.tgz

kiloclaw/scripts/push-dev.sh

@@ -3,8 +3,12 @@
 # timestamped tag, and update .dev.vars so the worker uses it on next
 # machine create/restart.
 #
-# Usage: ./scripts/push-dev.sh [app-name]
-#   app-name defaults to FLY_APP_NAME from .dev.vars, or "kiloclaw-dev"
+# Usage: ./scripts/push-dev.sh [--local] [app-name]
+#   --local    Use Dockerfile.local to install OpenClaw from a local tarball
+#              in openclaw-build/ instead of npm. Build your fork first:
+#              cd /path/to/openclaw && pnpm build && npm pack
+#              cp openclaw-*.tgz /path/to/kiloclaw/openclaw-build/
+#   app-name   defaults to FLY_APP_NAME from .dev.vars, or "kiloclaw-dev"
 #
 set -e
 
@@ -15,6 +19,30 @@ fly auth docker
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 KILOCLAW_DIR="$(dirname "$SCRIPT_DIR")"
 
+# Parse --local flag
+USE_LOCAL=false
+for arg in "$@"; do
+  case "$arg" in
+    --local) USE_LOCAL=true; shift ;;
+  esac
+done
+
+# Select Dockerfile
+if [ "$USE_LOCAL" = true ]; then
+  DOCKERFILE="$KILOCLAW_DIR/Dockerfile.local"
+  # Validate that a tarball exists in openclaw-build/
+  if ! ls "$KILOCLAW_DIR"/openclaw-build/openclaw-*.tgz 1>/dev/null 2>&1; then
+    echo "Error: No openclaw-*.tgz found in openclaw-build/." >&2
+    echo "Build your fork first:" >&2
+    echo "  cd /path/to/openclaw && pnpm build && npm pack" >&2
+    echo "  cp openclaw-*.tgz $(cd "$KILOCLAW_DIR" && pwd)/openclaw-build/" >&2
+    exit 1
+  fi
+  echo "Using Dockerfile.local (local OpenClaw tarball)"
+else
+  DOCKERFILE="$KILOCLAW_DIR/Dockerfile"
+fi
+
 # Read app name from argument, .dev.vars, or default
 APP_NAME="${1:-}"
 if [ -z "$APP_NAME" ] && [ -f "$KILOCLAW_DIR/.dev.vars" ]; then
@@ -26,7 +54,7 @@ TAG="dev-$(date +%s)"
 IMAGE="registry.fly.io/$APP_NAME:$TAG"
 GIT_SHA="$(git -C "$KILOCLAW_DIR" rev-parse HEAD 2>/dev/null || echo 'unknown')"
 
-# Extract OpenClaw version from Dockerfile
+# Extract OpenClaw version from Dockerfile (only available when using npm install)
 OPENCLAW_VERSION=$(sed -n 's/.*openclaw@\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' "$KILOCLAW_DIR/Dockerfile" | head -1)
 
 echo "Building + pushing $IMAGE (linux/amd64) ..."
@@ -38,7 +66,7 @@ trap 'rm -f "$METADATA_FILE"' EXIT
 
 docker buildx build \
   --platform linux/amd64 \
-  -f "$KILOCLAW_DIR/Dockerfile" \
+  -f "$DOCKERFILE" \
   --build-arg "CONTROLLER_COMMIT=$GIT_SHA" \
   --build-arg "CONTROLLER_CACHE_BUST=$(date +%s)" \
   -t "$IMAGE" \

src/app/api/gateway/embeddings/route.ts

@@ -0,0 +1 @@
+export { POST } from '@/app/api/openrouter/embeddings/route';