feat: /v1/responses passthrough endpoint + missing SSE event types + Docker docs fix (#37, #38)

- Add /v1/responses endpoint for raw Codex Responses API passthrough with
multi-account load balancing, no format translation
- Recognize response.output_item.done, response.incomplete, response.queued
SSE events to eliminate "Unknown event" debug log noise
- Add cp .env.example .env step to Docker quick start in README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CHANGELOG.md

@@ -8,10 +8,14 @@
 
 ### Fixed
 
+- README Docker 快速开始补充 `cp .env.example .env` 步骤，修复新用户因缺少 `.env` 文件导致 `docker compose up -d` 启动失败的问题 (#38)
+- 识别 `response.output_item.done`、`response.incomplete`、`response.queued` Codex SSE 事件，消除 "Unknown event" 日志噪音
 - 流式 SSE 请求不再设置 `--max-time` 墙钟超时，修复思考链（reasoning/thinking）在 60 秒处中断的问题；连接保护由 header 超时 + AbortSignal 提供，非流式请求（models、usage）超时不受影响
 
 ### Added
 
+- `/v1/responses` 端点：Codex Responses API 直通，无格式转换，支持原始 SSE 事件流和多账号负载均衡
+
 - 模型名后缀系统：通过模型名嵌入推理等级和速度模式（如 `gpt-5.4-high-fast`），CLI 工具（Claude Code、opencode 等）无需额外参数即可控制推理强度和 Fast 模式
 - `service_tier` 支持：接受 API 请求体中的 `service_tier` 字段（"fast" / "flex"），或通过 `-fast` 模型名后缀自动设置
 - Dashboard Speed 切换：模型选择器下方新增 Standard / Fast 速度切换按钮

README.md

@@ -58,6 +58,7 @@ cd codex-proxy
 ### Docker（推荐，所有平台通用）
 
 ```bash
+cp .env.example .env       # 创建环境变量文件（可编辑配置）
 docker compose up -d
 # 打开 http://localhost:8080 登录
 ```

README_EN.md

@@ -58,6 +58,7 @@ cd codex-proxy
 #### Docker (Recommended)
 
 ```bash
+cp .env.example .env       # Create env file (edit to configure)
 docker compose up -d
 # Open http://localhost:8080 to log in
 ```

src/index.ts

@@ -17,6 +17,7 @@ import { createWebRoutes } from "./routes/web.js";
 import { CookieJar } from "./proxy/cookie-jar.js";
 import { ProxyPool } from "./proxy/proxy-pool.js";
 import { createProxyRoutes } from "./routes/proxies.js";
+import { createResponsesRoutes } from "./routes/responses.js";
 import { startUpdateChecker, stopUpdateChecker } from "./update-checker.js";
 import { initProxy } from "./tls/curl-binary.js";
 import { initTransport } from "./tls/transport.js";
@@ -72,6 +73,7 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
   const chatRoutes = createChatRoutes(accountPool, cookieJar, proxyPool);
   const messagesRoutes = createMessagesRoutes(accountPool, cookieJar, proxyPool);
   const geminiRoutes = createGeminiRoutes(accountPool, cookieJar, proxyPool);
+  const responsesRoutes = createResponsesRoutes(accountPool, cookieJar, proxyPool);
   const proxyRoutes = createProxyRoutes(proxyPool, accountPool);
   const webRoutes = createWebRoutes(accountPool);
 
@@ -80,6 +82,7 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
   app.route("/", chatRoutes);
   app.route("/", messagesRoutes);
   app.route("/", geminiRoutes);
+  app.route("/", responsesRoutes);
   app.route("/", proxyRoutes);
   app.route("/", createModelRoutes());
   app.route("/", webRoutes);

src/routes/responses.ts

@@ -0,0 +1,279 @@
+/**
+ * POST /v1/responses — Codex Responses API passthrough.
+ *
+ * Accepts the native Codex Responses API format and streams raw SSE events
+ * back to the client without translation. Provides multi-account load balancing,
+ * retry logic, and usage tracking via the shared proxy handler.
+ */
+
+import { Hono } from "hono";
+import type { AccountPool } from "../auth/account-pool.js";
+import type { CookieJar } from "../proxy/cookie-jar.js";
+import type { ProxyPool } from "../proxy/proxy-pool.js";
+import type { CodexResponsesRequest, CodexInputItem, CodexApi } from "../proxy/codex-api.js";
+import { getConfig } from "../config.js";
+import { parseModelName, resolveModelId, getModelInfo } from "../models/model-store.js";
+import { EmptyResponseError } from "../translation/codex-event-extractor.js";
+import {
+  handleProxyRequest,
+  type FormatAdapter,
+} from "./shared/proxy-handler.js";
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// ── Passthrough stream translator ──────────────────────────────────
+
+async function* streamPassthrough(
+  api: CodexApi,
+  response: Response,
+  _model: string,
+  onUsage: (u: { input_tokens: number; output_tokens: number }) => void,
+  onResponseId: (id: string) => void,
+): AsyncGenerator<string> {
+  for await (const raw of api.parseStream(response)) {
+    // Re-emit raw SSE event
+    yield `event: ${raw.event}\ndata: ${JSON.stringify(raw.data)}\n\n`;
+
+    // Extract usage and responseId for account pool bookkeeping
+    if (
+      raw.event === "response.created" ||
+      raw.event === "response.in_progress" ||
+      raw.event === "response.completed"
+    ) {
+      const data = raw.data;
+      if (isRecord(data) && isRecord(data.response)) {
+        const resp = data.response;
+        if (typeof resp.id === "string") onResponseId(resp.id);
+        if (raw.event === "response.completed" && isRecord(resp.usage)) {
+          onUsage({
+            input_tokens: typeof resp.usage.input_tokens === "number" ? resp.usage.input_tokens : 0,
+            output_tokens: typeof resp.usage.output_tokens === "number" ? resp.usage.output_tokens : 0,
+          });
+        }
+      }
+    }
+  }
+}
+
+// ── Passthrough collect translator ─────────────────────────────────
+
+async function collectPassthrough(
+  api: CodexApi,
+  response: Response,
+  _model: string,
+): Promise<{
+  response: unknown;
+  usage: { input_tokens: number; output_tokens: number };
+  responseId: string | null;
+}> {
+  let finalResponse: unknown = null;
+  let usage = { input_tokens: 0, output_tokens: 0 };
+  let responseId: string | null = null;
+
+  for await (const raw of api.parseStream(response)) {
+    const data = raw.data;
+    if (!isRecord(data)) continue;
+    const resp = isRecord(data.response) ? data.response : null;
+
+    if (raw.event === "response.created" || raw.event === "response.in_progress") {
+      if (resp && typeof resp.id === "string") responseId = resp.id;
+    }
+
+    if (raw.event === "response.completed" && resp) {
+      finalResponse = resp;
+      if (typeof resp.id === "string") responseId = resp.id;
+      if (isRecord(resp.usage)) {
+        usage = {
+          input_tokens: typeof resp.usage.input_tokens === "number" ? resp.usage.input_tokens : 0,
+          output_tokens: typeof resp.usage.output_tokens === "number" ? resp.usage.output_tokens : 0,
+        };
+      }
+    }
+
+    if (raw.event === "error" || raw.event === "response.failed") {
+      const err = isRecord(data.error) ? data.error : data;
+      throw new Error(
+        `Codex API error: ${typeof err.code === "string" ? err.code : "unknown"}: ${typeof err.message === "string" ? err.message : JSON.stringify(data)}`,
+      );
+    }
+  }
+
+  if (!finalResponse) {
+    throw new EmptyResponseError(responseId, usage);
+  }
+
+  return { response: finalResponse, usage, responseId };
+}
+
+// ── Format adapter ─────────────────────────────────────────────────
+
+const PASSTHROUGH_FORMAT: FormatAdapter = {
+  tag: "Responses",
+  noAccountStatus: 503,
+  formatNoAccount: () => ({
+    type: "error",
+    error: {
+      type: "server_error",
+      code: "no_available_accounts",
+      message: "No available accounts. All accounts are expired or rate-limited.",
+    },
+  }),
+  format429: (msg) => ({
+    type: "error",
+    error: {
+      type: "rate_limit_error",
+      code: "rate_limit_exceeded",
+      message: msg,
+    },
+  }),
+  formatError: (_status, msg) => ({
+    type: "error",
+    error: {
+      type: "server_error",
+      code: "codex_api_error",
+      message: msg,
+    },
+  }),
+  streamTranslator: streamPassthrough,
+  collectTranslator: collectPassthrough,
+};
+
+// ── Route ──────────────────────────────────────────────────────────
+
+export function createResponsesRoutes(
+  accountPool: AccountPool,
+  cookieJar?: CookieJar,
+  proxyPool?: ProxyPool,
+): Hono {
+  const app = new Hono();
+
+  app.post("/v1/responses", async (c) => {
+    // Auth check
+    if (!accountPool.isAuthenticated()) {
+      c.status(401);
+      return c.json({
+        type: "error",
+        error: {
+          type: "invalid_request_error",
+          code: "invalid_api_key",
+          message: "Not authenticated. Please login first at /",
+        },
+      });
+    }
+
+    // Optional proxy API key check
+    const config = getConfig();
+    if (config.server.proxy_api_key) {
+      const authHeader = c.req.header("Authorization");
+      const providedKey = authHeader?.replace("Bearer ", "");
+      if (!providedKey || !accountPool.validateProxyApiKey(providedKey)) {
+        c.status(401);
+        return c.json({
+          type: "error",
+          error: {
+            type: "invalid_request_error",
+            code: "invalid_api_key",
+            message: "Invalid proxy API key",
+          },
+        });
+      }
+    }
+
+    // Parse request body
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      c.status(400);
+      return c.json({
+        type: "error",
+        error: {
+          type: "invalid_request_error",
+          code: "invalid_json",
+          message: "Malformed JSON request body",
+        },
+      });
+    }
+
+    if (!isRecord(body) || typeof body.instructions !== "string") {
+      c.status(400);
+      return c.json({
+        type: "error",
+        error: {
+          type: "invalid_request_error",
+          code: "invalid_request",
+          message: "Missing required field: instructions (string)",
+        },
+      });
+    }
+
+    // Resolve model (suffix parsing extracts service_tier and reasoning_effort)
+    const rawModel = typeof body.model === "string" ? body.model : "codex";
+    const parsed = parseModelName(rawModel);
+    const modelId = resolveModelId(parsed.modelId);
+    const modelInfo = getModelInfo(modelId);
+
+    // Build CodexResponsesRequest
+    const codexRequest: CodexResponsesRequest = {
+      model: modelId,
+      instructions: body.instructions,
+      input: Array.isArray(body.input) ? (body.input as CodexInputItem[]) : [],
+      stream: true,
+      store: false,
+    };
+
+    // Reasoning effort: explicit body > suffix > model default > config default
+    const effort =
+      (isRecord(body.reasoning) && typeof body.reasoning.effort === "string"
+        ? body.reasoning.effort
+        : null) ??
+      parsed.reasoningEffort ??
+      modelInfo?.defaultReasoningEffort ??
+      config.model.default_reasoning_effort;
+    const summary =
+      isRecord(body.reasoning) && typeof body.reasoning.summary === "string"
+        ? body.reasoning.summary
+        : "auto";
+    codexRequest.reasoning = { summary, ...(effort ? { effort } : {}) };
+
+    // Service tier: explicit body > suffix > config default
+    const serviceTier =
+      (typeof body.service_tier === "string" ? body.service_tier : null) ??
+      parsed.serviceTier ??
+      config.model.default_service_tier ??
+      null;
+    if (serviceTier) {
+      codexRequest.service_tier = serviceTier;
+    }
+
+    // Pass through tools and tool_choice as-is
+    if (Array.isArray(body.tools) && body.tools.length > 0) {
+      codexRequest.tools = body.tools;
+    }
+    if (body.tool_choice !== undefined) {
+      codexRequest.tool_choice = body.tool_choice as CodexResponsesRequest["tool_choice"];
+    }
+
+    // Client can request non-streaming (collect mode), but upstream is always stream
+    const clientWantsStream = body.stream !== false;
+
+    return handleProxyRequest(
+      c,
+      accountPool,
+      cookieJar,
+      {
+        codexRequest,
+        model: modelId,
+        isStreaming: clientWantsStream,
+      },
+      PASSTHROUGH_FORMAT,
+      proxyPool,
+    );
+  });
+
+  return app;
+}

src/translation/codex-event-extractor.ts

@@ -125,6 +125,21 @@ export async function* iterateCodexEvents(
         break;
       }
 
+      case "response.output_item.done":
+        // Completion marker — tool call data already delivered via delta/done events
+        break;
+
+      case "response.incomplete":
+        // Response was truncated/incomplete
+        if (typed.response.id) extracted.responseId = typed.response.id;
+        if (typed.response.usage) extracted.usage = typed.response.usage;
+        break;
+
+      case "response.queued":
+        // Response is queued for processing
+        if (typed.response.id) extracted.responseId = typed.response.id;
+        break;
+
       case "response.completed":
         if (typed.response.id) extracted.responseId = typed.response.id;
         if (typed.response.usage) extracted.usage = typed.response.usage;

src/types/codex-events.ts

@@ -82,6 +82,29 @@ export interface CodexFunctionCallArgsDoneEvent {
   name: string;
 }
 
+export interface CodexOutputItemDoneEvent {
+  type: "response.output_item.done";
+  outputIndex: number;
+  item: {
+    type: string;
+    id?: string;
+    call_id?: string;
+    name?: string;
+    arguments?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface CodexIncompleteEvent {
+  type: "response.incomplete";
+  response: CodexResponseData;
+}
+
+export interface CodexQueuedEvent {
+  type: "response.queued";
+  response: CodexResponseData;
+}
+
 export interface CodexErrorEvent {
   type: "error";
   error: { type: string; code: string; message: string };
@@ -107,6 +130,9 @@ export type TypedCodexEvent =
   | CodexReasoningSummaryDoneEvent
   | CodexCompletedEvent
   | CodexOutputItemAddedEvent
+  | CodexOutputItemDoneEvent
+  | CodexIncompleteEvent
+  | CodexQueuedEvent
   | CodexFunctionCallArgsDeltaEvent
   | CodexFunctionCallArgsDoneEvent
   | CodexErrorEvent
@@ -276,6 +302,34 @@ export function parseCodexEvent(evt: CodexSSEEvent): TypedCodexEvent {
       }
       return { type: "unknown", raw: data };
     }
+    case "response.output_item.done": {
+      if (isRecord(data) && isRecord(data.item)) {
+        return {
+          type: "response.output_item.done",
+          outputIndex: typeof data.output_index === "number" ? data.output_index : 0,
+          item: {
+            type: typeof data.item.type === "string" ? data.item.type : "unknown",
+            ...(typeof data.item.id === "string" ? { id: data.item.id } : {}),
+            ...(typeof data.item.call_id === "string" ? { call_id: data.item.call_id } : {}),
+            ...(typeof data.item.name === "string" ? { name: data.item.name } : {}),
+            ...(typeof data.item.arguments === "string" ? { arguments: data.item.arguments } : {}),
+          },
+        };
+      }
+      return { type: "unknown", raw: data };
+    }
+    case "response.incomplete": {
+      const resp = parseResponseData(data);
+      return resp
+        ? { type: "response.incomplete", response: resp }
+        : { type: "unknown", raw: data };
+    }
+    case "response.queued": {
+      const resp = parseResponseData(data);
+      return resp
+        ? { type: "response.queued", response: resp }
+        : { type: "unknown", raw: data };
+    }
     default:
       return { type: "unknown", raw: data };
   }