feat(test-local): default to keyless local Ollama provider; per-field Opik config

- Add a model-provider abstraction: `--provider ollama` (default) runs a local LLM
  in an Ollama sidecar (docker-compose.ollama.yml) so a real OpenClaw turn can be
  driven with no model-provider account or API key. `--provider openai` drives turns
  with a user-injected OPENAI_API_KEY (for stronger tool-calling or the Codex runtime
  that emits codex_app_server spans).
- Address Baz review (entrypoint.sh): write plugins.entries.opik-openclaw.config via
  per-field `config set` dot-paths instead of a hand-built JSON5 blob, so quotes /
  backslashes in OPIK_* env vars are stored verbatim (confirmed: the blob form fails
  config validation on a `"` in the value).
- Make OPIK_API_KEY optional (unauthenticated local Opik needs none).
- Document Opik targets (Comet Cloud + local self-hosted via host.docker.internal).
- Ollama config gotchas baked in: native baseUrl (no /v1), explicit models[] array,
  contextWindow large enough for the agent system prompt (default llama3.2:3b@131072).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: JetoPistola

README.md

@@ -237,47 +237,74 @@ the host.
 
 Prerequisites:
 
-- Docker
+- Docker (with Compose)
 - Node.js `>=22.12.0` and npm `>=10` (used on the host to pack the plugin)
-- An Opik project plus an `OPENAI_API_KEY` for the live model call
+- An Opik project to send traces to (see "Opik targets" below)
 - Optional: the GitHub `gh` CLI (used to check out PRs, including forks)
 
-Set the required credentials in your shell or in a gitignored `.env` (copy from
-`.env.example`):
+### Model provider
+
+By default the turn is driven by a **local LLM running in an Ollama sidecar** — no
+model-provider account or API key required. This is enough to verify trace export
+and LLM/tool spans. The first run pulls the model (default `llama3.2:3b`) into a
+named volume and reuses it afterwards; local CPU inference is slow.
+
+To drive turns with a **real provider** instead (stronger tool-calling, or the Codex
+runtime that produces `codex_app_server` spans), pass `--provider openai` and supply
+your own `OPENAI_API_KEY`. The key is yours, injected at runtime only, never baked
+into the image.
+
+### Opik targets
+
+Point `OPIK_URL_OVERRIDE` at whichever Opik you want traces to land in:
+
+- **Comet Cloud:** `https://www.comet.com/opik/api` (set `OPIK_API_KEY`)
+- **Local self-hosted Opik on your host:** `http://host.docker.internal:5173/api`
+  (`OPIK_API_KEY` can be omitted for unauthenticated local deployments)
+
+Set config in your shell or in a gitignored `.env` (copy from `.env.example`):
 
 ```bash
-export OPIK_API_KEY="your-api-key"
 export OPIK_URL_OVERRIDE="https://www.comet.com/opik/api"
-export OPENAI_API_KEY="sk-..."
+export OPIK_API_KEY="your-api-key"        # optional for unauthenticated local Opik
 # optional: OPIK_PROJECT_NAME (default openclaw), OPIK_WORKSPACE (default default)
+# only for --provider openai:
+export OPENAI_API_KEY="sk-..."
 ```
 
 Run a PR, a branch, or the current working tree:
 
 ```bash
-./scripts/test-local.sh 114                 # check out PR #114 and test it
-./scripts/test-local.sh my-feature-branch   # test a branch
-./scripts/test-local.sh --current           # test the current working tree as-is
+./scripts/test-local.sh 114                      # PR #114, local Ollama (default)
+./scripts/test-local.sh my-feature-branch        # a branch
+./scripts/test-local.sh --current                # the current working tree as-is
+./scripts/test-local.sh 114 --provider openai    # drive with a real provider / Codex
 ```
 
 The host runs only git: it checks out the PR/branch and exports a source snapshot
 with `git archive` (which executes no project code). The snapshot is mounted
 read-only into a clean Node 22 image that runs the latest `openclaw` (pin a
-specific version with `OPENCLAW_VERSION`); the container does `npm ci && npm pack`, installs the build,
-starts the gateway, and drops you into a shell. List the configured agents, then
-run a turn that triggers tool calls:
+specific version with `OPENCLAW_VERSION`); the container does `npm ci && npm pack`,
+installs the build, configures the provider + Opik export, starts the gateway, and
+drops you into a shell. List the configured agents, then run a turn that triggers
+tool calls:
 
 ```bash
 openclaw agents list
-openclaw agent --agent <id> --message "Use the shell tool to run 'echo hello', then reply done."
-# or run the embedded agent without routing:
-openclaw agent --local --message "Use the shell tool to run 'echo hello', then reply done."
+openclaw agent --session-id test1 --message "Use the shell tool to run 'echo hello', then reply done."
 ```
 
 Then open your Opik project and confirm the trace shows an LLM span and a tool span
 (e.g. `shell` / `apply_patch`), with `metadata.created_from = "openclaw"`. For
