codex-slot

codex-slot is a local multi-account / multi-workspace switcher for Codex.

中文文档

Overview

• Reuse the official ~/.codex login state
• Manage multiple accounts or workspaces as separate slots
• Refresh and cache the latest usage from the official usage endpoint
• Expose a local provider endpoint for Codex
• Optionally pin model requests to an OpenAI-compatible relay slot
• Proxy ChatGPT backend plugin requests through the selected cslot account
• Apply local block rules for temporary, 5-hour, and weekly limits
• Automatically switch ~/.codex/config.toml to the cslot provider while the local proxy is running (and restore it on stop)

Installation

npm i -g codex-slot

Verify:

codex-slot --help

This repository is the source repository. GitHub installation from the repository URL is not supported.

Quick Start

1. Import your current Codex login state:

codex-slot import current ~

import copies the official login state into ~/.cslot/homes/<name> instead of referencing the source HOME directly. current is only an example slot name, not a built-in account or workspace.

2. Check the latest usage:

codex-slot status

By default, status will:

• Refresh usage for all managed accounts
• Render a compact table with:
  • Remaining 5-hour / weekly quotas
  • Reset times
  • A status column with local block reasons and countdowns (for example: 5h_limited(2h27m))
• Enter an interactive mode where you can toggle enabled for accounts:
  • Up/Down: move selection
  • Space: toggle [x] enabled / [ ] disabled and save immediately
  • Enter / q: exit the interactive mode

If you only want a non-interactive snapshot of the current state:

codex-slot status --no-interactive

3. Start the local proxy:

codex-slot start
codex-slot start --port 4399

start will automatically write the required provider config into ~/.codex/config.toml. It prefers port 4399 by default and will switch to the next available port automatically when 4399 is busy, then sync that actual port into config. The local provider does not use a separate cslot API key; cslot authenticates upstream requests with the selected Codex ChatGPT account token internally.

codex-slot start

Commands

codex-slot add <name>
codex-slot del <name>
codex-slot rename <oldName> <newName>
codex-slot import <name> [HOME]
codex-slot status
codex-slot start [--port <port>]
codex-slot stop
codex-slot relay add <name> --base-url <url> --api-key <key>
codex-slot relay list
codex-slot use relay <name>
codex-slot use auth
codex-slot current

Common patterns:

• cslot import work ~/workspace-home
• cslot rename work work-main
• cslot relay add third --base-url https://relay.example.com/v1 --api-key sk-...
• cslot status
• cslot use relay third
• cslot use auth
• cslot start

Architecture

The project is intentionally split by responsibility:

• src/cli.ts: CLI bootstrap and command registration only
• src/account-commands.ts: account import, login, remove command handlers
• src/account-commands.ts: also owns slot rename command handling
• src/service-control.ts: background service lifecycle management
• src/status-command.ts: usage refresh output and interactive toggle UI
• src/codex-config.ts: managed ~/.codex/config.toml apply/restore logic
• src/backend-proxy-service.ts: ChatGPT backend proxy for Codex plugin/runtime requests
• src/relay-proxy-service.ts, src/model-proxy-dispatcher.ts, src/relay-store.ts: optional OpenAI-compatible relay slots and /v1/* model route dispatch
• src/account-store.ts, src/usage-sync.ts, src/scheduler.ts, src/status.ts: core domain and runtime logic
• src/text.ts: shared bilingual text and locale-independent formatting helpers

This keeps the CLI entry thin while preserving stable behavior in the lower-level modules.

How status Works

codex-slot status does not render stale data from the official registry.json cache.

Instead it:

1. Reads access_token, refresh_token, and account_id from the official Codex login state
2. Requests https://chatgpt.com/backend-api/wham/usage
3. Stores the latest result in ~/.cslot/state.json
4. Renders the latest local cache

Managed Codex Config

codex-slot start writes or updates a managed provider block like this, based on the current ~/.cslot/config.yaml:

[model_providers.cslot]
name = "cslot"
base_url = "http://127.0.0.1:4399/v1"
wire_api = "responses"
requires_openai_auth = true

Behavior:

• A managed marker block is inserted for model_provider = "cslot" and [model_providers.cslot]
• On cslot stop, the original model_provider line and original [model_providers.cslot] block are restored from the saved snapshot; legacy local bearer-token fields in the cslot provider are removed
• Other providers and settings in config.toml are left untouched
• If you start with --port, the port is saved to ~/.cslot/config.yaml
• If you start without --port, 4399 is preferred first and the next free port is chosen automatically on conflict, and the actual chosen port is written back to ~/.cslot/config.yaml and the managed provider block
• requires_openai_auth = true keeps Codex App treating the local cslot provider as a ChatGPT-authenticated provider, so plugin navigation and trusted plugin runtimes are not disabled as API-key/custom-provider mode
• /backend-api/* requests are forwarded to ChatGPT backend with the current selected account's upstream token; client Authorization headers are not forwarded upstream

OpenAI-compatible Relay Slots

Relay slots are optional model-only exits. They do not replace the official Codex / ChatGPT login state. Use codex-slot relay add to register a relay slot, then use codex-slot status for daily enable/disable and model-route selection.

codex-slot relay add third --base-url https://relay.example.com/v1 --api-key sk-...
codex-slot use relay third
codex-slot current

Behavior:

• /v1/* model requests are fixed to the selected relay slot
• Relay requests use the relay slot API key; client Authorization headers are not forwarded upstream
• Relay failures are returned directly and do not fall back to official cslot accounts
• /backend-api/* plugin/runtime requests still use the selected official Codex / ChatGPT login state
• Usage refresh only applies to official accounts, not relay slots
• In interactive status, press Space to enable/disable the selected account or relay slot, and press m to select the model route
• Run codex-slot use auth to restore /v1/* model requests to the official account scheduler

Codex App Plugins

codex-slot start also switches the main ~/.codex login state to the selected managed account while cslot is running. This keeps Codex app plugins that depend on the main ChatGPT login state working without a separate manual setup step.

Data Directory

codex-slot uses:

• ~/.cslot/config.yaml
• ~/.cslot/state.json
• ~/.cslot/cslot.pid
• ~/.cslot/logs/service.log

Limit Handling

• Weekly limit: blocked until the weekly reset time
• 5-hour limit: blocked until the 5-hour reset time
• Temporary limit: blocked for 5 minutes

Repository

• GitHub: https://github.com/openxiaobu/codex-slot
• Issues: https://github.com/openxiaobu/codex-slot/issues

Development

npm install
npm run build
npm run check