qwen-proxy

The qwen-proxy project is a proxy server designed to bridge Qwen's API with OpenAI-compatible endpoints. It is intended for users who want to use Qwen models within applications or tools that expect the OpenAI API format.

Key capabilities include:

• Multi-account support: Automatically rotates through multiple accounts to manage and bypass request quotas.
• OpenAI Compatibility: Provides endpoints that mimic the OpenAI API structure.
• Streaming: Supports streaming responses for real-time text generation.
• Authentication: Features a QR code-based authentication flow.
• Token Management: Includes built-in token counting and management.
• Observability: Provides detailed debug logging.

The Qwen OpenAI-Compatible Proxy Server is a Node.js-based API proxy that acts as a bridge between OpenAI-compatible clients and the Qwen API. It allows you to use Qwen models through the standard OpenAI API interface, enabling seamless integration into existing applications designed for OpenAI.

Key features include:

• OpenAI Compatibility: Supports standard endpoints like /v1/chat/completions and /v1/models.
• Multi-Account Support: Manages multiple Qwen accounts with round-robin request routing and automatic failover.
• OAuth 2.0 Authentication: Uses the Device Authorization Flow with PKCE for secure login.
• Streaming Support: Handles both regular and streaming responses.
• Token Management: Includes built-in token counting and automatic token refresh logic.

The Qwen Proxy is undergoing a rewrite to transition from a JavaScript-based proxy to a robust TypeScript-based product. The product is designed to support two primary interfaces:

1. Headless/CLI Mode: Optimized for Docker, scripts, and automation.
2. Interactive TUI (Terminal User Interface): A Rezi-based interface for operators to manage logs, accounts, usage, and server controls.

The rewrite follows a phased approach to ensure no feature loss and to establish a stable TypeScript foundation before introducing the TUI layer.

The qwen-proxy is an OpenAI-compatible API proxy server designed to allow any application built for OpenAI's API to use Qwen models. It acts as a translation layer between an OpenAI-compatible client and the Qwen API.

Workflow: [OpenAI Client] (OpenAI Format) $\leftrightarrow$ [Proxy Server] (Translation Layer) $\leftrightarrow$ [Qwen API] (Qwen Models)

It solves the "cold start" problem for new models by leveraging the existing OpenAI ecosystem. It handles authentication, token refreshes, and request/response translation automatically.

The proxy determines whether to use a streaming or non-streaming path based on two conditions:

1. The client must request it via stream: true in the request body.
2. The server must have streaming enabled via the STREAM environment variable.

If both conditions are met, the server forwards chunks from the Qwen API to the client as Server-Sent Events. Otherwise, it falls back to a regular request/response cycle.

The proxy manages application data through two primary JSON files and a structured logging directory. This structure ensures that runtime settings and transient states are preserved across restarts.

Core Files

• config.json: Stores operator-chosen runtime settings, such as the current log level or preferred UI behavior.
• state.json: Stores transient application state, such as the last active TUI tab or last viewed panel state.

Log Directory Structure

Logs are organized into a log/ directory. Request-specific logs are grouped by a unique <requestId> to facilitate debugging:

log/
  error.log
  error-*.log
  req-<requestId>/
    client-request.json
    upstream-request.json
    response.json
    error.json

When reviewing usage reports (especially in the TUI), the following definitions apply to cache metrics:

• cache read: Tokens served from the cache.
• cache write: Tokens written or created for the cache.
• cache hit: Calculated as cache_read / (cache_read + cache_write).
• cache type: The upstream label provided by the model, such as ephemeral or mixed (if multiple types appear in a single day).

The Terminal User Interface (TUI) is a product requirement and must meet specific quality standards.

Implementation Prerequisites

Real TUI implementation must not begin until the core application runtime has been fully migrated to TypeScript. The following files must be migrated and retired from maintained source before TUI work starts:

• src/qwen/api.js
• src/qwen/auth.js
• src/server/*.js
• src/utils/fileLogger.js
• src/utils/liveLogger.js
• src/config.js
• src/cli/qwen-proxy.js

TUI Quality Standards

• Responsiveness: Must resize cleanly with terminal size changes and use available space effectively.
• Theming: Must support at least one strong dark theme and one strong light theme using semantic theme/surface tokens.
• Visual Coherence: Text, background, and surface colors must be semantically consistent to avoid looking like a broken debug panel.

The authentication flow (Add-account) is triggered from the Accounts screen and must be presented as a floating modal or overlay above the main content.

The modal must include:

• A verification link.
• User/device code.
• A terminal-compatible QR code block (rendered using terminal characters).
• Progress indicators (Waiting / Success / Failure).
• Action buttons: "Open browser" and "Close".
• An elevated visual surface to distinguish it from the background.

Acceptance Criteria: The QR block must render correctly as terminal characters, and the modal must maintain its layout while floating over the Accounts screen.

The TUI is designed to be a consumer of the core application logic without introducing unnecessary dependencies.

Core Architecture Rules:

• Dependency Rule: The TUI must use the same internal core services as the CLI/headless modes. It should not depend on the local HTTP API for core application actions.
• Navigation Model: Primary shell navigation should be sidebar-driven rather than top-tab-driven.

Recommended Rezi Widgets:

• logsConsole: For displaying live logs.
• table: For displaying accounts and usage statistics.
• virtualList: For handling long, browsable lists.
• fileTreeExplorer: For browsing request/debug artifacts.

The Artifacts screen provides a way to browse and preview debug data stored in req-<id> directories. It uses a split-pane layout:

• Left Pane: A tree-view file explorer supporting keyboard navigation, mouse selection, and scrolling to browse folders and files.
• Right Pane: A preview area that displays the content or metadata of the selected file (e.g., JSON content, file size, or path).

This separation ensures that deep inspection of specific requests does not interfere with the real-time log streaming in the Live screen.

The proxy uses the OAuth 2.0 Device Authorization Flow with PKCE to authenticate with Qwen. This is typically managed via the authenticate.ts CLI tool or the TUI, but the underlying logic uses these endpoints:

• POST /auth/initiate: Generates PKCE code verifier/challenge and requests device authorization from Qwen. Returns a verification URI and user code.
• POST /auth/poll: Polls for the authentication token using the device code and code verifier. Saves credentials upon success.