diff --git a/docs/configuration.md b/docs/configuration.md
index 29ae0fe..5555590 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -402,6 +402,18 @@ CODEX_MODE=1 opencode run "task"  # Temporarily enable
 - Messages bubble up in OpenCode exactly where SDK errors normally surface.
 - Helpful when working inside the OpenCode UI or CLI—users immediately see reset timing.
 
+### CODEX_BASE_URL
+
+**What it does:**
+- Overrides the ChatGPT backend URL the plugin talks to (default: `https://chatgpt.com/backend-api`)
+- OAuth headers and account info are still attached by the plugin as normal; only the destination host changes
+- Useful for routing traffic through a local optimization/logging proxy (e.g. Headroom) that forwards upstream
+
+**Usage:**
+```bash
+CODEX_BASE_URL=http://127.0.0.1:8787/backend-api opencode run "task"
+```
+
 ---
 
 ## Configuration Files
diff --git a/lib/constants.ts b/lib/constants.ts
index 0df6dfc..5115d4f 100644
--- a/lib/constants.ts
+++ b/lib/constants.ts
@@ -6,8 +6,9 @@
 /** Plugin identifier for logging and error messages */
 export const PLUGIN_NAME = "openai-codex-plugin";
 
-/** Base URL for ChatGPT backend API */
-export const CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+/** Base URL for ChatGPT backend API. Override with CODEX_BASE_URL to route through a local proxy. */
+export const CODEX_BASE_URL =
+	process.env.CODEX_BASE_URL || "https://chatgpt.com/backend-api";
 
 /** Dummy API key used for OpenAI SDK (actual auth via OAuth) */
 export const DUMMY_API_KEY = "chatgpt-oauth";
diff --git a/test/constants.test.ts b/test/constants.test.ts
new file mode 100644
index 0000000..5279056
--- /dev/null
+++ b/test/constants.test.ts
@@ -0,0 +1,31 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+describe('CODEX_BASE_URL override', () => {
+	const originalEnv = process.env.CODEX_BASE_URL;
+
+	beforeEach(() => {
+		delete process.env.CODEX_BASE_URL;
+		vi.resetModules();
+	});
+
+	afterEach(() => {
+		if (originalEnv === undefined) {
+			delete process.env.CODEX_BASE_URL;
+		} else {
+			process.env.CODEX_BASE_URL = originalEnv;
+		}
+		vi.resetModules();
+	});
+
+	it('defaults to the ChatGPT backend when unset', async () => {
+		const { CODEX_BASE_URL } = await import('../lib/constants.js');
+		expect(CODEX_BASE_URL).toBe('https://chatgpt.com/backend-api');
+	});
+
+	it('honors CODEX_BASE_URL when set, for routing through a local proxy', async () => {
+		process.env.CODEX_BASE_URL = 'http://127.0.0.1:8787/backend-api';
+		vi.resetModules();
+		const { CODEX_BASE_URL } = await import('../lib/constants.js');
+		expect(CODEX_BASE_URL).toBe('http://127.0.0.1:8787/backend-api');
+	});
+});