# openai-oauth: turn a ChatGPT account into an OpenAI-compatible endpoint

> openai-oauth is a TypeScript monorepo that exposes a local OpenAI-compatible proxy, TypeScript SDK and React sign-in component on top of an existing ChatGPT or Codex login. It is convenient, and it inherits every constraint of the account it borrows.

**EvanZhouDev/openai-oauth** — Free AI with your ChatGPT account

- Repository: https://github.com/EvanZhouDev/openai-oauth
- Website: https://openai-oauth.vercel.app
- Stars: 1,382 · Forks: 227
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-14 · Updated: 2026-09-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/evanzhoudev-openai-oauth

## The gap openai-oauth fills between a ChatGPT subscription and an API key

Most tools that speak the OpenAI wire format want a base URL and an API key. A ChatGPT subscription gives you neither. openai-oauth closes that gap by running a local HTTP server that accepts OpenAI-shaped requests and forwards them upstream using the OAuth credentials already on the machine. The README frames it as "Free AI with your ChatGPT account", and the npm description is "Free OpenAI API access with your ChatGPT account".

The audience is narrow and specific. It is aimed at developers who already pay for ChatGPT or who use the Codex CLI, and who want that entitlement reachable from ordinary OpenAI-compatible clients: the Vercel AI SDK, the official OpenAI client, or anything else that lets you override a base URL. The v2 release adds a second audience: application developers who want end users to bring their own ChatGPT accounts through a React sign-in component, with the README noting it "Works across free and paid plans".

This is not an API-key replacement in the billing sense. Nothing in the documentation suggests you get a portable key, a quota dashboard or a service-level agreement. What you get is a local bridge between two systems that were not designed to talk to each other directly.

## How the proxy, credential store and client adapters fit together

The architecture is a local proxy in front of an upstream base URL. The CLI flag table lists the upstream default as https://chatgpt.com/backend-api/codex, so requests are not sent to api.openai.com; they go to the Codex backend with your account's OAuth credentials attached. That single detail explains most of the project's behaviour, including which models you see.

Credentials live in ~/.codex, which the README describes as "the same place codex CLI uses". That is a deliberate choice: if you already ran codex locally, openai-oauth picks up the session instead of asking you to authenticate again. Login itself listens on loopback and uses http://localhost:1455/auth/callback, described as "the local callback URL accepted by OpenAI OAuth".

Model discovery is account-aware. The --models flag defaults to "Account-specific Codex models discovered from ChatGPT", and /v1/models reflects that unless you override it with a comma-separated list. Discovery depends on a Codex client version, which defaults to the latest @openai/codex from npm with a bundled fallback, overridable through --codex-version. So the model list is a function of your account plus a client version, not a static table in the repository.

On the client side there are three adapters over the same core: the CLI proxy, the TypeScript SDK (@openai-oauth/local plus @openai-oauth/ai-sdk), and the React component (@openai-oauth/react). The SDK example calls createOpenAIOAuth(openaiCredentials()) and then uses the result as a model provider inside generateText, which means the adapter plugs into the AI SDK's provider interface rather than inventing a new one.

## Installing openai-oauth and running a first request through the proxy

The fastest path is the CLI, which needs no install step at all. Running it starts an OpenAI-compatible endpoint on port 10531 by default, and the README shows the banner it prints, including the base URL http://127.0.0.1:10531/v1 and the note that no API key is required.

```bash
npx openai-oauth@latest
```

If you are not signed in, the CLI asks you to sign in locally and stores credentials in ~/.codex. You can also authenticate without starting the server, which is useful when you only want the TypeScript SDK:

```bash
npx openai-oauth login
```

For a long-running session, the README documents detached mode and the companion commands for inspecting and stopping it. Pressing d keeps the process running in the background, or you can start it detached directly:

```bash
npx openai-oauth --detach
npx openai-oauth status
npx openai-oauth logs --follow
npx openai-oauth stop
```

With the proxy up, point any OpenAI-compatible client at http://127.0.0.1:10531/v1 and use any placeholder as the API key. The README lists /v1/responses, /v1/chat/completions and /v1/models as working endpoints, with streaming responses, tool calls and reasoning traces supported.

For code rather than a proxy, install the SDK packages and call the provider factory. The README's example imports openaiCredentials from @openai-oauth/local and wraps it with createOpenAIOAuth:

```bash
npm i @openai-oauth/local @openai-oauth/ai-sdk ai
```

```ts
import { createOpenAIOAuth } from "@openai-oauth/ai-sdk";
import { openaiCredentials } from "@openai-oauth/local";
import { generateText } from "ai";

const openai = createOpenAIOAuth(openaiCredentials());

const result = await generateText({
	model: openai("gpt-5.4-mini"),
	prompt: "Hello!",
});
```

The React path is heavier. It requires @openai-oauth/react, @openai-oauth/ai-sdk, ai and @ai-sdk/react, and first-time users are prompted to install a browser extension for Chrome or Firefox for authentication. The Next.js quickstart pairs a client component using SignInWithChatGPT and openaiAuthHeaders() with a route handler that reads credentials from @openai-oauth/react/server. That extension requirement is worth noticing before you plan a production sign-in flow around it.

## Where openai-oauth breaks down: account coupling and the known limitations

The central limitation is that the whole thing is a proxy over somebody's ChatGPT session. If that session is revoked, expires or belongs to a different account, the endpoint stops working. There is no API key to rotate and no fallback credential documented in the README. For a personal machine that is fine. For a shared service it is a single point of failure that lives outside your infrastructure.

