Configuration

The proxy is configured entirely through environment variables — there's no config file. Variable names match the Claude Code relay's wherever the concept is shared, so both proxies have a consistent config surface if you're running them side by side.

Environment variables

Fail-open vs. fail-closed

TAWA_PROXY_FAIL_MODE decides what happens if the call to Tawa's scan endpoint fails — not what happens when a scan succeeds and returns a block, which always blocks regardless of this setting.

• open (default): if the scan call itself fails, the request forwards to OpenAI anyway. A Tawa outage degrades you back to unprotected Codex CLI rather than a broken one.
• closed: if the scan call fails, the request is rejected instead of forwarded.

What triggers a block

By default, a scan verdict of BLOCK, HARD_BLOCK, or SANDBOX stops it — an OpenAI-shaped 400 error on the request side, or a synthetic mid-stream error SSE event on the response side that ends the stream before a blocked action or reply reaches the client. Every other verdict (ALLOW, REVIEW, SOFT_BLOCK, AMBIGUOUS, OOD) forwards through by default — same reasoning as the Claude Code relay: there's no human in a local CLI's loop to hand an ambiguous verdict to.

Override which tiers actually block with TAWA_PROXY_BLOCK_ACTIONS — a comma-separated list of any of ALLOW, REVIEW, SOFT_BLOCK, BLOCK, HARD_BLOCK, SANDBOX, AMBIGUOUS, OOD:

# Also stop on SOFT_BLOCK and REVIEW, not just the hard-block family:
TAWA_PROXY_BLOCK_ACTIONS=BLOCK,HARD_BLOCK,SANDBOX,SOFT_BLOCK,REVIEW

# Narrower than the default — only a HARD_BLOCK stops anything:
TAWA_PROXY_BLOCK_ACTIONS=HARD_BLOCK

Scanning the model's own reply

By default, the model's own visible reply (any message output item) is scanned too — before it reaches Codex CLI. This catches a different threat shape than action gating: a hijacked model can exfiltrate something it read (a secret in a file, credentials from a tool result) just by printing it in its answer, with no action item involved at all.

Turn it off entirely if that's not worth it for a given workflow:

TAWA_PROXY_SCAN_OUTPUT_TEXT=false

An empty reply (or one that's all whitespace) is never sent for scanning regardless of this setting. Action-item gating is unaffected either way; this only controls the text side.

Streaming checkpoints vs. standard mode

Once output-text scanning is on, TAWA_PROXY_OUTPUT_CHUNK_CHARS decides how it's scanned — the same cost/delay trade-off as the Claude Code relay, applied to message items instead of text content blocks:

• Streaming checkpoints (default, 400): every time roughly that many new characters have streamed in, the proxy scans everything accumulated so far and releases whatever's cleared to Codex CLI. One scan call per checkpoint.
• Standard mode (TAWA_PROXY_OUTPUT_CHUNK_CHARS=0): no mid-stream checkpoints — the entire reply is held until the model finishes generating it, scanned exactly once, then released or blocked as a single piece.

# Smaller checkpoints: closer to un-gated streaming, more scan calls
TAWA_PROXY_OUTPUT_CHUNK_CHARS=150

# Standard mode: one scan per reply, but nothing streams until it's done
TAWA_PROXY_OUTPUT_CHUNK_CHARS=0

Action items (function_call and everything else this proxy gates generically) are never chunked regardless of this setting — each is scanned exactly once, at response.output_item.done, since there's no per-item-type partial-JSON checkpoint that would mean anything across ~30 different item shapes.

Session correlation

Not implemented. The Claude Code relay forwards Claude Code's own x-claude-code-session-id header through to Tawa as session_id, confirmed from Claude Code's own docs. There's no confirmed equivalent header for Codex CLI, so this relay doesn't guess at one — every scan from it passes no session identifier. Worth adding once the actual mechanism (if any) is confirmed against a real Codex CLI session.

Not yet configurable here

• Per-user identifiers, Policy Studio directives, language hints, and a fully custom block predicate — none of these are available through this proxy yet. If you need any of them today, use the TypeScript or Python SDK directly.