-Codex-native runs (PR #114) the spans also carry `metadata.source = "codex_app_server"`.
-Type `exit` to tear the container down.
+Codex-native runs (PR #114, `--provider openai`) the spans also carry
+`metadata.source = "codex_app_server"`. Type `exit` to tear the container down.
+
+Notes:
+
+- Small local models call tools less reliably than hosted ones; if a turn answers in
+  text instead of calling the tool, retry or use `--provider openai`.
+- Override the local model with `OLLAMA_MODEL` (must be tool-capable, e.g.
+  `qwen2.5-coder:7b`).
 
 ### Safety model
 
@@ -294,11 +321,12 @@ is not a substitute for trusting the code you run.
   `tmpfs` only), and pid/memory caps. The source snapshot is mounted read-only.
 - **Disposable.** `--rm` deletes the container and its writable layer on exit.
 - **Secrets at runtime only.** Credentials come from the environment (or a gitignored
-  `.env`) via `docker run -e`; they are never baked into the image. Note they are
-  live inside the running container by design, so treat `OPIK_API_KEY` /
-  `OPENAI_API_KEY` as scoped, burnable keys rather than shared production secrets.
-- **Not a sandbox.** Plain Docker shares the host kernel and has open network egress
-  (needed to reach Opik/OpenAI). Do not use this to run PRs you do not trust.
+  `.env`); they are never baked into the image. Any key you pass (`OPIK_API_KEY`, or
+  `OPENAI_API_KEY` with `--provider openai`) is live inside the running container by
+  design, so treat it as scoped/burnable rather than a shared production secret. The
+  default Ollama provider needs no key at all.
+- **Not a sandbox.** Plain Docker shares the host kernel and has open network egress.
+  Do not use this to run PRs you do not trust.
 
 ## Contributing
 

docker/docker-compose.ollama.yml

