mirror of
https://github.com/dtzp555-max/olp.git
synced 2026-07-21 21:15:10 +00:00
5d60a0599f
The previous version of docs/integrations/openclaw.md assumed
loopback OpenClaw+OLP co-located on the same host. Two real gaps:
1. **Client-mode (OpenClaw on a different machine than OLP) is
the common family-deployment shape**, and the loopback config
recipe doesn't work there. Specifically:
- apiKey field is silently overridden by OpenClaw's service-managed
env (`OPENCLAW_SERVICE_MANAGED_ENV_KEYS=DEEPSEEK_API_KEY,OPENAI_API_KEY`).
The OpenClaw gateway clobbers `process.env.OPENAI_API_KEY` with
whatever ChatGPT key it's been authed against, so when an
openai-completions provider falls back to env-var auth, the
wrong token gets sent and OLP rejects with 401.
- The escape hatch is `headers.Authorization: Bearer olp_...` in
the provider config, which beats the env fallback because
OpenClaw merges `providerConfig.headers` at request-build time
(sanitizeModelHeaders → outgoing request).
2. **codex / OpenAI models via OLP routing wasn't documented at
all.** OpenClaw's stock `openai-codex` provider talks to ChatGPT
directly (bypasses OLP, no audit, no per-key tracking). To get
gpt-5.5 / gpt-5.3-codex etc. routed through OLP for per-key
observability, you have to register a custom `olp-openai`
provider — recipe now included.
Changes to docs/integrations/openclaw.md:
- Restructured into Mode A (server-co-located) vs Mode B (client-mode)
with explicit "pick yours" table up top.
- Mode B fully written out — proxyUrl with server IP, headers.Authorization
override, claude-local provider listed with the three Claude IDs that
OLP's /v1/models actually exposes.
- New § "Using codex / OpenAI models through OLP" with olp-openai
provider recipe + agents.defaults.models alias examples + warning
about why NOT to use OpenClaw's stock openai-codex provider.
- New § Gotchas covering: OPENCLAW_SERVICE_MANAGED_ENV_KEYS clobber,
default-agent-model points-at-removed-provider, /new doesn't reset
model selection, the openclaw.extensions schema-drift (was already
there).
- New § Troubleshooting table mapping symptoms → root causes → fixes.
Discovered live on Mac mini 2026-05-27 during PI231-as-server topology
bring-up. The "apiKey shadowed by env" finding required reading
OpenClaw source (`/opt/homebrew/lib/node_modules/openclaw/dist/...`)
to confirm the `providerConfig.headers` precedence. Verified end-to-end:
Telegram bot now routes free-text through claude-local → PI231 OLP →
claude spawn → reply; and `/models olp-openai/gpt-5.5` switches to
codex via OLP with per-key audit visible on dashboard.
Co-authored-by: dtzp555 <dtzp555@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
OLP IDE & client integrations
This directory documents per-tool setup for the IDEs and AI clients OLP supports. Every page follows the same shape: one-line description, status icon, copy-paste-able config block, known issues, OLP-specific notes, and a one-line verification command.
Index
| Tool | Status | Path | Notes |
|---|---|---|---|
| Continue.dev | ✅ Supported | VS Code / JetBrains extension | config.yaml (NOT config.json); supports custom headers |
| Cline | ✅ Supported | VS Code extension | OpenAI-compatible provider; UI field occasionally vanishes (Cline #7128) |
| Cursor | ⚠️ Best-effort | Cursor editor | "Override OpenAI Base URL" — known fragile across releases |
| Aider | ✅ Supported | terminal CLI | OPENAI_API_BASE env + openai/ model prefix |
| Claude Code | ❌ Not supported | terminal CLI | Anthropic wire format only; OLP serves OpenAI wire format. Use Cline instead. |
| OpenClaw | ✅ Supported | Telegram + Discord gateway | /olp slash command via the olp-plugin/ plugin |
Status legend
- ✅ Supported — works against OLP's OpenAI-compatible
/v1/chat/completionsendpoint; the tool's IR fields flow through OLP's IR without lossy translation warnings on the documented chain. - ⚠️ Best-effort — works in current versions but the tool has known upstream bugs around base-URL configuration; expect occasional weirdness.
- ❌ Not supported — the tool's wire protocol or transport is incompatible with what OLP serves; recommended alternative is documented on the page.
How OLP's response headers help debugging
Every response carries (see README § Response Headers):
X-OLP-Provider-Used— which provider's plugin served the requestX-OLP-Model-Used— which model the served provider usedX-OLP-Fallback-Hops—0= primary chain entry served itX-OLP-Cache—hit | miss | bypassX-OLP-Latency-Ms— end-to-end latency at the proxy
When something looks wrong in an IDE, the first sanity check is curl -i
against /v1/chat/completions with the same key — those headers tell you
whether the IDE config is broken or OLP routed somewhere unexpected.
Cross-references
- ADR 0010 — Phase 4 charter; documents why
/v1/messagesis not supported and points to Cline as the recommended Anthropic-CLI replacement. - ADR 0011 — trusted-LAN-only invariant for
auth.advertise_anonymous_key. bin/olp-connect— automated client setup helper (D68-D70).