apale7
7c30e9d5eb
Align the binary, config, provider, proxy, tests, and docs with the OpenCode LocalProxy CLI rename so user-facing guidance and runtime identifiers stay consistent.
92 lines
2.7 KiB
Markdown
92 lines
2.7 KiB
Markdown
# opencode-provider-switch (`olpx`)
|
|
|
|
A tiny local proxy for [OpenCode](https://opencode.ai) that gives you **one
|
|
stable model alias** routed to **multiple upstream providers** with
|
|
**deterministic failover**.
|
|
|
|
- Expose one custom provider `olpx` to OpenCode.
|
|
- Configure logical aliases (`olpx/gpt-5.4`, etc.).
|
|
- Each alias has an ordered list of upstream `provider/model` targets.
|
|
- When the primary upstream returns `5xx`/`429`/connect error *before* any
|
|
stream bytes are flushed, `olpx` transparently retries the next target.
|
|
- Once a stream has started, the upstream is locked for the rest of that
|
|
request — no mid-stream splicing.
|
|
|
|
Protocol: OpenAI Responses (`POST /v1/responses`) only. Streaming supported.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
go build -o olpx ./cmd/olpx
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# 1. add upstream providers
|
|
olpx provider add --id su8 --base-url https://cn2.su8.codes/v1 --api-key sk-...
|
|
olpx provider add --id codex --base-url https://api-vip.codex-for.me/v1 --api-key sk-...
|
|
|
|
# 2. create alias and bind targets in priority order
|
|
olpx alias add --name gpt-5.4
|
|
olpx alias bind --alias gpt-5.4 --provider su8 --model gpt-5.4
|
|
olpx alias bind --alias gpt-5.4 --provider codex --model GPT-5.4
|
|
|
|
# 3. push alias exposure into OpenCode global config
|
|
olpx opencode sync
|
|
|
|
# 4. run the proxy
|
|
olpx serve
|
|
```
|
|
|
|
Inside OpenCode you can now pick `olpx/gpt-5.4`.
|
|
|
|
### Import providers from an existing OpenCode config
|
|
|
|
```bash
|
|
olpx provider import-opencode # reads global OpenCode config
|
|
olpx provider import-opencode --from ./examples/opencode.jsonc
|
|
```
|
|
|
|
The default import/sync target is the global user config only. It does not
|
|
follow `OPENCODE_CONFIG_DIR`; use `--from` or `--target` when you want a
|
|
different file.
|
|
|
|
Only `@ai-sdk/openai` custom providers with a `baseURL` and `apiKey` are
|
|
imported. Everything else is out of MVP scope.
|
|
|
|
### Doctor (static)
|
|
|
|
```bash
|
|
olpx doctor
|
|
```
|
|
|
|
Runs structural checks only — never issues real upstream requests.
|
|
|
|
## CLI reference
|
|
|
|
- `olpx serve` — run the proxy
|
|
- `olpx doctor` — validate config
|
|
- `olpx provider {add,list,remove,import-opencode}`
|
|
- `olpx alias {add,list,bind,unbind,remove}`
|
|
- `olpx opencode sync [--target FILE] [--set-model ALIAS] [--set-small-model ALIAS] [--dry-run]`
|
|
|
|
Global flag: `--config PATH` (default `$XDG_CONFIG_HOME/olpx/config.json`).
|
|
|
|
## Debug headers
|
|
|
|
Every proxied response includes:
|
|
|
|
- `X-OLPX-Alias`
|
|
- `X-OLPX-Provider`
|
|
- `X-OLPX-Remote-Model`
|
|
- `X-OLPX-Attempt`
|
|
- `X-OLPX-Failover-Count`
|
|
|
|
## Scope
|
|
|
|
Out of MVP: Anthropic native, multi-protocol routing, dashboard, billing,
|
|
latency-based routing, `/v1/models` discovery, full OpenCode config takeover.
|
|
See `.trellis/tasks/archive/2026-04/04-17-04-17-ops-mvp-design-review/prd.md`
|
|
for the authoritative design notes.
|