@@ -0,0 +1,67 @@
+# Ollama-backed local E2E: a local LLM sidecar so a real OpenClaw turn can be driven
+# with no model-provider account or API key. test-local.sh sets the env vars below.
+#
+#   SRC_DIR    host path to the git-archive source snapshot (mounted read-only)
+#   OUT_DIR    host path for run artifacts / span results
+#   OLLAMA_MODEL  tool-capable model to pull and run (default llama3.2:3b)
+#
+# The tester keeps the same hardening as the plain `docker run` path; the ollama
+# service holds the model in a named volume so it is pulled once and reused.
+services:
+  ollama:
+    image: ollama/ollama
+    environment:
+      OLLAMA_KEEP_ALIVE: "30m"
+    volumes:
+      - ollama-models:/root/.ollama
+    networks:
+      - e2e
+    healthcheck:
+      test: ["CMD", "ollama", "list"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+
+  tester:
+    image: opik-openclaw-e2e:local
+    depends_on:
+      ollama:
+        condition: service_healthy
+    environment:
+      MODEL_PROVIDER: ollama
+      OLLAMA_BASE_URL: "http://ollama:11434"
+      OLLAMA_MODEL: "${OLLAMA_MODEL:-llama3.2:3b}"
+      OPIK_API_KEY: "${OPIK_API_KEY}"
+      OPIK_URL_OVERRIDE: "${OPIK_URL_OVERRIDE}"
+      OPIK_PROJECT_NAME: "${OPIK_PROJECT_NAME:-openclaw}"
+      OPIK_WORKSPACE: "${OPIK_WORKSPACE:-default}"
+    volumes:
+      - "${SRC_DIR}:/src:ro"
+      - "${OUT_DIR}:/out"
+    networks:
+      - e2e
+    # Lets OPIK_URL_OVERRIDE point at a host-run local Opik via host.docker.internal.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    stdin_open: true
+    tty: true
+    # Hardening (mirrors scripts/test-local.sh): unprivileged, no new privileges,
+    # read-only rootfs with writable tmpfs only, bounded blast radius.
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges
+    read_only: true
+    pids_limit: 512
+    mem_limit: 4g
+    tmpfs:
+      - /work:exec,size=2g,uid=1000,gid=1000
+      - /home/node:exec,size=3g,uid=1000,gid=1000
+      - /tmp:size=512m,uid=1000,gid=1000
+
+networks:
+  e2e:
+    driver: bridge
+
+volumes:
+  ollama-models:

docker/entrypoint.sh

@@ -20,15 +20,35 @@ if [[ ! -d "${SRC_DIR}" || ! -f "${SRC_DIR}/package.json" ]]; then
   exit 1
 fi
 
-: "${OPIK_API_KEY:?OPIK_API_KEY is required}"
 : "${OPIK_URL_OVERRIDE:?OPIK_URL_OVERRIDE is required (e.g. https://www.comet.com/opik/api)}"
-: "${OPENAI_API_KEY:?OPENAI_API_KEY is required for the live model call}"
+# Optional: unauthenticated local Opik deployments do not need a key.
+OPIK_API_KEY="${OPIK_API_KEY:-}"
 OPIK_PROJECT_NAME="${OPIK_PROJECT_NAME:-openclaw}"
 OPIK_WORKSPACE="${OPIK_WORKSPACE:-default}"
-LIVE_MODEL="${OPENCLAW_LIVE_MODEL:-gpt-4o-mini}"
 GATEWAY_PORT="${OPENCLAW_GATEWAY_PORT:-18789}"
 GATEWAY_TOKEN="${OPENCLAW_GATEWAY_TOKEN:-local-e2e-token}"
 
+# Model provider. Default is a local Ollama sidecar (no account, no real key).
+# Set MODEL_PROVIDER=openai (and OPENAI_API_KEY) to drive turns with a real
+# provider instead — e.g. to exercise the Codex runtime or a stronger model.
+MODEL_PROVIDER="${MODEL_PROVIDER:-ollama}"
+if [[ "${MODEL_PROVIDER}" == "ollama" ]]; then
+  OLLAMA_BASE_URL="${OLLAMA_BASE_URL:-http://ollama:11434}"
+  OLLAMA_MODEL="${OLLAMA_MODEL:-llama3.2:3b}"
+  # Declare the model's full context. OpenClaw blocks windows below 16000 AND sizes
+  # its prompt budget from this number, so it must be large enough to hold the agent
+  # system prompt — too small overflows regardless of model size.
+  OLLAMA_CONTEXT_WINDOW="${OLLAMA_CONTEXT_WINDOW:-131072}"
+  AGENT_MODEL="ollama/${OLLAMA_MODEL}"
+elif [[ "${MODEL_PROVIDER}" == "openai" ]]; then
+  : "${OPENAI_API_KEY:?OPENAI_API_KEY is required when MODEL_PROVIDER=openai}"
+  LIVE_MODEL="${OPENCLAW_LIVE_MODEL:-gpt-4o-mini}"
+  AGENT_MODEL="openai/${LIVE_MODEL}"
+else
+  err "unsupported MODEL_PROVIDER: ${MODEL_PROVIDER} (expected 'ollama' or 'openai')"
+  exit 1
+fi
+
 # GATEWAY_PORT is interpolated unquoted into the config JSON below; a non-integer
 # would produce invalid JSON and fail the gateway with an opaque error, so reject it now.
 if ! [[ "${GATEWAY_PORT}" =~ ^[0-9]+$ ]]; then
@@ -66,6 +86,39 @@ export OPENCLAW_GATEWAY_TOKEN="${GATEWAY_TOKEN}"
 # Write only the gateway + model defaults first. The plugin entry must NOT exist
 # yet: `openclaw plugins install` validates config and aborts if it references a
 # not-yet-installed plugin, and it injects plugins.entries.opik-openclaw itself.
+#
+# For Ollama, declare an explicit provider (baseUrl points at the sidecar; explicit
+# config disables auto-discovery, so a manual model entry is required). Use the
+# native Ollama API URL — no /v1 suffix, which would break tool calling.
+if [[ "${MODEL_PROVIDER}" == "ollama" ]]; then
+  PROVIDERS_BLOCK=$(cat <<JSON
+,
+  "models": {
+    "providers": {
+      "ollama": {
+        "apiKey": "ollama-local",
+        "baseUrl": "${OLLAMA_BASE_URL}",
+        "api": "ollama",
+        "models": [
+          {
+            "id": "${OLLAMA_MODEL}",
+            "name": "${OLLAMA_MODEL}",
+            "reasoning": false,
+            "input": ["text"],
+            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+            "contextWindow": ${OLLAMA_CONTEXT_WINDOW},
+            "maxTokens": 2048
+          }
+        ]
+      }
+    }
+  }
+JSON
+)
+else
+  PROVIDERS_BLOCK=""
+fi
+
 cat > "${CONFIG_PATH}" <<JSON
 {
   "gateway": {
@@ -76,22 +129,31 @@ cat > "${CONFIG_PATH}" <<JSON
   },
   "agents": {
     "defaults": {
-      "model": { "primary": "openai/${LIVE_MODEL}" }
+      "model": { "primary": "${AGENT_MODEL}" }
     }
-  }
+  }${PROVIDERS_BLOCK}
 }
 JSON
 
 info "installing plugin build into OpenClaw..."
 ${OPENCLAW} plugins install "${TARBALL_PATH}"
 
