Skip to content

Commit bd01201

Browse files
ndycodendycode
committed
docs: update documentation for v4.5.0 release
- Update README.md version references from 4.3.1 to @latest - Add health-aware rotation explanation to Multi-Account Setup section - Add retry behavior options table to Configuration section - Update docs/configuration.md with new env vars: - CODEX_PLUGIN_LOG_LEVEL (debug|info|warn|error) - CODEX_AUTH_RETRY_ALL_RATE_LIMITED - CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS - CODEX_AUTH_RETRY_ALL_MAX_RETRIES - Add retryAllAccountsRateLimited, retryAllAccountsMaxWaitMs, retryAllAccountsMaxRetries plugin config options - Update ARCHITECTURE.md with Multi-Account Rotation section: - Health-based account selection algorithm - Token bucket rate limiting parameters - Reason-aware backoff multipliers - RefreshQueue for concurrent token refresh
1 parent 9970c97 commit bd01201

3 files changed

Lines changed: 89 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Install the opencode-openai-codex-auth-multi plugin and add the OpenAI model def
5454
**Option B: One-command install**
5555

5656
```bash
57-
npx -y opencode-openai-codex-auth-multi@4.3.1
57+
npx -y opencode-openai-codex-auth-multi@latest
5858
```
5959

6060
This writes the config to `~/.config/opencode/opencode.json`, backs up existing config, and clears the plugin cache.
@@ -67,7 +67,7 @@ This writes the config to `~/.config/opencode/opencode.json`, backs up existing
6767

6868
```json
6969
{
70-
"plugin": ["opencode-openai-codex-auth-multi@4.3.1"]
70+
"plugin": ["opencode-openai-codex-auth-multi@latest"]
7171
}
7272
```
7373

@@ -99,7 +99,7 @@ This writes the config to `~/.config/opencode/opencode.json`, backs up existing
9999
2. Add the plugin to the `plugin` array:
100100
```json
101101
{
102-
"plugin": ["opencode-openai-codex-auth-multi@4.3.1"]
102+
"plugin": ["opencode-openai-codex-auth-multi@latest"]
103103
}
104104
```
105105

@@ -147,7 +147,7 @@ Add this to your `~/.config/opencode/opencode.json`:
147147
```json
148148
{
149149
"$schema": "https://opencode.ai/config.json",
150-
"plugin": ["opencode-openai-codex-auth-multi@4.3.1"],
150+
"plugin": ["opencode-openai-codex-auth-multi@latest"],
151151
"provider": {
152152
"openai": {
153153
"options": {
@@ -236,7 +236,7 @@ For legacy OpenCode (v1.0.209 and below), use `config/opencode-legacy.json` whic
236236

237237
## Multi-Account Setup
238238

239-
Add multiple ChatGPT accounts for higher combined quotas. The plugin automatically rotates between accounts when one is rate-limited.
239+
Add multiple ChatGPT accounts for higher combined quotas. The plugin uses **health-aware rotation** with automatic failover.
240240

241241
```bash
242242
opencode auth login # Run again to add more accounts
@@ -247,6 +247,12 @@ opencode auth login # Run again to add more accounts
247247
- `openai-accounts-switch` — Switch active account
248248
- `openai-accounts-status` — Show rate limit status
249249

250+
**How rotation works (v4.4.0+):**
251+
- Health scoring tracks success/failure per account
252+
- Token bucket prevents hitting rate limits
253+
- Hybrid selection prefers healthy accounts with available tokens
254+
- Always retries when all accounts are rate-limited (waits for reset)
255+
250256
**Storage:** `~/.opencode/openai-codex-accounts.json`
251257

252258
---
@@ -354,7 +360,7 @@ OpenCode uses `~/.config/opencode/` on **all platforms** including Windows.
354360
**Solutions:**
355361
1. Update plugin:
356362
```bash
357-
npx -y opencode-openai-codex-auth-multi@4.3.1
363+
npx -y opencode-openai-codex-auth-multi@latest
358364
```
359365
2. Ensure config has:
360366
```json
@@ -399,7 +405,7 @@ Works alongside oh-my-opencode. No special configuration needed.
399405
```json
400406
{
401407
"plugin": [
402-
"opencode-openai-codex-auth-multi@4.3.1",
408+
"opencode-openai-codex-auth-multi@latest",
403409
"oh-my-opencode@latest"
404410
]
405411
}
@@ -412,7 +418,7 @@ List this plugin BEFORE DCP:
412418
```json
413419
{
414420
"plugin": [
415-
"opencode-openai-codex-auth-multi@4.3.1",
421+
"opencode-openai-codex-auth-multi@latest",
416422
"@tarquinen/opencode-dcp@latest"
417423
]
418424
}
@@ -434,6 +440,14 @@ Create `~/.opencode/openai-codex-auth-config.json` for optional settings:
434440
|--------|---------|--------------|
435441
| `codexMode` | `true` | Uses Codex-OpenCode bridge prompt (synced with latest Codex CLI) |
436442

443+
### Retry Behavior (v4.4.0+)
444+
445+
| Option | Default | What it does |
446+
|--------|---------|--------------|
447+
| `retryAllAccountsRateLimited` | `true` | Wait and retry when all accounts are rate-limited |
448+
| `retryAllAccountsMaxWaitMs` | `0` | Max wait time (0 = unlimited) |
449+
| `retryAllAccountsMaxRetries` | `Infinity` | Max retry attempts |
450+
437451
### Environment Variables
438452

439453
```bash

