Skip to content

Commit d1d5d5e

Browse files
masterkainmasterkain
committed
docs(clients): sync setup guides
1 parent ed5271e commit d1d5d5e

10 files changed

Lines changed: 279 additions & 11 deletions

File tree

‎docs-site/public/llms.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Codex Pooler Public Docs For Agents
22

3-
Last reviewed: 2026-06-02
3+
Last reviewed: 2026-06-08
44

55
Canonical docs base: https://docs.codex-pooler.com/
66
Canonical llms index: https://docs.codex-pooler.com/llms.txt
@@ -13,8 +13,13 @@ Primary public docs:
1313
- https://docs.codex-pooler.com/getting-started/configuration/
1414
- https://docs.codex-pooler.com/clients/codex-cli/
1515
- https://docs.codex-pooler.com/clients/openai-compatible/
16+
- https://docs.codex-pooler.com/clients/aider/
17+
- https://docs.codex-pooler.com/clients/continue/
18+
- https://docs.codex-pooler.com/clients/cline/
19+
- https://docs.codex-pooler.com/clients/goose/
1620
- https://docs.codex-pooler.com/clients/opencode/
1721
- https://docs.codex-pooler.com/clients/openclaw/
22+
- https://docs.codex-pooler.com/clients/roo-code/
1823
- https://docs.codex-pooler.com/clients/hermes/
1924
- https://docs.codex-pooler.com/reference/runtime-routes/
2025
- https://docs.codex-pooler.com/reference/routing-strategies/
@@ -64,6 +69,7 @@ Privacy boundaries:
6469
Agent guidance:
6570
- Start with https://docs.codex-pooler.com/clients/codex-cli/ when configuring Codex backend clients.
6671
- Start with https://docs.codex-pooler.com/clients/openai-compatible/ when configuring selected OpenAI SDK-compatible clients.
72+
- Use the client-specific pages for Aider, Continue, Cline, Goose, OpenCode, OpenClaw, Roo Code, and Hermes setup snippets.
6773
- Use https://docs.codex-pooler.com/reference/routing-strategies/ when configuring Pools and routing behavior.
6874
- Use https://docs.codex-pooler.com/answers.md for short, citable answers about scope, routes, credentials, privacy, setup, and deployment.
6975
- Keep examples on http://localhost:4000 for local setup or https://codex-pooler.example.com for deployed product examples.

‎docs-site/src/content/docs/clients/aider.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Aider
3+
description: Configure Aider with Codex Pooler's narrow OpenAI-compatible /v1 surface and a Pool API key.
4+
---
5+
6+
Aider uses the OpenAI-compatible route with the `openai/` model prefix. Keep the Pool API key in the environment and point Aider's OpenAI API base at Codex Pooler's `/v1` surface.
7+
8+
For a deployed instance, use:
9+
10+
```yaml
11+
model: openai/gpt-5.5
12+
openai-api-base: https://codex-pooler.example.com/v1
13+
```
14+
15+
For local setup, use:
16+
17+
```yaml
18+
model: openai/gpt-5.5
19+
openai-api-base: http://localhost:4000/v1
20+
```
21+
22+
Smoke-test from a repository:
23+
24+
```bash
25+
export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
26+
aider --model openai/gpt-5.5 --message 'Reply with exactly: aider ok'
27+
```
28+
29+
The Pool API key authenticates `/v1` model requests. Do not use an operator MCP token as the OpenAI API key.

