Connecting to ChatGPT

Connecting to ChatGPT

Codex Free connects to ChatGPT through a developer-mode connector. There are two connection styles: the native OpenAI tunnel (recommended — no public URL) and an externally managed tunnel (you run the proxy).

---

With the native OpenAI tunnel (recommended)

1. In ChatGPT, enable Developer mode.

2. Configure openaiTunnel in codex.config.json (or use codex-free quickstart), export the referenced runtime key, and start Codex Free. Keep the process running for connector discovery and every tool call.

3. In ChatGPT's connector/plugin settings, create a developer-mode connector with Connection type: Tunnel.

4. Select the same tunnel ID that Codex Free reports as ready. Set Authentication to None.

5. Set the connector's permissions to Allow all actions if you don't want per-call confirmations.

6. Enable the connector in a new chat and open with:

   Call get_agent_brief and follow it for the rest of this chat.
   
   Task: <what you want done>
   

There is no server URL to enter in this mode. OpenAI routes the selected tunnel to the supervised client, which supplies Codex Free's generated per-process bearer on the local hop. The startup banner prints the runtime-only /readyz and /metrics URLs; it does not advertise an admin UI because tunnel-client-runtime omits that surface.

Optional: gate the connector with a shared secret

Set conversationAuthToken in codex.config.json (32–256 ASCII bytes) to require each new chat to prove it before any tool works. When it's set, every tool except authenticate is refused until the conversation calls authenticate with the matching token; after that, the grant is remembered for that ChatGPT conversation (restored across MCP reconnects and restarts from a hashed record under ~/.codex-free/conversation-authorizations/, or scoped to the transport session for non-ChatGPT clients). Leave it unset to allow any conversation that can reach the connector. The wizard does not create this token — add it by hand. See Configuration and Security Model.

One-time tunnel setup

1. Create or obtain a tunnel ID in OpenAI Platform → Tunnels.

2. Create a restricted runtime API key whose principal has Tunnels Read + Use for that tunnel. Keep tunnel-management/admin credentials separate.

3. Reference the key from config — never paste the literal key:

   {
     "openaiTunnel": {
       "tunnelId": "tunnel_0123456789abcdef0123456789abcdef",
       "apiKeyRef": "env:CONTROL_PLANE_API_KEY"
     }
   }

4. Provide the key and start:

   export CONTROL_PLANE_API_KEY='...'
   codex-free --work-dir /path/to/your/project

The wizard (codex-free quickstart) does all of this for you and stores the key in a locked-down file: reference under ~/.codex-free/openai-tunnel/credentials/ — see Quick Start.

Using a preinstalled tunnel client

Set openaiTunnel.clientPath or pass --openai-tunnel-client /path/to/tunnel-client-runtime. Codex Free still checks the binary's version surface and required flags before starting it.

---

With an externally managed tunnel

1. Start Codex Free without openaiTunnel (add --multi-project for one connector shared across projects).
2. Put an authenticated reverse proxy or tunnel in front of port 3000.
3. Create a URL-based developer connector whose server URL is the resulting HTTPS URL with /mcp appended.
4. Configure the connector authentication your client supports, and enforce access controls at the proxy/tunnel layer.

ngrok http 3000 is fine for a disposable connectivity test, but an unprotected public URL is not an appropriate long-lived deployment. Use provider access policies, source restrictions, mTLS, OAuth, or another control. --api-key helps MCP clients that send a static bearer, though ChatGPT's connector auth may not support that form directly. Read Security Model before exposing this mode.

---

Onboarding a chat

instructions is the proper channel, but ChatGPT Web isn't reliable about showing it to the model. One line fixes that:

Call get_agent_brief and follow it for the rest of this chat.

Task: <what you want done>

Everything — the shell you're on, the allowlist, your repo's AGENTS.md, any saved plan — arrives with that one call. If a chat drifts back into generic-assistant behaviour, ask for the brief again to re-anchor it.

Multi-project chats

Select the project first. With an exact path:

Call set_project_root with path "my-project", then call get_agent_brief and follow it for the rest of this chat.

Task: <what you want done>

By intent (let the agent search):

Call list_projects with a query derived from the task. If exactly one candidate is unambiguous, pass its selector to set_project_root; otherwise ask me which project I mean. Then call get_agent_brief and follow it for the rest of this chat.

Task: <what you want done>

On a later turn in an already-bound chat, the path doesn't need repeating — just get_agent_brief. A conversation cannot switch projects once bound; start a new chat for a different project. See Multi-Project Mode.

---

See also

• Quick Start — the guided path through all of this.
• Security Model — what "Allow all actions" actually grants.
• Troubleshooting — connector not appearing, tools missing, etc.