‎docs/configuration.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,10 @@ Advanced plugin settings in `~/.opencode/openai-codex-auth-config.json`:
220220

221221
```json
222222
{
223-
"codexMode": true
223+
"codexMode": true,
224+
"retryAllAccountsRateLimited": true,
225+
"retryAllAccountsMaxWaitMs": 0,
226+
"retryAllAccountsMaxRetries": null
224227
}
225228
```
226229

@@ -229,15 +232,22 @@ Advanced plugin settings in `~/.opencode/openai-codex-auth-config.json`:
229232
| Option | Default | What it does |
230233
|--------|---------|--------------|
231234
| `codexMode` | `true` | Uses Codex-OpenCode bridge prompt (synced with Codex CLI) |
235+
| `retryAllAccountsRateLimited` | `true` | Wait and retry when all accounts are rate-limited |
236+
| `retryAllAccountsMaxWaitMs` | `0` | Max wait time in ms (0 = unlimited) |
237+
| `retryAllAccountsMaxRetries` | `Infinity` | Max retry attempts (null = unlimited) |
232238

233239
### Environment Variables
234240

235241
| Variable | Description |
236242
|----------|-------------|
237243
| `DEBUG_CODEX_PLUGIN=1` | Enable debug logging |
238244
| `ENABLE_PLUGIN_REQUEST_LOGGING=1` | Log all API requests |
245+
| `CODEX_PLUGIN_LOG_LEVEL=debug` | Set log level (debug, info, warn, error) |
239246
| `CODEX_MODE=0` | Temporarily disable bridge prompt |
240247
| `CODEX_MODE=1` | Temporarily enable bridge prompt |
248+
| `CODEX_AUTH_RETRY_ALL_RATE_LIMITED=0` | Disable wait-and-retry behavior |
249+
| `CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS=30000` | Set max wait time |
250+
| `CODEX_AUTH_RETRY_ALL_MAX_RETRIES=1` | Set max retries |
241251

242252
---
243253

‎docs/development/ARCHITECTURE.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -428,6 +428,62 @@ let include: Vec<String> = if reasoning.is_some() {
428428

429429
---
430430

431+
## Multi-Account Rotation (v4.4.0+)
432+
433+
### Health-Based Account Selection
434+
435+
The plugin tracks account health and uses intelligent rotation:
436+
437+
```
438+
Account Selection Flow:
439+
1. Score = (health × 2) + (tokens × 5) + (freshness × 0.1)
440+
2. Select account with highest score
441+
3. Consume token from bucket
442+
4. On success: health +1
443+
5. On rate limit: health -10, mark rate-limited
444+
6. On failure: health -20
445+
7. Passive recovery: +2 health/hour
446+
```
447+
448+
### Token Bucket Rate Limiting
449+
450+
Client-side rate limiting prevents hitting API limits:
451+
452+
| Parameter | Value |
453+
|-----------|-------|
454+
| Max tokens | 50 |
455+
| Regeneration | 6 tokens/min |
456+
| Consume per request | 1 token |
457+
458+
### Reason-Aware Backoff
459+
460+
Different rate limit reasons use different backoff multipliers:
461+
462+
| Reason | Multiplier | Description |
463+
|--------|------------|-------------|
464+
| `quota` | 3.0× | Daily quota exhausted |
465+
| `tokens` | 1.5× | Token limit hit |
466+
| `concurrent` | 0.5× | Concurrent request limit |
467+
| `unknown` | 1.0× | Default |
468+
469+
### RefreshQueue (v4.5.0+)
470+
471+
Prevents race conditions when multiple concurrent requests try to refresh the same token:
472+
473+
```typescript
474+
// Without RefreshQueue: N concurrent requests = N refresh attempts
475+
// With RefreshQueue: N concurrent requests = 1 refresh, N-1 await
476+
477+
const queue = getRefreshQueue();
478+
const tokens = await queue.queuedRefresh(refreshToken, async () => {
479+
return await actualRefresh(refreshToken);
480+
});
481+
```
482+
483+
**Source**: `lib/refresh-queue.ts`, `lib/rotation.ts`
484+
485+
---
486+
431487
## Performance Considerations
432488

433489
### Token Usage

0 commit comments

Comments
 (0)