‎docs-site/src/content/docs/clients/cline.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Cline
3+
description: Configure Cline with Codex Pooler's narrow OpenAI-compatible /v1 surface and optional operator MCP metadata access.
4+
---
5+
6+
Cline's OpenAI-compatible provider id is `openai`. Configure it with the Pool API key, the Codex Pooler `/v1` base URL, and the model id that your assigned Pool can serve.
7+
8+
```bash
9+
cline auth \
10+
--provider openai \
11+
--apikey "$CODEX_POOLER_API_KEY" \
12+
--baseurl https://codex-pooler.example.com/v1 \
13+
--modelid gpt-5.5
14+
```
15+
16+
For local setup, change `--baseurl` to `http://localhost:4000/v1`.
17+
18+
For optional operator MCP in Cline CLI, add the remote server to `~/.cline/mcp.json`. Codex Pooler does not require this for model use. The VS Code extension opens its own MCP settings JSON from the Cline MCP Servers panel; use the same `mcpServers` shape there.
19+
20+
```json
21+
{
22+
"mcpServers": {
23+
"codex_pooler": {
24+
"url": "https://codex-pooler.example.com/mcp",
25+
"headers": {
26+
"Authorization": "Bearer <operator-mcp-token>"
27+
},
28+
"disabled": false,
29+
"autoApprove": []
30+
}
31+
}
32+
}
33+
```
34+
35+
For local MCP setup, change the MCP `url` to `http://localhost:4000/mcp`.
36+
37+
Use a Pool API key for `/v1` model requests and an operator MCP token for `/mcp`. Do not reuse the Pool API key for MCP.

‎docs-site/src/content/docs/clients/codex-cli.mdx‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Codex CLI
3-
description: Configure Codex CLI with Codex Pooler backend compatibility, HTTP/SSE fallback, and operator MCP access.
3+
description: Configure Codex CLI with Codex Pooler backend compatibility, HTTP/SSE fallback, optional operator MCP access, and local session migration.
44
---
55

66
![Codex Pooler Codex CLI integration](/codex-pooler-codex.png)
@@ -56,9 +56,9 @@ requires_openai_auth = true
5656

5757
Both providers use the same Pool API key and the same Codex backend compatibility route. Codex Pooler routes each request through Pool policy, account eligibility, limits, session continuity, and request accounting.
5858

59-
## Operator MCP endpoint
59+
## Optional operator MCP endpoint
6060

61-
Codex Pooler also exposes an operator MCP endpoint at `/mcp`. MCP uses an operator-owned MCP token, not a Pool API key.
61+
Codex Pooler also exposes an operator MCP endpoint at `/mcp`. This is an optional operator-only metadata add-on. Omit it for normal Codex runtime use. MCP uses an operator-owned MCP token, not a Pool API key.
6262

6363
```toml
6464
[mcp_servers.codex_pooler]
@@ -74,6 +74,72 @@ export CODEX_POOLER_MCP_KEY="<operator-mcp-token>"
7474

7575
Use `http://localhost:4000/mcp` only for local setup.
7676

