Skip to content

Commit d56359b

Browse files
committed
docs(grok): state what the integration actually does on non-loopback and reload
The guide told users to swap api_key on a non-loopback bind, which no longer matches the code (auto-registration is refused there) and never addressed the unreachable 127.0.0.1 base_url. It now explains why the fence is loopback-only, gives a manual recipe with a reachable host and the admission token, and warns against env_key -- an unresolved one makes Grok fall through to the xAI session token and send it to whatever base_url the entry names. The reload note claimed hot reload without a version guarantee. Grok does watch config.toml and reload on a real [model] change, so the note now describes the observed mechanism, points at grok inspect for verification (config sources and rejected fields, not a model list), and records that one TOML error invalidates the whole user layer -- which is why we write atomically. Also corrects devlog 020, which recommended the responses backend against its own receipt: Grok's Responses event enum has no catch-all, so an unknown top-level type ends the turn with a non-retryable Serialization error.
1 parent 228f080 commit d56359b

2 files changed

Lines changed: 51 additions & 6 deletions

File tree

‎devlog/_plan/260723_grok_build_bridge/020_docs_and_residual_smoke.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,23 @@
22

33
Precondition: wp1 (usage details 상시 방출) 완료, 3-way 매트릭스 exit 0.
44

5+
> **정정 2026-07-26.** 아래 "백엔드 선택"의 `responses` 권장은 같은 유닛의
6+
> `011_receipt.md:53-55`(grok이 `response.heartbeat`에서 종료)와 모순됐고, 이후 구현은 그래서
7+
> `chat_completions`를 골랐다. 권장을 `chat_completions`로 정정하고 `responses`는 알려진 한계로
8+
> 기록한다. 근거는 추측이 아니라 원본이다: grok의 Responses 이벤트 열거형(async-openai 포크
9+
> `95b52ebd`)에는 catch-all 변형이 없고, 알 수 없는 최상위 `type` 태그는
10+
> `SamplingError::Serialization`으로 분류되어 **재시도 없이** 턴을 끝낸다. 삼켜지는 비표준
11+
> 이벤트는 doom-loop 체크 하나뿐이다. 상세: `devlog/_plan/260726_grok_build_prod/001` E5.
12+
513
## Deliverables
614

715
### 1. 사용자 문서 (docs-site)
816
- 위치 후보: `docs-site` 내 클라이언트 연동 섹션 (기존 Claude Code / Copilot 인바운드 문서 형식 답습 — P에서 실제 경로 확인).
917
- 내용:
1018
- 권장 config: `[model_providers.opencodex]` 블록 + 얇은 `[model.<alias>]` 목록 (Sol 분석의 신규 표면 활용, grok 0.2.101+).
11-
- 백엔드 선택: `responses` 권장 (wp1 이후 완전 동작; harness가 내부적으로 Responses vocab을 쓰는 경로 존재), `chat_completions`도 동작.
19+
- 백엔드 선택: **`chat_completions` 권장**. `responses`는 우리가 keep-alive로 보내는
20+
`response.heartbeat`를 grok이 역직렬화하지 못해 턴이 중단되므로 알려진 한계로 문서화한다.
21+
(수용값은 `chat_completions`(기본), `responses`, `messages` 셋이다.)
1222
- 인증: loopback은 아무 non-empty `XAI_API_KEY`/api_key로 충분(ocx가 무시), non-loopback은 ocx admission token.
1323
- 카탈로그: `GROK_MODELS_BASE_URL=http://127.0.0.1:10100/v1`.
1424
- 한계: grok 하니스 시스템 프롬프트는 xAI 톤 전제, 모델별 tool 동작 차이.

‎docs-site/src/content/docs/guides/grok-build.md‎

Lines changed: 40 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,23 @@ grok -m ocx-anthropic-claude-opus-4-8 -p "hello"
5050

