clawmatrix 0.1.22 → 0.2.0

package/src/model-proxy.ts

@@ -11,7 +11,16 @@ import type {
 import { debug } from "./debug.ts";
 import { readBody } from "./http-utils.ts";
 
-const MODEL_TIMEOUT = 120_000; // 2 minutes
+const DEFAULT_MODEL_TIMEOUT = 120_000; // 2 minutes
+
+/** Normalize usage from OpenAI-compatible APIs (supports both field naming conventions). */
+function parseUsage(usage: Record<string, number> | undefined): { inputTokens: number; outputTokens: number } | undefined {
+  if (!usage) return undefined;
+  return {
+    inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? 0,
+    outputTokens: usage.output_tokens ?? usage.completion_tokens ?? 0,
+  };
+}
 const MAX_STREAM_BUFFER = 1_048_576; // 1MB — guard against upstream not sending newlines
 
 type ResponseFormat = "chat" | "responses";
@@ -53,12 +62,54 @@ export class ModelProxy {
   private httpServer: Server | null = null;
   private gatewayInfo: GatewayInfo;
   private openclawConfig: OpenClawConfig;
+  private readonly modelTimeout: number;
+
+  /** Dynamically discovered proxy models from peer capabilities (auto-discovery). */
+  private discoveredModels: import("./config.ts").ProxyModel[] = [];
+
+  /** Cache of models that need a different API format than configured (detected at runtime).
+   *  Entries expire after 10 minutes so upstream upgrades are eventually detected. */
+  private modelApiCache = new Map<string, { api: string; ts: number }>();
+  private static readonly MODEL_API_CACHE_TTL = 600_000; // 10 minutes
+  private cacheCleanupTimer: ReturnType<typeof setInterval> | null = null;
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo, openclawConfig: OpenClawConfig) {
     this.config = config;
     this.peerManager = peerManager;
     this.gatewayInfo = gatewayInfo;
     this.openclawConfig = openclawConfig;
+    this.modelTimeout = config.modelTimeout ?? DEFAULT_MODEL_TIMEOUT;
+  }
+
+  /** All proxy models: static config + dynamically discovered from peers. */
+  get allProxyModels(): import("./config.ts").ProxyModel[] {
+    if (this.discoveredModels.length === 0) return this.config.proxyModels;
+    return [...this.config.proxyModels, ...this.discoveredModels];
+  }
+
+  /** Rebuild discovered models from current peer capabilities.
+   *  Skips models already present in static config.proxyModels. */
+  updateDiscoveredModels(peers: import("./router.ts").RouteEntry[]) {
+    const staticKeys = new Set(this.config.proxyModels.map((m) => `${m.nodeId}/${m.id}`));
+    const next: import("./config.ts").ProxyModel[] = [];
+    for (const peer of peers) {
+      for (const m of peer.models) {
+        const key = `${peer.nodeId}/${m.id}`;
+        if (staticKeys.has(key)) continue;
+        next.push({
+          id: m.id,
+          nodeId: peer.nodeId,
+          provider: m.provider,
+          description: m.description,
+          input: m.input,
+          compat: m.compat as import("./config.ts").ProxyModel["compat"],
+        });
+      }
+    }
+    this.discoveredModels = next;
+    if (next.length > 0) {
+      debug("proxy", `Auto-discovered ${next.length} model(s) from peers: ${next.map((m) => `${m.nodeId}/${m.id}`).join(", ")}`);
+    }
   }
 
   /**
@@ -212,8 +263,18 @@ export class ModelProxy {
     return items;
   }
 
-  /** Resolve API endpoint for a model: explicit config > OpenClaw provider > gateway fallback */
-  private resolveModelEndpoint(model: { id: string; provider: string; baseUrl?: string; apiKey?: string; api?: string }): { baseUrl: string; apiKey?: string; direct: boolean; api: string } {
+  /**
+   * Resolve API endpoint for a model: explicit config > OpenClaw provider > null.
+   *
+   * ⚠️ 重要：绝对不能 fallback 到 OpenClaw gateway 的 /v1/chat/completions！
+   * OpenClaw gateway 的 /v1/chat/completions 会走 Agent 系统，每次请求都会创建
+   * 一个新的 Agent session（带记忆、system prompt 等）。这会导致：
+   * - 远程节点（如 iPhone）的每次 model_req 都在本地产生一个多余的 OpenClaw 会话
+   * - 模型响应被 OpenClaw Agent 的 system prompt 和记忆污染，结果不正确
+   *
+   * 如果找不到直连 API 端点，必须返回 null 让调用方报错，而不是静默 fallback。
+   */
+  private resolveModelEndpoint(model: { id: string; provider: string; baseUrl?: string; apiKey?: string; api?: string }): { baseUrl: string; apiKey?: string; direct: boolean; api: string } | null {
     const defaultApi = "openai-completions";
 
     // 1. Explicit baseUrl in ClawMatrix model config
@@ -227,9 +288,11 @@ export class ModelProxy {
     }
 
     // 2. Read from OpenClaw's models.providers[provider]
-    const providers = (this.openclawConfig as Record<string, unknown>).models as
-      { providers?: Record<string, { baseUrl?: string; apiKey?: string; api?: string }> } | undefined;
-    const providerConfig = providers?.providers?.[model.provider];
+    const modelsConfig = (this.openclawConfig as Record<string, unknown>).models;
+    const providers = (modelsConfig && typeof modelsConfig === "object")
+      ? (modelsConfig as { providers?: Record<string, { baseUrl?: string; apiKey?: string; api?: string }> }).providers
+      : undefined;
+    const providerConfig = providers?.[model.provider];
     if (providerConfig?.baseUrl) {
       return {
         baseUrl: providerConfig.baseUrl.replace(/\/$/, ""),
@@ -239,18 +302,20 @@ export class ModelProxy {
       };
     }
 
-    // 3. Fallback: OpenClaw gateway
-    const { port } = this.gatewayInfo;
-    return {
-      baseUrl: `http://127.0.0.1:${port}/v1`,
-      apiKey: undefined,
-      direct: false,
-      api: model.api ?? defaultApi,
-    };
+    // 找不到直连端点 → 返回 null（见上方注释，不能 fallback 到 gateway）
+    return null;
   }
 
   /** Start the local HTTP proxy server for OpenAI-compatible requests. */
   start() {
+    // Periodically prune expired model API cache entries
+    this.cacheCleanupTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [id, entry] of this.modelApiCache) {
+        if (now - entry.ts > ModelProxy.MODEL_API_CACHE_TTL) this.modelApiCache.delete(id);
+      }
+    }, ModelProxy.MODEL_API_CACHE_TTL);
+
     this.httpServer = createServer(async (req, res) => {
       try {
         const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
@@ -292,6 +357,10 @@ export class ModelProxy {
   }
 
   stop() {
+    if (this.cacheCleanupTimer) {
+      clearInterval(this.cacheCleanupTimer);
+      this.cacheCleanupTimer = null;
+    }
     if (this.httpServer) {
       this.httpServer.close();
       this.httpServer = null;
@@ -303,8 +372,17 @@ export class ModelProxy {
     this.pending.clear();
     this.streamText.clear();
     this.streamSetupSent.clear();
+    this.modelApiCache.clear();
   }
 
+  /** Clean up all tracking state for a request (pending, streamText, streamSetupSent). */
+  private cleanupRequest(id: string, stableStreamId?: string) {
+    const pending = this.pending.get(id);
+    if (pending) clearTimeout(pending.timer);
+    this.pending.delete(id);
+    this.streamText.delete(id);
+    if (stableStreamId) this.streamSetupSent.delete(stableStreamId);
+  }
 
   private sendResponse(res: import("node:http").ServerResponse, response: ProxyResponse) {
     res.writeHead(response.status, response.headers);
@@ -313,18 +391,34 @@ export class ModelProxy {
     } else {
       // Stream response
       const reader = response.body.getReader();
+      let finished = false;
+
+      // Clean up stream when client disconnects mid-stream
+      res.on("close", () => {
+        if (!finished) {
+          finished = true;
+          reader.cancel().catch(() => {});
+        }
+      });
+
       const pump = (): void => {
         reader.read().then(({ done, value }) => {
-          if (done) {
+          if (done || finished) {
+            finished = true;
             reader.releaseLock();
-            res.end();
+            if (!res.writableEnded) res.end();
             return;
           }
-          res.write(value);
-          pump();
+          const ok = res.write(value);
+          if (ok) {
+            pump();
+          } else {
+            res.once("drain", pump);
+          }
         }).catch(() => {
+          finished = true;
           reader.releaseLock();
-          res.end();
+          if (!res.writableEnded) res.end();
         });
       };
       pump();
@@ -340,16 +434,17 @@ export class ModelProxy {
   } | { error: { status: number; message: string } } {
     const slashIdx = rawModelId.indexOf("/");
     let modelId: string;
-    let matchingModels: (typeof this.config.proxyModels)[number][];
+    const proxyModels = this.allProxyModels;
+    let matchingModels: (typeof proxyModels)[number][];
 
     if (slashIdx > 0) {
       const nodeId = rawModelId.slice(0, slashIdx);
       modelId = rawModelId.slice(slashIdx + 1);
       // Explicit node/model — only target that specific node, no failover to others
-      matchingModels = this.config.proxyModels.filter((m) => m.id === modelId && m.nodeId === nodeId);
+      matchingModels = proxyModels.filter((m) => m.id === modelId && m.nodeId === nodeId);
     } else {
       modelId = rawModelId;
-      matchingModels = this.config.proxyModels.filter((m) => m.id === modelId);
+      matchingModels = proxyModels.filter((m) => m.id === modelId);
     }
 
     if (matchingModels.length === 0) {
@@ -368,6 +463,16 @@ export class ModelProxy {
       }
     }
 
+    // Sort candidates by latency (lowest first) for optimal first-try and failover order
+    candidates.sort((a, b) => {
+      const routeA = this.peerManager.router.getRoute(a.routeNodeId);
+      const routeB = this.peerManager.router.getRoute(b.routeNodeId);
+      const aDirect = routeA?.connection ? 0 : 1;
+      const bDirect = routeB?.connection ? 0 : 1;
+      if (aDirect !== bDirect) return aDirect - bDirect;
+      return (routeA?.latencyMs ?? 0) - (routeB?.latencyMs ?? 0);
+    });
+
     debug("proxy", `model raw="${rawModelId}" modelId="${modelId}" candidates=${candidates.map((c) => c.routeNodeId).join(",") || "none"}`);
     if (candidates.length === 0) {
       return { error: { status: 502, message: `No reachable node for model "${rawModelId}"` } };
@@ -377,7 +482,7 @@ export class ModelProxy {
   }
 
   private async handleChatCompletion(rawBody: string, _api: string): Promise<ProxyResponse> {
-    let body: { model: string; messages: unknown[]; stream?: boolean; temperature?: number; max_tokens?: number };
+    let body: { model: string; messages: unknown[]; stream?: boolean; temperature?: number; max_tokens?: number; tools?: unknown[]; tool_choice?: unknown };
     try {
       body = JSON.parse(rawBody);
     } catch {
@@ -410,7 +515,7 @@ export class ModelProxy {
       }
       return {
         type: "model_req", id, from: this.config.nodeId, to: candidate.routeNodeId, timestamp: Date.now(),
-        payload: { model: modelId, provider: candidate.proxyModel?.provider, api: candidate.proxyModel?.api, messages, temperature: body.temperature, maxTokens: body.max_tokens, stream },
+        payload: { model: modelId, provider: candidate.proxyModel?.provider, api: candidate.proxyModel?.api, messages, tools: body.tools, toolChoice: body.tool_choice, temperature: body.temperature, maxTokens: body.max_tokens, stream },
       };
     };
     const frame = buildFrame(first, requestId);
@@ -423,7 +528,7 @@ export class ModelProxy {
   }
 
   private async handleResponses(rawBody: string): Promise<ProxyResponse> {
-    let body: { model: string; input: unknown; stream?: boolean; temperature?: number; max_output_tokens?: number; instructions?: string };
+    let body: { model: string; input: unknown; stream?: boolean; temperature?: number; max_output_tokens?: number; instructions?: string; tools?: unknown[]; tool_choice?: unknown };
     try {
       body = JSON.parse(rawBody);
     } catch {
@@ -467,7 +572,7 @@ export class ModelProxy {
       }
       return {
         type: "model_req", id, from: this.config.nodeId, to: candidate.routeNodeId, timestamp: Date.now(),
-        payload: { model: modelId, provider: candidate.proxyModel?.provider, api: candidate.proxyModel?.api, messages: inputItems, inputFormat: "responses", temperature: body.temperature, maxTokens: body.max_output_tokens, stream },
+        payload: { model: modelId, provider: candidate.proxyModel?.provider, api: candidate.proxyModel?.api, messages: inputItems, inputFormat: "responses", tools: body.tools, toolChoice: body.tool_choice, temperature: body.temperature, maxTokens: body.max_output_tokens, stream },
       };
     };
     const frame = buildFrame(first, requestId);
@@ -490,10 +595,21 @@ export class ModelProxy {
     const encoder = new TextEncoder();
     const model = frame.payload.model;
 
+    let streamController: ReadableStreamDefaultController;
     const readable = new ReadableStream({
       start: (controller) => {
+        streamController = controller;
         this.startStreamAttempt(requestId, targetNodeId, frame, responseFormat, controller, encoder, model, failoverCandidates, buildFrame);
       },
+      cancel: () => {
+        // Client disconnected — find and clean up the pending request using this controller
+        for (const [id, p] of this.pending) {
+          if (p.controller === streamController) {
+            this.cleanupRequest(id, p.stableStreamId);
+            break;
+          }
+        }
+      },
     });
 
     // Emit setup events for responses API (once, before any attempts)
@@ -524,11 +640,10 @@ export class ModelProxy {
     const stableId = streamId ?? requestId;
 
     const timer = setTimeout(() => {
-      this.pending.delete(requestId);
-      this.streamText.delete(requestId);
+      this.cleanupRequest(requestId);
       this.peerManager.router.markFailed(requestId);
       this.tryStreamFailover(stableId, responseFormat, controller, encoder, model, failoverCandidates, buildFrame, `model request to "${targetNodeId}" timed out`);
-    }, MODEL_TIMEOUT);
+    }, this.modelTimeout);
 
     this.pending.set(requestId, {
       resolve: () => {}, reject: () => {},
@@ -542,14 +657,14 @@ export class ModelProxy {
 
     // Emit setup events for responses API (only once per stream, keyed by stableId)
     if (responseFormat === "responses" && !this.streamSetupSent.has(stableId)) {
-      this.enqueueResponsesStreamSetup(controller, encoder, stableId, model);
+      const hasTools = Array.isArray(frame.payload.tools) && frame.payload.tools.length > 0;
+      this.enqueueResponsesStreamSetup(controller, encoder, stableId, model, hasTools);
       this.streamSetupSent.add(stableId);
     }
 
     const sent = this.peerManager.sendTo(targetNodeId, frame);
     if (!sent) {
-      this.pending.delete(requestId);
-      clearTimeout(timer);
+      this.cleanupRequest(requestId);
       this.tryStreamFailover(stableId, responseFormat, controller, encoder, model, failoverCandidates, buildFrame, `cannot reach node "${targetNodeId}"`);
     }
   }
@@ -593,18 +708,23 @@ export class ModelProxy {
   }
 
   /** Emit responses API stream setup events (response.created → content_part.added). */
-  private enqueueResponsesStreamSetup(controller: ReadableStreamDefaultController, encoder: TextEncoder, id: string, model: string) {
+  private enqueueResponsesStreamSetup(controller: ReadableStreamDefaultController, encoder: TextEncoder, id: string, model: string, hasTools = false) {
     const respId = `resp_${id}`;
-    const msgId = `msg_${id}`;
     const now = Math.floor(Date.now() / 1000);
     const baseResp = { id: respId, object: "response", created_at: now, status: "in_progress", model, output: [] };
-    const msgItem = { type: "message", id: msgId, role: "assistant", content: [], status: "in_progress" };
-    const textPart = { type: "output_text", text: "" };
 
     controller.enqueue(encoder.encode(`event: response.created\ndata: ${JSON.stringify({ type: "response.created", response: baseResp })}\n\n`));
     controller.enqueue(encoder.encode(`event: response.in_progress\ndata: ${JSON.stringify({ type: "response.in_progress", response: baseResp })}\n\n`));
-    controller.enqueue(encoder.encode(`event: response.output_item.added\ndata: ${JSON.stringify({ type: "response.output_item.added", output_index: 0, item: msgItem })}\n\n`));
-    controller.enqueue(encoder.encode(`event: response.content_part.added\ndata: ${JSON.stringify({ type: "response.content_part.added", item_id: msgId, output_index: 0, content_index: 0, part: textPart })}\n\n`));
+
+    // When tools are present, skip pre-fabricated output_item/content_part events —
+    // the real events (including function_call items) will be forwarded from the remote.
+    if (!hasTools) {
+      const msgId = `msg_${id}`;
+      const msgItem = { type: "message", id: msgId, role: "assistant", content: [], status: "in_progress" };
+      const textPart = { type: "output_text", text: "" };
+      controller.enqueue(encoder.encode(`event: response.output_item.added\ndata: ${JSON.stringify({ type: "response.output_item.added", output_index: 0, item: msgItem })}\n\n`));
+      controller.enqueue(encoder.encode(`event: response.content_part.added\ndata: ${JSON.stringify({ type: "response.content_part.added", item_id: msgId, output_index: 0, content_index: 0, part: textPart })}\n\n`));
+    }
   }
 
   /** Emit responses API stream completion events (output_text.done → response.completed). */
@@ -697,7 +817,7 @@ export class ModelProxy {
         this.pending.delete(requestId);
         this.peerManager.router.markFailed(requestId);
         reject(new Error(`Model request to "${targetNodeId}" timed out`));
-      }, MODEL_TIMEOUT);
+      }, this.modelTimeout);
 
       this.pending.set(requestId, {
         resolve: resolve as (v: unknown) => void,
@@ -781,7 +901,7 @@ export class ModelProxy {
         .map((p) => p.nodeId),
     );
 
-    const models = this.config.proxyModels.map((m) => {
+    const models = this.allProxyModels.map((m) => {
       const entry: Record<string, unknown> = {
         id: m.id,
         object: "model",
@@ -820,18 +940,17 @@ export class ModelProxy {
     // process the request and sent model_res instead of model_stream).
     if (pending.stream) {
       if (!frame.payload.success && pending.controller && pending.encoder) {
-        clearTimeout(pending.timer);
-        this.pending.delete(frame.id);
-        this.streamText.delete(frame.id);
+        const stableId = pending.stableStreamId ?? frame.id;
         // Try failover if no content has been sent yet
         if (!pending.hasContent && pending.failoverCandidates?.length && pending.buildFrame) {
+          this.cleanupRequest(frame.id);
           this.tryStreamFailover(
-            pending.stableStreamId ?? frame.id, pending.responseFormat, pending.controller, pending.encoder,
+            stableId, pending.responseFormat, pending.controller, pending.encoder,
             pending.model ?? "", pending.failoverCandidates, pending.buildFrame,
             `remote error: ${frame.payload.error}`,
           );
         } else {
-          const stableId = pending.stableStreamId ?? frame.id;
+          this.cleanupRequest(frame.id, stableId);
           try {
             const errMsg = `[ClawMatrix] Remote error: ${frame.payload.error}`;
             if (pending.responseFormat === "responses") {
@@ -843,14 +962,12 @@ export class ModelProxy {
             }
             pending.controller.close();
           } catch { /* controller may already be closed */ }
-          this.streamSetupSent.delete(stableId);
         }
       }
       return;
     }
 
-    clearTimeout(pending.timer);
-    this.pending.delete(frame.id);
+    this.cleanupRequest(frame.id);
     pending.resolve(frame.payload);
   }
 
@@ -870,9 +987,8 @@ export class ModelProxy {
         this.handleModelStreamChat(frame, pending);
       }
     } catch {
-      clearTimeout(pending.timer);
-      this.pending.delete(frame.id);
-      this.streamText.delete(frame.id);
+      this.cleanupRequest(frame.id, pending.stableStreamId);
+      try { pending.controller?.close(); } catch { /* already closed */ }
     }
   }
 
@@ -889,12 +1005,13 @@ export class ModelProxy {
       pending.controller!.enqueue(pending.encoder!.encode(`data: ${JSON.stringify(finalChunk)}\n\n`));
       pending.controller!.enqueue(pending.encoder!.encode("data: [DONE]\n\n"));
       pending.controller!.close();
-      clearTimeout(pending.timer);
-      this.pending.delete(frame.id);
-      this.streamSetupSent.delete(stableId);
+      this.cleanupRequest(frame.id, stableId);
     } else {
       // Use full deltaObj when available (carries tool_calls etc.), otherwise simple text delta
-      const delta = frame.payload.deltaObj ?? { content: frame.payload.delta };
+      const delta = frame.payload.deltaObj ?? {
+        content: frame.payload.delta,
+        ...(frame.payload.reasoningDelta && { reasoning_content: frame.payload.reasoningDelta }),
+      };
       const chunkStableId = pending.stableStreamId ?? frame.id;
       const chunk = { id: `chatcmpl-${chunkStableId}`, object: "chat.completion.chunk", choices: [{ index: 0, delta, finish_reason: null }] };
       pending.controller!.enqueue(pending.encoder!.encode(`data: ${JSON.stringify(chunk)}\n\n`));
@@ -907,13 +1024,27 @@ export class ModelProxy {
       const stableId = pending.stableStreamId ?? frame.id;
       const fullText = this.streamText.get(frame.id) ?? "";
       this.streamText.delete(frame.id);
-      this.enqueueResponsesStreamDone(pending.controller!, pending.encoder!, stableId, pending.model ?? "", fullText, frame.payload.usage);
+
+      // If the remote forwarded the full response.completed event, emit it directly
+      const doneObj = frame.payload.deltaObj as { event?: string; data?: unknown } | undefined;
+      if (doneObj?.event === "response.completed" && doneObj.data) {
+        pending.controller!.enqueue(pending.encoder!.encode(`event: response.completed\ndata: ${JSON.stringify(doneObj.data)}\n\n`));
+      } else {
+        // Fallback: reconstruct text-only completion
+        this.enqueueResponsesStreamDone(pending.controller!, pending.encoder!, stableId, pending.model ?? "", fullText, frame.payload.usage);
+      }
       pending.controller!.close();
-      clearTimeout(pending.timer);
-      this.pending.delete(frame.id);
-      this.streamSetupSent.delete(stableId);
+      this.cleanupRequest(frame.id, stableId);
     } else {
-      // Accumulate text for done event
+      // Forward structured Responses API events (function_call, output_item, etc.)
+      const obj = frame.payload.deltaObj as { event?: string; data?: unknown } | undefined;
+      if (obj?.event && obj.data) {
+        pending.controller!.enqueue(pending.encoder!.encode(`event: ${obj.event}\ndata: ${JSON.stringify(obj.data)}\n\n`));
+        pending.hasContent = true;
+        return;
+      }
+
+      // Text delta
       this.streamText.set(frame.id, (this.streamText.get(frame.id) ?? "") + (frame.payload.delta ?? ""));
       const respStableId = pending.stableStreamId ?? frame.id;
       const evt = { type: "response.output_text.delta", item_id: `msg_${respStableId}`, output_index: 0, content_index: 0, delta: frame.payload.delta };
@@ -922,25 +1053,30 @@ export class ModelProxy {
     }
   }
 
-  private sendStreamDelta(to: string, id: string, delta: string, deltaObj?: unknown) {
+  private sendStreamDelta(to: string, id: string, delta: string, deltaObj?: unknown, reasoningDelta?: string) {
     this.peerManager.sendTo(to, {
       type: "model_stream",
       id,
       from: this.config.nodeId,
       to,
       timestamp: Date.now(),
-      payload: { delta, ...(deltaObj !== undefined && { deltaObj }), done: false },
+      payload: {
+        delta,
+        ...(reasoningDelta && { reasoningDelta }),
+        ...(deltaObj !== undefined && { deltaObj }),
+        done: false,
+      },
     } satisfies ModelStreamChunk);
   }
 
-  private sendStreamDone(to: string, id: string, usage?: { inputTokens: number; outputTokens: number }) {
+  private sendStreamDone(to: string, id: string, usage?: { inputTokens: number; outputTokens: number }, deltaObj?: unknown) {
     this.peerManager.sendTo(to, {
       type: "model_stream",
       id,
       from: this.config.nodeId,
       to,
       timestamp: Date.now(),
-      payload: { delta: "", done: true, usage },
+      payload: { delta: "", done: true, usage, ...(deltaObj !== undefined && { deltaObj }) },
     } satisfies ModelStreamChunk);
   }
 
@@ -967,21 +1103,27 @@ export class ModelProxy {
 
     try {
       const endpoint = this.resolveModelEndpoint(model);
-      const isResponsesApi = endpoint.api === "openai-responses" || endpoint.api === "openai-codex-responses";
+      if (!endpoint) {
+        this.peerManager.sendTo(from, {
+          type: "model_res", id, from: this.config.nodeId, to: from, timestamp: Date.now(),
+          payload: { success: false, error: `No direct API endpoint configured for model "${payload.model}" (provider: ${model.provider}). Configure baseUrl/apiKey in ClawMatrix model config or OpenClaw provider config.` },
+        } satisfies ModelResponse);
+        return;
+      }
+      // Use payload.api override from requesting side, or cached API from previous auto-detection
+      const cached = this.modelApiCache.get(model.id);
+      const cachedApi = (cached && Date.now() - cached.ts < ModelProxy.MODEL_API_CACHE_TTL) ? cached.api : undefined;
+      if (cached && !cachedApi) this.modelApiCache.delete(model.id); // expired
+      const effectiveApi = payload.api ?? cachedApi ?? endpoint.api;
+      const isResponsesApi = effectiveApi === "openai-responses" || effectiveApi === "openai-codex-responses";
       const path = isResponsesApi ? "/responses" : "/chat/completions";
       const url = `${endpoint.baseUrl}${path}`;
       const headers: Record<string, string> = { "Content-Type": "application/json" };
 
-      if (endpoint.direct) {
-        if (endpoint.apiKey) headers["Authorization"] = `Bearer ${endpoint.apiKey}`;
-        debug("model_req", `direct API call to ${url} (api=${endpoint.api})`);
-      } else {
-        const { authHeader } = this.gatewayInfo;
-        if (authHeader) headers["Authorization"] = authHeader;
-        debug("model_req", `gateway fallback to ${url}`);
-      }
+      if (endpoint.apiKey) headers["Authorization"] = `Bearer ${endpoint.apiKey}`;
+      debug("model_req", `direct API call to ${url} (api=${endpoint.api})`);
 
-      const modelField = endpoint.direct ? model.id : `${model.provider}/${model.id}`;
+      const modelField = model.id;
       const srcFormat = payload.inputFormat ?? "chat";
 
       // Convert messages between formats if source and target API differ
@@ -996,6 +1138,8 @@ export class ModelProxy {
           stream: payload.stream,
           temperature: payload.temperature,
           max_output_tokens: payload.maxTokens,
+          ...(payload.tools && { tools: payload.tools }),
+          ...(payload.toolChoice !== undefined && { tool_choice: payload.toolChoice }),
         };
       } else {
         const messages = srcFormat === "chat"
@@ -1008,6 +1152,8 @@ export class ModelProxy {
           max_tokens: payload.maxTokens,
           stream: payload.stream,
           ...(payload.stream ? { stream_options: { include_usage: true } } : {}),
+          ...(payload.tools && { tools: payload.tools }),
+          ...(payload.toolChoice !== undefined && { tool_choice: payload.toolChoice }),
         };
       }
 
@@ -1031,6 +1177,8 @@ export class ModelProxy {
           let buffer = "";
           let lastUsage: { inputTokens: number; outputTokens: number } | undefined;
           let streamDone = false;
+          let contentSent = false;
+          let completedEvent: unknown = undefined;
 
           while (!streamDone) {
             const { done, value } = await reader.read();
@@ -1053,7 +1201,6 @@ export class ModelProxy {
               if (!line.startsWith("data: ")) continue;
               const data = line.slice(6).trim();
               if (data === "[DONE]") {
-                this.sendStreamDone(from, id, lastUsage);
                 streamDone = true;
                 break;
               }
@@ -1067,33 +1214,38 @@ export class ModelProxy {
                     const delta = parsed.delta || "";
                     if (delta) {
                       this.sendStreamDelta(from, id, delta);
+                      contentSent = true;
                     }
+                  } else if (
+                    evtType === "response.output_item.added" ||
+                    evtType === "response.output_item.done" ||
+                    evtType === "response.content_part.added" ||
+                    evtType === "response.content_part.done" ||
+                    evtType === "response.output_text.done" ||
+                    evtType === "response.function_call_arguments.delta" ||
+                    evtType === "response.function_call_arguments.done"
+                  ) {
+                    // Forward structured Responses API events via deltaObj
+                    this.sendStreamDelta(from, id, "", { event: evtType, data: parsed });
+                    contentSent = true;
                   } else if (evtType === "response.completed") {
                     const usage = parsed.response?.usage;
-                    if (usage) {
-                      lastUsage = {
-                        inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? 0,
-                        outputTokens: usage.output_tokens ?? usage.completion_tokens ?? 0,
-                      };
-                    }
-                    this.sendStreamDone(from, id, lastUsage);
+                    lastUsage = parseUsage(usage) ?? lastUsage;
+                    completedEvent = { event: evtType, data: parsed };
                     streamDone = true;
                     break;
                   }
                 } else {
                   // Chat completions format
-                  if (parsed.usage) {
-                    lastUsage = {
-                      inputTokens: parsed.usage.prompt_tokens,
-                      outputTokens: parsed.usage.completion_tokens,
-                    };
-                  }
+                  lastUsage = parseUsage(parsed.usage) ?? lastUsage;
                   const d = parsed.choices?.[0]?.delta;
-                  const delta = d?.content || d?.reasoning_content || "";
+                  const delta = d?.content || "";
+                  const reasoningDelta = d?.reasoning_content || "";
                   // Pass full delta object when it contains tool_calls or other structured data
                   const hasStructured = d?.tool_calls || d?.refusal != null;
-                  if (delta || hasStructured) {
-                    this.sendStreamDelta(from, id, delta, hasStructured ? d : undefined);
+                  if (delta || reasoningDelta || hasStructured) {
+                    this.sendStreamDelta(from, id, delta, hasStructured ? d : undefined, reasoningDelta || undefined);
+                    contentSent = true;
                   }
                 }
               } catch {
@@ -1102,9 +1254,30 @@ export class ModelProxy {
               currentEvent = "";
             }
           }
-          // If the upstream closed without sending [DONE] or response.completed,
-          // send a completion frame so the requesting side doesn't hang.
-          if (!streamDone) {
+
+          // Responses API stream produced no content — fall back to chat completions
+          if (isResponsesApi && !contentSent && !cachedApi) {
+            debug("model_req", `responses API stream produced no content for "${model.id}", retrying with chat completions`);
+            const chatResult = await this.retryWithChatCompletions(endpoint, modelField, payload, headers);
+            if (chatResult) {
+              this.modelApiCache.set(model.id, { api: "openai-completions", ts: Date.now() });
+              debug("model_req", `cached "${model.id}" as openai-completions (stream fallback)`);
+              if (chatResult.content) {
+                this.sendStreamDelta(from, id, chatResult.content);
+              }
+              this.sendStreamDone(from, id, chatResult.usage);
+            } else if (completedEvent) {
+              this.sendStreamDone(from, id, lastUsage, completedEvent);
+            } else {
+              this.sendStreamDone(from, id, lastUsage);
+            }
+          } else if (completedEvent) {
+            this.sendStreamDone(from, id, lastUsage, completedEvent);
+          } else if (!streamDone) {
+            // Upstream closed without sending [DONE] or response.completed
+            this.sendStreamDone(from, id, lastUsage);
+          } else {
+            // Chat completions [DONE] received
             this.sendStreamDone(from, id, lastUsage);
           }
         } finally {
@@ -1112,12 +1285,33 @@ export class ModelProxy {
         }
       } else {
         // Non-streaming response
-        const result = await response.json();
+        const responseText = await response.text();
+        let result: Record<string, unknown>;
+        let chatFallbackResult: Awaited<ReturnType<ModelProxy["retryWithChatCompletions"]>> = null;
+        try {
+          result = JSON.parse(responseText);
+        } catch {
+          // Upstream returned non-JSON (e.g. SSE in non-stream mode) — try chat completions fallback
+          if (!cachedApi && isResponsesApi) {
+            debug("model_req", `responses API returned non-JSON for "${model.id}", retrying with chat completions`);
+            chatFallbackResult = await this.retryWithChatCompletions(endpoint, modelField, payload, headers);
+            if (chatFallbackResult) {
+              this.modelApiCache.set(model.id, { api: "openai-completions", ts: Date.now() });
+              debug("model_req", `cached "${model.id}" as openai-completions (non-JSON fallback)`);
+            }
+          }
+          if (!chatFallbackResult) throw new Error(`Upstream returned non-JSON: ${responseText.slice(0, 100)}`);
+          result = {}; // unused — chatFallbackResult takes precedence
+        }
         let content: string;
+        let reasoning = "";
         let message: unknown | undefined;
         let usage: { inputTokens: number; outputTokens: number } | undefined;
 
-        if (isResponsesApi) {
+        if (chatFallbackResult) {
+          ({ content, message, usage } = chatFallbackResult);
+          reasoning = chatFallbackResult.reasoning ?? "";
+        } else if (isResponsesApi) {
           // Responses API: extract text from output[].content[].text
           content = "";
           const output = result.output as { type?: string; content?: { type?: string; text?: string }[] }[] | undefined;
@@ -1130,28 +1324,40 @@ export class ModelProxy {
               }
             }
           }
-          // Carry full output array for structured data (function_call items, etc.)
-          message = result.output;
-          if (result.usage) {
-            usage = {
-              inputTokens: result.usage.input_tokens ?? result.usage.prompt_tokens ?? 0,
-              outputTokens: result.usage.output_tokens ?? result.usage.completion_tokens ?? 0,
-            };
+
+          // Auto-detect: if Responses API returned empty output but produced tokens,
+          // the upstream adapter likely doesn't support Responses API properly.
+          // Retry with chat completions and cache the result.
+          const parsedUsage = parseUsage(result.usage as Record<string, number> | undefined);
+          const hasMessage = Array.isArray(output) && output.some((o: { type?: string }) => o.type === "message");
+          if (!hasMessage && (parsedUsage?.outputTokens ?? 0) > 0 && !cachedApi) {
+            debug("model_req", `responses API returned empty output for "${model.id}" (output_tokens=${parsedUsage!.outputTokens}), retrying with chat completions`);
+            const chatResult = await this.retryWithChatCompletions(endpoint, modelField, payload, headers);
+            if (chatResult) {
+              this.modelApiCache.set(model.id, { api: "openai-completions", ts: Date.now() });
+              debug("model_req", `cached "${model.id}" as openai-completions`);
+              ({ content, message, usage } = chatResult);
+            } else {
+              message = result.output;
+              usage = parsedUsage;
+            }
+          } else {
+            // Carry full output array for structured data (function_call items, etc.)
+            message = result.output;
+            usage = parsedUsage;
           }
         } else {
           // Chat completions format
           const msg = result.choices?.[0]?.message;
-          content = msg?.content || msg?.reasoning_content || "";
+          content = msg?.content || "";
+          reasoning = msg?.reasoning_content || "";
           // Carry full message object when it has tool_calls or other structured data
           if (msg?.tool_calls || msg?.refusal != null || msg?.function_call) {
             message = msg;
           }
-          if (result.usage) {
-            usage = {
-              inputTokens: result.usage.prompt_tokens,
-              outputTokens: result.usage.completion_tokens,
-            };
-          }
+          usage = parseUsage(result.usage);
+          // If no content but has reasoning, use reasoning as content fallback
+          if (!content && reasoning) content = reasoning;
         }
 
         this.peerManager.sendTo(from, {
@@ -1163,6 +1369,7 @@ export class ModelProxy {
           payload: {
             success: true,
             content,
+            ...(reasoning && { reasoning }),
             ...(message !== undefined && { message }),
             usage,
           },
@@ -1182,4 +1389,45 @@ export class ModelProxy {
       } satisfies ModelResponse);
     }
   }
+
+  /** Retry a model request using chat completions format (fallback from Responses API). */
+  private async retryWithChatCompletions(
+    endpoint: { baseUrl: string; apiKey?: string; direct: boolean; api: string },
+    modelField: string,
+    payload: ModelRequest["payload"],
+    headers: Record<string, string>,
+  ): Promise<{ content: string; reasoning?: string; message?: unknown; usage?: { inputTokens: number; outputTokens: number } } | null> {
+    try {
+      const srcFormat = payload.inputFormat ?? "chat";
+      const messages = srcFormat === "chat"
+        ? payload.messages
+        : ModelProxy.normalizeResponsesInput(payload.messages);
+      const chatBody: Record<string, unknown> = {
+        model: modelField,
+        messages,
+        temperature: payload.temperature,
+        max_tokens: payload.maxTokens,
+        stream: false,
+        ...(payload.tools && { tools: payload.tools }),
+        ...(payload.toolChoice !== undefined && { tool_choice: payload.toolChoice }),
+      };
+      const chatUrl = `${endpoint.baseUrl}/chat/completions`;
+      const chatResp = await fetch(chatUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(chatBody),
+      });
+      if (!chatResp.ok) return null;
+      const chatResult = await chatResp.json();
+      const msg = chatResult.choices?.[0]?.message;
+      const content = msg?.content || "";
+      const reasoningContent = msg?.reasoning_content || "";
+      const message = (msg?.tool_calls || msg?.refusal != null || msg?.function_call) ? msg : undefined;
+      const usage = parseUsage(chatResult.usage);
+      return { content: content || reasoningContent, reasoning: reasoningContent || undefined, message, usage };
+    } catch (err) {
+      debug("model_req", `retryWithChatCompletions failed for "${modelField}": ${err instanceof Error ? err.message : String(err)}`);
+      return null;
+    }
+  }
 }