77+
## Existing session migration
78+
79+
Codex filters resumable conversations by `model_provider`. If you already have sessions created with the built-in `openai` provider and want them to appear under `codex-pooler-ws`, re-tag both the JSONL transcripts and the newer SQLite state database.
80+
81+
Run these commands with Codex closed. They edit local Codex state in place. The transcript rewrite scans the whole sessions directory and can take a while on large installs. Set `TO_PROVIDER=codex-pooler-http` if you made the HTTP provider your default.
82+
83+
```bash
84+
set -eu
85+
86+
FROM_PROVIDER="openai"
87+
TO_PROVIDER="codex-pooler-ws"
88+
89+
find ~/.codex/sessions -type f -name '*.jsonl' \
90+
-exec perl -pi -e \
91+
"s/\"model_provider\":\"${FROM_PROVIDER}\"/\"model_provider\":\"${TO_PROVIDER}\"/g" \
92+
{} +
93+
94+
for db in ~/.codex/state_*.sqlite; do
95+
[ -e "$db" ] || continue
96+
sqlite3 "$db" \
97+
"UPDATE threads SET model_provider = '${TO_PROVIDER}' WHERE model_provider = '${FROM_PROVIDER}';"
98+
done
99+
```
100+
101+
On Windows, run the same migration from PowerShell. This expects `sqlite3` to be available on `PATH`.
102+
103+
```powershell
104+
$ErrorActionPreference = "Stop"
105+
106+
$FromProvider = "openai"
107+
$ToProvider = "codex-pooler-ws"
108+
$CodexHome = Join-Path $HOME ".codex"
109+
110+
$FromJson = '"model_provider":"' + $FromProvider + '"'
111+
$ToJson = '"model_provider":"' + $ToProvider + '"'
112+
113+
Get-ChildItem -Path (Join-Path $CodexHome "sessions") -Recurse -Filter "*.jsonl" |
114+
ForEach-Object {
115+
$Path = $_.FullName
116+
$TempPath = "$Path.tmp"
117+
$Reader = [System.IO.StreamReader]::new($Path)
118+
$Writer = [System.IO.StreamWriter]::new(
119+
$TempPath,
120+
$false,
121+
[System.Text.UTF8Encoding]::new($false)
122+
)
123+
124+
try {
125+
while (($Line = $Reader.ReadLine()) -ne $null) {
126+
$Writer.WriteLine($Line.Replace($FromJson, $ToJson))
127+
}
128+
} finally {
129+
$Reader.Dispose()
130+
$Writer.Dispose()
131+
}
132+
133+
Move-Item -Force $TempPath $Path
134+
}
135+
136+
Get-ChildItem -Path $CodexHome -Filter "state_*.sqlite" |
137+
ForEach-Object {
138+
sqlite3 $_.FullName `
139+
"UPDATE threads SET model_provider = '$ToProvider' WHERE model_provider = '$FromProvider';"
140+
}
141+
```
142+
77143
## Route boundaries
78144

79145
`/backend-api/codex/*` is an authenticated Codex backend compatibility surface. It is not a wildcard proxy and it is not the OpenAI-compatible `/v1` SDK surface.

‎docs-site/src/content/docs/clients/continue.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Continue
3+
description: Configure Continue with Codex Pooler's narrow OpenAI-compatible /v1 surface, model capabilities, and optional operator MCP metadata access.
4+
---
5+
6+
Continue can use Codex Pooler as an OpenAI-compatible provider by setting `provider: openai`, `apiBase` to `/v1`, and the Pool API key as a Continue secret. For `gpt-5*` models, Continue uses the Responses API by default.
7+
8+
```yaml
9+
name: Codex Pooler
10+
version: 1.0.0
11+
schema: v1
12+
13+
models:
14+
- name: GPT-5.5 via Codex Pooler
15+
provider: openai
16+
model: gpt-5.5
17+
apiBase: https://codex-pooler.example.com/v1
18+
apiKey: "${{ secrets.CODEX_POOLER_API_KEY }}"
19+
roles:
20+
- chat
21+
- edit
22+
- apply
23+
- summarize
24+
capabilities:
25+
- tool_use
26+
- image_input
27+
28+
# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
29+
mcpServers:
30+
- name: codex_pooler
31+
type: streamable-http
32+
url: https://codex-pooler.example.com/mcp
33+
requestOptions:
34+
timeout: 30000
35+
headers:
36+
Authorization: "Bearer ${{ secrets.CODEX_POOLER_MCP_KEY }}"
37+
```
38+
39+
For local setup, change `apiBase` to `http://localhost:4000/v1`. If you keep the optional operator MCP add-on locally, change the MCP `url` to `http://localhost:4000/mcp`.
40+
41+
The Pool API key authenticates model requests. The MCP token authenticates only the operator metadata endpoint.

‎docs-site/src/content/docs/clients/goose.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Goose
3+
description: Configure Goose with Codex Pooler's narrow OpenAI-compatible /v1 chat completions path and optional operator MCP metadata access.
4+
---
5+
6+
Goose's OpenAI provider supports OpenAI-compatible endpoints through `OPENAI_HOST` and `OPENAI_BASE_PATH`. Point the host at Codex Pooler and keep the Pool API key in the `OPENAI_API_KEY` environment variable or Goose's secret storage.
7+
8+
```yaml
9+
GOOSE_PROVIDER: openai
10+
GOOSE_MODEL: gpt-5.5
11+
OPENAI_HOST: https://codex-pooler.example.com
12+
OPENAI_BASE_PATH: v1/chat/completions
13+
```
14+
15+
For local setup, change `OPENAI_HOST` to `http://localhost:4000`.
16+
17+
For optional operator MCP metadata access, add a remote Streamable HTTP extension. Codex Pooler model use does not require this. Goose stores remote extension headers in its config, so use a dedicated MCP token.
18+
19+
```yaml
20+
# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
21+
extensions:
22+
codex_pooler:
23+
enabled: true
24+
type: streamable_http
25+
name: codex_pooler
26+
uri: https://codex-pooler.example.com/mcp
27+
headers:
28+
Authorization: "Bearer <operator-mcp-token>"
29+
timeout: 300
30+
bundled: null
31+
available_tools: []
32+
```
33+
34+
For local MCP setup, change the extension `uri` to `http://localhost:4000/mcp`.
35+
36+
Use a Pool API key for OpenAI-compatible model requests and an operator MCP token for `/mcp`. Do not reuse the Pool API key for MCP.

‎docs-site/src/content/docs/clients/openai-compatible.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,19 @@ Bearer <pool-api-key>
2525

2626
For local setup, use `http://localhost:4000/v1`.
2727

28+
## Tool-specific setup pages
29+
30+
Use the dedicated setup pages when configuring an agent or editor that has its own provider shape:
31+
32+
- [Aider](/clients/aider/)
33+
- [Continue](/clients/continue/)
34+
- [Cline](/clients/cline/)
35+
- [Goose](/clients/goose/)
36+
- [Hermes Agent](/clients/hermes/)
37+
- [OpenCode](/clients/opencode/)
38+
- [OpenClaw](/clients/openclaw/)
39+
- [Roo Code](/clients/roo-code/)
40+
2841
## Python SDK
2942

3043
```python

‎docs-site/src/content/docs/clients/openclaw.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
22
title: OpenClaw
3-
description: Configure OpenClaw with Codex Pooler's narrow OpenAI-compatible /v1 surface, current runtime id, model metadata, and operator MCP endpoint.
3+
description: Configure OpenClaw with Codex Pooler's narrow OpenAI-compatible /v1 surface, current runtime id, model metadata, and optional operator MCP endpoint.
44
---
55

66
![Codex Pooler OpenClaw integration](/codex-pooler-openclaw.png)
77

8-
OpenClaw should use Codex Pooler through the narrow OpenAI-compatible `/v1` surface. Keep `openai/*` model names when you want OpenClaw and its tools to treat the model as the canonical OpenAI provider path.
8+
OpenClaw should use Codex Pooler through the narrow OpenAI-compatible `/v1` surface. Keep `openai/*` model names when you want OpenClaw and its tools to treat the model as the canonical OpenAI provider path. The optional MCP block is only for operator metadata tools.
99

1010
For a deployed instance, use these URLs:
1111

@@ -35,7 +35,7 @@ OpenClaw's OpenAI provider should point `baseUrl` at Codex Pooler's `/v1` surfac
3535
providers: {
3636
openai: {
3737
baseUrl: "https://codex-pooler.example.com/v1",
38-
apiKey: "<pool-api-key>",
38+
apiKey: "${CODEX_POOLER_API_KEY}",
3939
api: "openai-responses",
4040
agentRuntime: { id: "openclaw" },
4141
timeoutSeconds: 300,
@@ -60,7 +60,7 @@ Define only model ids your assigned Pool can serve. If you run Codex Pooler loca
6060

6161
## Operator MCP server
6262

63-
Add Codex Pooler as a remote Streamable HTTP MCP server only when OpenClaw should inspect metadata that the operator can already see in the admin UI.
63+
Add Codex Pooler as a remote Streamable HTTP MCP server only when OpenClaw should inspect metadata that the operator can already see in the admin UI. Omit this block for normal model/runtime use.
6464

6565
```json5
6666
{

‎docs-site/src/content/docs/clients/opencode.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
---
22
title: OpenCode
3-
description: Configure OpenCode with Codex Pooler's narrow OpenAI-compatible /v1 surface and remote operator MCP endpoint.
3+
description: Configure OpenCode with Codex Pooler's narrow OpenAI-compatible /v1 surface and optional remote operator MCP endpoint.
44
---
55

66
![Codex Pooler OpenCode integration](/codex-pooler-opencode.png)
77

8-
OpenCode should use Codex Pooler through the narrow OpenAI-compatible `/v1` surface. The Pool API key authenticates model requests. A separate operator MCP token authenticates the remote MCP endpoint.
8+
OpenCode should use Codex Pooler through the narrow OpenAI-compatible `/v1` surface. The Pool API key authenticates model requests. A separate operator MCP token authenticates the optional remote MCP endpoint. MCP is not required for OpenCode to use Codex Pooler; it only gives an operator MCP host read-only metadata tools.
9+
10+
OpenCode websocket support is the narrow Responses websocket route at `GET /v1/responses`, not OpenAI Realtime SDK compatibility.
911

1012
For a deployed instance, use these URLs:
1113

@@ -25,6 +27,7 @@ Store the Pool API key outside the config and read it through environment expans
2527

2628
```jsonc
2729
{
30+
"$schema": "https://opencode.ai/config.json",
2831
"provider": {
2932
"openai": {
3033
"npm": "@ai-sdk/openai",
@@ -67,7 +70,7 @@ Define only model ids your assigned Pool can serve. If you run Codex Pooler loca
6770

6871
## Remote MCP example
6972

70-
Add Codex Pooler as a remote MCP server when the OpenCode host should inspect metadata that the operator can already see in the admin UI.
73+
Add Codex Pooler as a remote MCP server only when the OpenCode host should inspect metadata that the operator can already see in the admin UI.
7174

7275
```jsonc
7376
{

‎docs-site/src/content/docs/clients/roo-code.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Roo Code
3+
description: Configure Roo Code with Codex Pooler's narrow OpenAI-compatible /v1 surface and optional operator MCP metadata access.
4+
---
5+
6+
Roo Code is configured from its VS Code settings panel. Select the OpenAI-compatible provider and use the Codex Pooler `/v1` URL.
7+
8+
```text
9+
API Provider: OpenAI Compatible
10+
Base URL: https://codex-pooler.example.com/v1
11+
API Key: ${CODEX_POOLER_API_KEY}
12+
Model ID: gpt-5.5
13+
```
14+
15+
For local setup, change the base URL to `http://localhost:4000/v1`.
16+
17+
Roo Code supports project-level MCP configuration in `.roo/mcp.json`. This is only for optional operator MCP metadata access; Codex Pooler model use does not require it. This file can be committed when it contains only the endpoint shape; keep the MCP token in a private copy or configure it through the Roo MCP settings UI.
18+
19+
```json
20+
{
21+
"mcpServers": {
22+
"codex_pooler": {
23+
"type": "streamable-http",
24+
"url": "https://codex-pooler.example.com/mcp",
25+
"headers": {
26+
"Authorization": "Bearer <operator-mcp-token>"
27+
},
28+
"disabled": false,
29+
"timeout": 300
30+
}
31+
}
32+
}
33+
```
34+
35+
For local MCP setup, change the MCP `url` to `http://localhost:4000/mcp`.
36+
37+
Use a Pool API key for `/v1` model requests and an operator MCP token for `/mcp`. Do not reuse the Pool API key for MCP.

0 commit comments

Comments
 (0)