The README points to a Known Limitations section for the full list, and that section is not reproduced in the repository's top-level README excerpt, so the exact gaps are not something this article can enumerate. What can be said is that the supported surface is explicitly bounded: three endpoints, streaming, tool calls and reasoning traces. Anything outside that list is unverified.

Model availability is another moving part. Because /v1/models is discovered from the account and depends on a Codex client version, the model ids you get are not stable identifiers you can hard-code and forget. The README's own examples use gpt-5.4-mini while the CLI banner advertises gpt-5.6-terra and gpt-5.6-sol, which is a reminder that the model set shifts with account access and upstream releases.

Binding is a real risk too. The --host flag defaults to 127.0.0.1, and the flag table warns that "Non-loopback hosts expose the proxy to your network". There is no authentication in front of the proxy by design, so changing that flag turns an unauthenticated OpenAI-shaped endpoint into a LAN service. The default is safe; the override is not.

Finally, the project has its own legal section and a PRIVACY.md at the repository root. Traffic flows through the ChatGPT Codex backend under your account, which is a different arrangement from a normal API key, and the README does not present it as an officially sanctioned access path.

## openai-oauth versus a plain OpenAI API key

The obvious alternative is an API key from OpenAI, used directly against api.openai.com with no proxy in between. The difference is not just convenience.

An API key is a credential you own independently of any consumer account. You can scope it, put it in a secrets manager, rotate it, and hand it to a server that runs without a human present. openai-oauth has none of those properties. Its credential is a ChatGPT or Codex login stored in ~/.codex, and its upstream is the Codex backend rather than the public API host.

What the API key path costs you is money per token and a separate signup. What openai-oauth costs you is coupling: your code depends on an account, on a local callback URL at http://localhost:1455/auth/callback for login, and on a model list that the account discovers rather than one you select. If your workload is a background job, a multi-tenant backend or anything that must run unattended, the API key is the right tool and openai-oauth is the wrong one.

There is also a middle position the README supports deliberately: the React component exists precisely so each end user brings their own ChatGPT account instead of you holding one key for everyone. That is a different product decision, not a cheaper version of the same one.

## Maintenance, licensing and what the repository layout tells you

The last push to the default branch was on 2026-07-15, and the v2.0.0 release ("OpenAI OAuth v2") landed the same day. That is the most recent activity the repository metadata shows. The project is not archived.

Licensing is Apache-2.0, and the v2 notes call this out explicitly, saying you can "Use OpenAI OAuth in both open-source and proprietary applications". That is a permissive arrangement with the usual Apache-2.0 expectations around NOTICE and attribution; a NOTICE file sits at the repository root. Nothing here is legal advice, and the interaction between this licence and OpenAI's own terms is a separate question the repository's Legal section and PRIVACY.md are the places to read.

The upgrade surface is the part worth weighing. This is a Bun workspace monorepo with turbo, biome and tsup, and the root package.json pins its toolchain tightly: bun@1.3.11, turbo 2.10.4, typescript 5.9.2, biome 2.3.10, plus overrides for esbuild 0.28.1 and postcss 8.5.17. If you consume the published packages rather than building the repo, those pins do not affect you. If you vendor or build it, they do.

More important is the coupling to @openai/codex for model discovery. The flag table says the default is the latest @openai/codex from npm with a bundled fallback, and --codex-version exists to override it. A project whose model list is derived from another package's version inherits that package's release cadence. Expect to revisit --codex-version when the discovered model ids drift from what your prompts assume.

## Conclusion

Adopt openai-oauth if you already have a ChatGPT or Codex login and want an OpenAI-compatible endpoint on 127.0.0.1:10531 for local tooling, prototypes or a bring-your-own-account React flow. Do not adopt it if you need a server-side API key that survives account changes, per-user billing, or an endpoint you can expose to the network. Before committing, verify that /v1/responses and /v1/chat/completions behave as your client expects, check the Known Limitations section for the gaps that matter to you, and confirm the version of @openai/codex that model discovery resolves to, since that is what determines which model ids appear in /v1/models.

## FAQ

### Is openai-oauth free to use?

The project itself is Apache-2.0 licensed and published on npm, so there is no licence fee. What it uses is your existing ChatGPT account, and the README says the React sign-in flow works across free and paid plans.

### What is openai-oauth used for?

It turns a ChatGPT or Codex login into an OpenAI-compatible endpoint at http://127.0.0.1:10531/v1, so clients that expect a base URL and an API key can talk to your account. It also ships a TypeScript SDK and a React component for letting end users sign in with their own ChatGPT accounts.

### How do I use openai-oauth?

Run npx openai-oauth@latest to start the local proxy, sign in when prompted, then point an OpenAI-compatible client at the printed base URL with any placeholder API key. If you prefer code over a proxy, install @openai-oauth/local and @openai-oauth/ai-sdk and call createOpenAIOAuth(openaiCredentials()).

### How does openai-oauth differ from an OpenAI API key?

An API key is an independent credential you can rotate and deploy to a server. openai-oauth instead reuses OAuth credentials stored in ~/.codex and forwards requests to the Codex backend at https://chatgpt.com/backend-api/codex, so it is tied to a specific account and machine.

## Sources

- [EvanZhouDev/openai-oauth on GitHub](https://github.com/EvanZhouDev/openai-oauth)
- [License: Apache-2.0](https://github.com/EvanZhouDev/openai-oauth/blob/main/LICENSE)
- [Project website](https://openai-oauth.vercel.app)
- [README](https://github.com/EvanZhouDev/openai-oauth/blob/main/README.md)
- [Releases](https://github.com/EvanZhouDev/openai-oauth/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/evanzhoudev-openai-oauth