# OpenClaw on Codex Pooler
OpenClaw is an open-source AI assistant that runs on your own devices and connects to the chat channels you use. It can carry out tasks with tools while keeping conversations available through its gateway. Connect it to Codex Pooler to use your Pool's models for the main assistant and background tasks.
## Before you start
- Install [OpenClaw](https://docs.openclaw.ai/install) using the official instructions for your operating system.
- Have a Codex Pooler URL reachable from the client.
- Create a [Pool API key](/getting-started/quick-start/) and choose a model available to that Pool.
## Configure the connection
Use the commands for the terminal that starts the client. Environment-variable assignments below apply to that terminal; desktop apps and services need the variables in their own launch environment.
### Config file paths
| OS | Default config file |
| --- | --- |
| macOS | `~/.openclaw/openclaw.json` |
| Linux | `~/.openclaw/openclaw.json` |
| Windows | `%USERPROFILE%\.openclaw\openclaw.json` |
If you set `OPENCLAW_CONFIG_PATH`, edit that file instead of the default shown below.
These are the default locations. On Windows, paste the `%USERPROFILE%`, `%APPDATA%` or `%LOCALAPPDATA%` path into File Explorer's address bar. For a client installed inside WSL, use the Linux paths and commands inside WSL. Keep any custom configuration folder or profile you already use.
Merge the following settings into `openclaw.json` at the path for your system, or the file selected by `OPENCLAW_CONFIG_PATH`. Make `CODEX_POOLER_API_KEY` available to the running OpenClaw process:
**macOS / Linux / WSL**
```bash
export CODEX_POOLER_API_KEY=""
```
**Windows PowerShell**
```powershell
$env:CODEX_POOLER_API_KEY = ""
```
OpenClaw's OpenAI provider should point `baseUrl` at Codex Pooler's `/v1` surface, use a Pool API key for model requests, and pin the agent runtime to `openclaw`. The older `pi` runtime id is a deprecated alias and should not be used in new Codex Pooler examples.
```json5 title="openclaw.json" frame="code"
{
agents: {
defaults: {
model: {
primary: "openai/gpt-6-sol",
list: [
{
id: "background",
model: "openai/gpt-6-luna",
},
],
},
compaction: { reserveTokens: 128000 },
},
},
models: {
mode: "merge",
providers: {
openai: {
baseUrl: "https://codex-pooler.example.com/v1",
apiKey: "${CODEX_POOLER_API_KEY}",
api: "openai-responses",
agentRuntime: { id: "openclaw" },
timeoutSeconds: 120,
models: [
{
id: "gpt-6-luna",
name: "GPT-6 Luna via Codex Pooler",
reasoning: true,
input: ["text", "image"],
contextWindow: 872000,
contextTokens: 828400,
maxTokens: 128000,
},
{
id: "gpt-6-sol",
name: "GPT-6 Sol via Codex Pooler",
reasoning: true,
input: ["text", "image"],
contextWindow: 872000,
contextTokens: 828400,
maxTokens: 128000,
},
{
id: "gpt-6-astra",
name: "GPT-6 Astra via Codex Pooler",
reasoning: true,
input: ["text", "image"],
contextWindow: 872000,
contextTokens: 828400,
maxTokens: 128000,
},
],
},
},
},
}
```
Define only model ids your assigned Pool can serve. If you run Codex Pooler locally, set `baseUrl` to `http://localhost:4000/v1`.
## Choose a model
OpenClaw separates the configured `contextWindow` from the effective runtime `contextTokens` budget. The `872000` raw-context / `828400` effective-budget values above are long-profile examples. Provider accounts can temporarily report different ceilings for the same model; a selected 272000-token profile exposes `258400` effective tokens. Use each model's `/v1/models.context_length` for `contextWindow`; set `contextTokens` to `floor(0.95 * context_length)` and do not configure the raw ceiling as the effective budget. For the long-profile example, the 128000-token compaction reserve keeps output accounting explicit and starts local compaction at 700400 tokens. Use `gpt-6-luna` for background routing, keep `gpt-6-sol` as the primary model, and select `gpt-6-astra` only when its Pool assignment permits it.
## Verify the connection
Start a new OpenClaw conversation with the configured primary model and send a short request. In Codex Pooler's request logs, match the request time, API key, model, and final status to your test. A reply alone does not confirm that the client used your Pooler instance.
If you configured a background model, check a background request as well: it must use a model available to the same Pool.
## Advanced configuration
### Custom provider option
If you want to keep Codex Pooler separate from OpenClaw's built-in OpenAI provider behavior, you can use a custom provider id such as `codex-pooler/gpt-6-sol` instead.
That follows OpenClaw's generic custom-provider shape, but tools that look specifically for `openai/gpt-*` model refs won't see it as canonical OpenAI. Prefer the `openai` provider shape above unless you need that separation.
## Operator MCP (optional)
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.
```json5 title="openclaw.json" frame="code"
{
mcp: {
servers: {
codex_pooler: {
url: "https://codex-pooler.example.com/mcp",
transport: "streamable-http",
headers: {
Authorization: "Bearer ",
},
},
},
},
}
```
Use `http://localhost:4000/mcp` only for local setup.
MCP uses an operator-owned MCP token, not a Pool API key. Don't reuse the Pool API key from the model provider block for `/mcp`.
## Compatibility notes
OpenClaw model requests use Codex Pooler's narrow OpenAI-compatible `/v1` support for selected SDK routes. Codex Pooler doesn't provide full OpenAI API parity.
`GET /v1/responses` is narrow Responses websocket compatibility, not `/v1/realtime` support. `/v1/realtime` and OpenAI Realtime SDK websocket or session routes are unsupported.
The operator MCP endpoint is rooted at `/mcp`. It uses an operator-owned MCP token, not a Pool API key.