Pick a model per agent. Save. It talks native and survives Grok Bot updates.
Keys never leave your machine. Every wire claim in this repo is probe-verified, not vibed.
✨ The LiquidGlass Observatory
The old picker was a dropdown. This is the deck it grew into — a frosted-glass
mission-control panel that lives inside the Grok Bot window itself:
- Swap the brain mid-chat. Pick any bound model from the glass dropdown —
Claude, GLM, Qwen, Gemini — and the agent's next reply rides the new lane. No restart.
- VERIFIED HOP. Every switch is confirmed end-to-end through the hop proxy
before it counts; Copy Proof hands you the receipt.
- Live telemetry per bot. Throughput, TTFT latency, token flow and prompt-cache
hit rate, refreshed while the agent works.
- Context Guardian. Live bar against the 256k window so long marathons never
clip mid-run.
- 28 bots on one deck.
Show All Bots walks the whole fleet; Diagnostics &
Logs digs into the hop, Reset Chat clears a stuck thread.
- Zero install into Grok. Injected into the app bundle by opengrok, rides
silent Grok updates, MIT.
⚡ Quick start
What this repo is — and is not. opengrok is a config sidecar for an
existing Grok Bot install: it writes model bindings, wire maps, and a
health doctor next to your Grok Bot. It does not host or emulate Grok
Bot, does not control your machine, and does not ship auth shims — your
Grok Bot (desktop + optional cloud computer) stays exactly what it is; we
only tell it which model to talk to. A "hop" here simply means any
OpenAI-compatible base URL (the "OpenAI-compatible base URL" you'd paste in
other tools).
Prerequisites: a working Grok Bot install (desktop app), Python 3.9+,
Node 18+ (for the picker/maps), and API keys for any provider you bind.
git clone https://github.com/OnlyTerp/opengrok
cd opengrok
python setup.py
That's the whole install: it detects your Grok Bot install and live services,
adopts existing bindings or asks 3 questions, writes its config, baselines your
machine, and opens the picker. Then:
- pick a model for each agent in the dropdown
- test it live (one click, real request)
- save — done
python tools/doctor.py # anytime: is everything still healthy?
python tools/qa.py # repo self-check: leaks, refs, tests
🤖 What it gives each model
Dropping a foreign model into Grok Bot usually "works" and feels off — slower,
dumber, token-hungry. That's harness mismatch: the model was RL-trained on its
own harness's wire shape, and gets a generic prompt shape plus wrong reasoning
knobs. opengrok fixes the wire:
| Model family |
What goes wrong vanilla |
What opengrok does |
| Grok (xAI) |
effort knob is xhigh, not max; fast has no field |
literal token mapping, always-on reasoning documented |
| GLM (Zhipu) |
thinks by default — silence is expensive; max is real |
verified token table + true off-switch via thinking:disabled |
| Claude |
thinking is owned by the auth shim; body-painting it 400s |
shim-owned thinking, effort passes clean |
| Gemini |
"fast" was decorative — the knob is the slug, not a field |
fast lane rerouting, measured 1.5s → 0.9s first token |
| DeepSeek |
thinking lives in the model slug, not the body |
slug-owns-thinking mapping |
| local models |
context/recovery edges |
dedicated route, fail-closed |
Every row of that table is backed by a capture in wire-captures/
(see glm-5.3-flash for the full ladder —
bare request thinks by default, disabled really switches it off, max is a
real token).
🧩 How it fits together
Grok Bot agent
│ modelId + parameters (thinking/effort/fast)
▼
provider-maps ──► per-provider wire truth (verified, versioned, tested)
│
▼
upstream (xAI / Zhipu / Anthropic / Google / DeepSeek / local llama.cpp)
Two contracts, one story:
provider-maps.cjs — Contract A: direct body maps (client-side lanes)provider-maps-hop.cjs — Contract B: applyHarnessControls() for hop lanes — this is what ships on the box
Cloud agents need one more step. Stock Grok Bot cloud hosts do not read
model-bindings.json — a saved binding is ignored until you install the
binding consumer into the host. tools/apply-box-patch.py does that (anchored,
idempotent, backs up first), and tools/file-relay.py is the box-side file
relay the picker pushes bindings to. See CLOUD-HOST for
the full local → push → patch → bounce → verify flow.
🛡️ Update-proof by design
Grok Bot updates silently rewrite its bundle. Instead of hoping:
doctor.py baselines your machine on setup and watches files, services,
and caches — after any update it tells you exactly what moved--quiet mode stays silent when clean (cron-friendly), complains only on drift- maps hot-reload; no restart needed to fix a route
📚 The laws
Hard-won rules this repo encodes — each one earned by a real failure:
- Evidence or it doesn't ship. No map lands without a wire capture (
tools/wire-probe.py).
- 200-accepted ≠ honored. A field that 200s and does nothing is worse than a 400. Behavior-prove every knob.
- Silence is not cheap. Several providers think by default; a bare request burns reasoning tokens.
- Shared connection pools break under load; fresh-connection-per-call triggers throttling. Thread-local keep-alive or nothing.
- Fail-closed over fake success. If a control can't be expressed on the wire, document the noop — never pretend.
🧪 Testing (how we know it's true)
node tools/test-provider-maps.cjs # 23/23 — Contract A
node tools/test-provider-maps-hop.cjs # 6/6 — Contract B
python tools/qa.py # leak scan, ref integrity, suites
CI runs all three on every push and PR. The QA tool is itself
negative-control-tested: plant a fake key or break a file and it fails
loudly — a green that can't fail is decoration.
➕ Adding a provider
python tools/wire-probe.py --base https://api.example.com/v1 --model their-model --key-env THEIR_API_KEY
Run it, paste the verdict into a PR with the capture attached.
CONTRIBUTING.md has the contract — no capture, no merge.
🧠 Codex Everywhere
Codex Everywhere is configured in OpenClaw as the OpenAI Responses API
(openai-responses), while Grok Bot speaks Chat Completions. The repository
ships a local, dependency-free bridge for this protocol boundary:
python3 tools/codex-everywhere-bridge.py \
--api-key-env CE_API_KEY --port 18795
Provide CE_API_KEY through an OS-managed secret environment; never put it in
model-bindings.json. Bind a CE model to the bridge with
hopBaseUrl: "http://127.0.0.1:18795/v1" and the exact model ID, for example
gpt-5.6-terra. The bridge converts /v1/chat/completions into
/v1/responses, translates common tool, reasoning, and budget fields, and converts
JSON/SSE Responses replies back to Chat Completions. See
docs/CODEX-EVERYWHERE.md for the complete setup
and the current compatibility boundary.
🎙️ Voice assistant (voice/)
A full local realtime voice assistant built on the same wire-truth philosophy:
- Ears — streaming STT (Grok/xAI), energy-gated turn detection
- Captain — OpenAI realtime brain (
gpt-realtime-2.1) with consult/dispatch tools
- Mouth — ElevenLabs TTS (any voice, including your own clone), never-flush queue, barge-in
Browser panel UI, zero native audio deps, all lanes localhost-only. Setup is a
guided walkthrough (ElevenLabs key + Codex CLI login + Grok CLI login), with a
doctor that tells you exactly what's missing:
node voice/doctor.js # pre-flight check
voice\scripts\start-voice.ps1 # start everything, open the panel
See voice/README.md · voice/SETUP.md.
🗺️ Status
- ✅ Working today: Grok, GLM, Claude plans, Gemini (incl. fast lane), DeepSeek, local llama.cpp
- ✅ Bundled cloud hosts now supported —
tools/openai-hop-install.py installs the consumer into sealed 25 MB builders (the #3/#5/#8/#10 class), behavior-verified by a 105-check harness
- ✅ LiquidGlass Observatory — in-app frosted HUD: mid-chat model swaps, verified hops, per-bot telemetry, context guardian
- 🧪 Pattern proven, capture pending: OpenRouter, Groq, Mistral, xAI OAuth
- 📄 Docs: MODEL-GUIDELINES · BYOK vs hop · FAILURE-MODES · CLOUD-HOST · ROADMAP
not farming you, arming you.
opengrok 让你在现有的 Grok Bot 桌面安装中运行其他 LLM（Claude、GLM、Qwen、Gemini、DeepSeek、本地模型），并提供基于证据的线协议映射，让每个模型获得正确的请求格式，而不是通用的提示词。