fix: make instructions optional in /v1/responses for client compatibility (#71) (#112)

Cherry and other third-party clients don't send the `instructions` field.
Previously this returned 400; now it defaults to an empty string.

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

CHANGELOG.md

@@ -6,6 +6,11 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- `/v1/responses` 不再强制要求 `instructions` 字段，未传时默认空字符串（#71）
+  - 修复 Cherry 等第三方客户端不传 `instructions` 时返回 400 的兼容性问题
+
 ### Added
 
 - Sticky rotation strategy（#107）：新增 `sticky` 账号轮换策略，持续使用同一账号直到限速或额度耗尽

src/proxy/codex-api.ts

@@ -23,7 +23,7 @@ let _firstModelFetchLogged = false;
 
 export interface CodexResponsesRequest {
   model: string;
-  instructions: string;
+  instructions?: string | null;
   input: CodexInputItem[];
   stream: true;
   store: false;

src/routes/__tests__/responses-optional-instructions.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Tests that /v1/responses works without the `instructions` field.
+ * Regression test for: https://github.com/icebear0828/codex-proxy/issues/71
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { Hono } from "hono";
+
+// ── Mocks (before imports) ──────────────────────────────────────────
+
+const mockConfig = {
+  server: { proxy_api_key: null as string | null },
+  model: {
+    default: "gpt-5.2-codex",
+    default_reasoning_effort: null,
+    default_service_tier: null,
+    suppress_desktop_directives: false,
+  },
+  auth: {
+    jwt_token: undefined as string | undefined,
+    rotation_strategy: "least_used" as const,
+    rate_limit_backoff_seconds: 60,
+  },
+};
+
+vi.mock("../../config.js", () => ({
+  getConfig: vi.fn(() => mockConfig),
+}));
+
+vi.mock("../../paths.js", () => ({
+  getDataDir: vi.fn(() => "/tmp/test-responses"),
+  getConfigDir: vi.fn(() => "/tmp/test-responses-config"),
+}));
+
+vi.mock("fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("fs")>();
+  return {
+    ...actual,
+    readFileSync: vi.fn(() => "models: []"),
+    writeFileSync: vi.fn(),
+    writeFile: vi.fn(
+      (_p: string, _d: string, _e: string, cb: (err: Error | null) => void) =>
+        cb(null),
+    ),
+    existsSync: vi.fn(() => false),
+    mkdirSync: vi.fn(),
+    renameSync: vi.fn(),
+  };
+});
+
+vi.mock("js-yaml", () => ({
+  default: {
+    load: vi.fn(() => ({ models: [], aliases: {} })),
+    dump: vi.fn(() => ""),
+  },
+}));
+
+vi.mock("../../auth/jwt-utils.js", () => ({
+  decodeJwtPayload: vi.fn(() => ({
+    exp: Math.floor(Date.now() / 1000) + 3600,
+  })),
+  extractChatGptAccountId: vi.fn((token: string) => `acct-${token}`),
+  extractUserProfile: vi.fn(() => null),
+  isTokenExpired: vi.fn(() => false),
+}));
+
+vi.mock("../../models/model-fetcher.js", () => ({
+  triggerImmediateRefresh: vi.fn(),
+  startModelRefresh: vi.fn(),
+  stopModelRefresh: vi.fn(),
+}));
+
+vi.mock("../../utils/retry.js", () => ({
+  withRetry: vi.fn(async (fn: () => Promise<unknown>) => fn()),
+}));
+
+// Capture the codexRequest that handleProxyRequest receives
+let capturedCodexRequest: unknown = null;
+
+vi.mock("../shared/proxy-handler.js", () => ({
+  handleProxyRequest: vi.fn(async (c, _pool, _jar, proxyReq) => {
+    capturedCodexRequest = proxyReq.codexRequest;
+    return c.json({ ok: true });
+  }),
+}));
+
+// ── Imports ─────────────────────────────────────────────────────────
+
+import { AccountPool } from "../../auth/account-pool.js";
+import { loadStaticModels } from "../../models/model-store.js";
+import { createResponsesRoutes } from "../responses.js";
+
+// ── Tests ───────────────────────────────────────────────────────────
+
+describe("/v1/responses — optional instructions", () => {
+  let pool: AccountPool;
+  let app: Hono;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    capturedCodexRequest = null;
+    mockConfig.server.proxy_api_key = null;
+    loadStaticModels();
+    pool = new AccountPool();
+    pool.addAccount("test-token-1");
+    app = createResponsesRoutes(pool);
+  });
+
+  afterEach(() => {
+    pool?.destroy();
+  });
+
+  it("accepts request without instructions field", async () => {
+    const res = await app.request("/v1/responses", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "codex",
+        input: [{ role: "user", content: "Hello" }],
+        stream: true,
+      }),
+    });
+
+    expect(res.status).toBe(200);
+  });
+
+  it("accepts request with instructions: null", async () => {
+    const res = await app.request("/v1/responses", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "codex",
+        instructions: null,
+        input: [{ role: "user", content: "Hello" }],
+        stream: true,
+      }),
+    });
+
+    expect(res.status).toBe(200);
+  });
+
+  it("defaults instructions to empty string when omitted", async () => {
+    await app.request("/v1/responses", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "codex",
+        input: [{ role: "user", content: "Hello" }],
+        stream: true,
+      }),
+    });
+
+    expect(capturedCodexRequest).toBeDefined();
+    const req = capturedCodexRequest as Record<string, unknown>;
+    expect(req.instructions).toBe("");
+  });
+
+  it("preserves instructions when provided as string", async () => {
+    await app.request("/v1/responses", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "codex",
+        instructions: "You are a helpful assistant.",
+        input: [{ role: "user", content: "Hello" }],
+        stream: true,
+      }),
+    });
+
+    expect(capturedCodexRequest).toBeDefined();
+    const req = capturedCodexRequest as Record<string, unknown>;
+    expect(req.instructions).toBe("You are a helpful assistant.");
+  });
+
+  it("still rejects non-object body", async () => {
+    const res = await app.request("/v1/responses", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify("not an object"),
+    });
+
+    expect(res.status).toBe(400);
+  });
+});

src/routes/responses.ts

@@ -274,14 +274,14 @@ export function createResponsesRoutes(
       });
     }
 
-    if (!isRecord(body) || typeof body.instructions !== "string") {
+    if (!isRecord(body)) {
       c.status(400);
       return c.json({
         type: "error",
         error: {
           type: "invalid_request_error",
           code: "invalid_request",
-          message: "Missing required field: instructions (string)",
+          message: "Request body must be a JSON object",
         },
       });
     }
@@ -298,7 +298,7 @@ export function createResponsesRoutes(
     // When client sends stream:false, the proxy collects SSE events and returns assembled JSON.
     const codexRequest: CodexResponsesRequest = {
       model: modelId,
-      instructions: body.instructions,
+      instructions: typeof body.instructions === "string" ? body.instructions : "",
       input: Array.isArray(body.input) ? (body.input as CodexInputItem[]) : [],
       stream: true,
       store: false,