-# Merge Opik settings into the install-updated config via config set (dot-path,
-# JSON5 value) rather than overwriting the file — install expands many defaults we
-# must preserve. No "hooks" key: openclaw 2026.3.2 rejects it as unrecognized; the
-# plugin registers its own conversation hooks on load.
+# Merge Opik settings into the install-updated config via config set, one field at a
+# time. Setting each scalar with its own dot-path passes the value as a raw string, so
+# quotes/backslashes in OPIK_* env vars are stored verbatim — a hand-built JSON5 blob
+# would break parsing or corrupt the value. install expands many defaults we preserve.
+# No "hooks" key: openclaw 2026.3.2 rejects it as unrecognized; the plugin registers
+# its own conversation hooks on load. tags is a fixed literal (no user input).
 info "configuring Opik export..."
-${OPENCLAW} config set plugins.entries.opik-openclaw.config \
-  "{enabled:true,apiUrl:\"${OPIK_URL_OVERRIDE}\",apiKey:\"${OPIK_API_KEY}\",projectName:\"${OPIK_PROJECT_NAME}\",workspaceName:\"${OPIK_WORKSPACE}\",tags:[\"local-docker-e2e\"]}"
+PLUGIN_CFG="plugins.entries.opik-openclaw.config"
+${OPENCLAW} config set "${PLUGIN_CFG}.enabled" true
+${OPENCLAW} config set "${PLUGIN_CFG}.apiUrl" "${OPIK_URL_OVERRIDE}"
+if [[ -n "${OPIK_API_KEY}" ]]; then
+  ${OPENCLAW} config set "${PLUGIN_CFG}.apiKey" "${OPIK_API_KEY}"
+fi
+${OPENCLAW} config set "${PLUGIN_CFG}.projectName" "${OPIK_PROJECT_NAME}"
+${OPENCLAW} config set "${PLUGIN_CFG}.workspaceName" "${OPIK_WORKSPACE}"
+${OPENCLAW} config set "${PLUGIN_CFG}.tags" '["local-docker-e2e"]'
 ${OPENCLAW} config set plugins.allow '["opik-openclaw"]'
 
 if ! ${OPENCLAW} config validate; then
@@ -130,6 +192,8 @@ cat <<GUIDE
 
 $(info "gateway ready — plugin installed and tracing to Opik")
 
+  Provider:  ${MODEL_PROVIDER}
+  Model:     ${AGENT_MODEL}
   Project:   ${OPIK_PROJECT_NAME}
   Workspace: ${OPIK_WORKSPACE}
   Endpoint:  ${OPIK_URL_OVERRIDE}