How lanterncx/codex-gateway works
codex-gateway is a self-hosted OpenAI-compatible API gateway. The primary workflow is interactive OAuth login to save a token, then serving authenticated client requests by validating a fixed downstream key, obtaining or refreshing an OAuth access token, and proxying or adapting requests to an upstream service. It also exposes health and model endpoints, supports both Codex OAuth and direct OpenAI API modes, and provides structured request logging. Edges reflect the README and shown source; unsampled wiring is omitted where not established.
Main entry points: server.go HTTP server · auth_login.go OAuth login · client.go HTTP upstream client · handlers.go API handlers
Components 17
CLI and OAuth
- CLI commands
internal/cli/root.go - OAuth login
internal/cli/auth_login.go - Callback OAuth
internal/oauth/callback_flow.go - Device OAuth
internal/oauth/device_flow.go - Token storage
internal/auth/token_store.go - Token manager
internal/auth/manager.go
Gateway runtime
- HTTP server
internal/server/server.go - API handlers
internal/server/handlers.go - Key validation
internal/server/middleware_auth.go
Upstream access
- HTTP upstream client
internal/upstream/client.go
Configuration and observability
- Configuration
internal/config/config.go - Structured logging
internal/logging/logger.go - Request correlation
internal/logging/request_id.go
Other components
- Operator
- API client
- OAuth service
- OpenAI or Codex API
Connections 19
- Operator → CLI commands: runs commands
README.md - CLI commands → OAuth login: starts login
internal/cli/auth_login.go - OAuth login → Configuration: loads settings
internal/cli/auth_login.go - OAuth login → Callback OAuth: runs callback flow
internal/cli/auth_login.go - Callback OAuth → OAuth service: exchanges code
internal/oauth/callback_flow.go - OAuth login → Token storage: saves token
internal/cli/auth_login.go - Operator → Device OAuth: may use device flow
- Token manager → Token storage: loads and saves
internal/auth/manager.go - Token manager → OAuth service: refreshes token
- API client → HTTP server: sends API requests
README.md - HTTP server → Key validation: protects routes
internal/server/server.go - HTTP server → API handlers: routes requests
internal/server/server.go - API handlers → Token manager: gets access token
README.md - API handlers → HTTP upstream client: sends upstream requests
- HTTP upstream client → OpenAI or Codex API: makes HTTP request
internal/upstream/client.go - Configuration → HTTP server: configures endpoints
README.md - Configuration → HTTP upstream client: configures upstream mode
README.md - HTTP server → Structured logging: logs requests
- HTTP upstream client → Request correlation: reads request ID
internal/upstream/client.go