5151
Grok Build requires a non-empty API key for custom models even on loopback. The injected
5252
entries carry a placeholder (`opencodex-loopback`) — opencodex ignores admission keys for
53-
loopback connections, so no real secret is involved. If you bind the proxy on a
54-
non-loopback host, replace the per-model `api_key` with your opencodex admission token.
53+
loopback connections, so no real secret is involved.
54+
55+
**Auto-registration is loopback-only.** When opencodex binds a non-loopback host — including
56+
the wildcards `0.0.0.0` and `::`, which expose every interface — requests need your real
57+
admission token, and a managed block cannot carry one safely. Writing the literal token would
58+
put your secret into `~/.grok/config.toml` and overwrite whatever you set there on the next
59+
`ocx start`/`ensure`/`restart`. So opencodex writes nothing at all in that case (and removes
60+
any block left over from an earlier loopback bind), and you configure the models yourself
61+
outside the managed markers, where nothing opencodex does can clobber them. See
62+
[Manual recipe](#manual-recipe-without-auto-registration) for the exact table, and set both
63+
`base_url` (a host that is actually reachable from where you run `grok`) and `api_key`
64+
(your `OPENCODEX_API_AUTH_TOKEN`).
65+
66+
Do not replace `api_key` with `env_key` here. With no `model_provider` set, an `env_key`
67+
that fails to resolve does not stop the request — Grok falls through to your xAI session
68+
token and sends it to whatever `base_url` the entry names, which for a LAN deployment is a
69+
plaintext HTTP endpoint that is not xAI.
5570

5671
The injected per-model `api_key` sits first in Grok's credential chain for these models,
5772
so turns against opencodex need no additional Grok login. Keep your normal `grok login` /
@@ -60,7 +75,8 @@ directly.
6075

6176
## Manual recipe (without auto-registration)
6277

63-
If you manage `~/.grok/config.toml` yourself, add per-model tables with **direct fields**:
78+
If you manage `~/.grok/config.toml` yourself — or opencodex is on a non-loopback bind — add
79+
per-model tables with **direct fields**, outside the `# >>> opencodex managed block` markers:
6480

6581
```toml
6682
[model.ocx-opus]
@@ -70,11 +86,25 @@ api_backend = "chat_completions"
7086
api_key = "opencodex-loopback"
7187
```
7288

89+
For a proxy reachable over the network, point `base_url` at the address `grok` can actually
90+
dial and use your admission token:
91+
92+
```toml
93+
[model.ocx-opus]
94+
model = "anthropic/claude-opus-4-8"
95+
base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1
96+
api_backend = "chat_completions"
97+
api_key = "your-OPENCODEX_API_AUTH_TOKEN"
98+
```
99+
73100
Do not rely on `[model_providers.<id>]` inheritance for the endpoint: as of Grok Build
74101
0.2.101 the inherited `base_url` is not applied to inference routing (requests fall
75102
through to the default xAI proxy and fail with 401). Direct per-model fields route
76103
correctly.
77104

105+
Quote any alias containing a dot: bare `[model.grok-4.5]` is a three-segment key path, not
106+
the id `grok-4.5`. Generated aliases avoid dots entirely for this reason.
107+
78108
## Known limitations
79109

80110
- **Responses backend and keep-alives:** opencodex emits a `response.heartbeat` keep-alive
@@ -88,7 +118,12 @@ correctly.
88118
`ocx service` setup, and if that unmanaged process dies the managed block can point at
89119
a dead proxy until the next `ocx start`/`ocx ensure` refreshes it.
90120
- **Config read timing:** start opencodex first, then launch `grok` for the most
91-
predictable results. Recent Grok Build versions watch `config.toml` and hot-reload
92-
`[model.*]` changes into an open session; older builds may need a restart.
121+
predictable results. Grok Build watches `~/.grok/config.toml` and reloads when the
122+
`[model]` table actually changes (roughly a one-second debounce, compared by content), so
123+
a refreshed block reaches an open session without a restart. To confirm what Grok parsed,
124+
run `grok inspect`: it lists the config sources it loaded and warns about any field it
125+
rejected. It does not print the resolved model list. Note that a single TOML error
126+
invalidates the *entire* user config layer, which is why opencodex writes the file
127+
atomically — Grok never sees a half-written config.
93128
- **Catalog updates:** the fenced block reflects the catalog at injection time. After
94129
adding providers or models, run `ocx ensure` (or restart the proxy) to refresh it.

0 commit comments

Comments
 (0)