Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/inference/inference-options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,11 @@ During interactive NVIDIA Endpoints onboarding, NemoClaw loads NVIDIA's public f
OpenRouter uses the same catalog-backed picker flow with its own OpenRouter featured model catalog, provider route, and credential check.
NVIDIA Endpoints excludes NVIDIA-retired or unsafe choices and corrects known catalog lag before displaying the result.
OpenRouter does not inherit the NVIDIA-only retired-model filter, so a model can appear in OpenRouter onboarding after it leaves NVIDIA Endpoints.
For OpenRouter runtime traffic, NemoClaw starts or reuses a local host adapter on port `11437` by default and registers OpenShell with `OPENAI_BASE_URL=http://host.openshell.internal:11437/v1`.
The adapter receives OpenShell's normal `Authorization: Bearer <OPENROUTER_API_KEY>` header, forwards requests to `https://openrouter.ai/api/v1`, and injects the OpenRouter attribution headers `HTTP-Referer` and `X-OpenRouter-Title`.
The adapter does not store the API key.
It exposes a host health endpoint and writes logs to `~/.nemoclaw/openrouter-runtime-adapter.log`.
Set `NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT` before onboarding to use a different host port.
If the catalog is unavailable, malformed, or contains no safe model IDs, the wizard warns you and uses the bundled fallback list shown below.
Nemotron 3 Super remains the shared default for OpenClaw and Hermes when it is present.
LangChain Deep Agents Code uses Nemotron 3 Ultra as its NVIDIA Endpoints default.
Expand Down Expand Up @@ -272,7 +277,7 @@ OpenRouter credentials are validated as non-empty `sk-or-` keys.
|---|---|
| OpenAI | Tries `/responses` first, then `/chat/completions`. |
| NVIDIA Endpoints | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). |
| OpenRouter | Validates through `/v1/chat/completions` only. NemoClaw skips the `/v1/responses` probe and uses managed Chat Completions for OpenClaw, Hermes, and Deep Agents Code. |
| OpenRouter | Host-side catalog, model, and smoke validation use `/v1/chat/completions` only. NemoClaw skips the `/v1/responses` probe and uses managed Chat Completions for OpenClaw, Hermes, and Deep Agents Code. |
| Google Gemini | Validates through Gemini's OpenAI-compatible chat-completions path only; NemoClaw skips the `/v1/responses` probe because Gemini does not support the Responses API. |
| Other OpenAI-compatible endpoint | Tries `/v1/responses` first with a tool-calling probe; falls back to `/v1/chat/completions`. Selected runtime API defaults to `/v1/chat/completions`; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. |
| Other Anthropic-compatible endpoint | For agents that support Anthropic Messages, including OpenClaw, tries `/v1/messages` with a non-streaming request, then repeats the request with `stream: true` and validates the SSE event sequence. Set `NEMOCLAW_REASONING=true` to skip the streaming check for reasoning-only endpoints. For Hermes and OpenAI-compatible-only agents, validates `/v1/chat/completions`, the surface used by the managed OpenAI frontend. |
Expand Down
4 changes: 3 additions & 1 deletion docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3086,6 +3086,7 @@ Passthrough commands do not consume flags intended for the downstream command as
| `NEMOCLAW_VLLM_PORT` | 8000 | vLLM / NIM inference |
| `NEMOCLAW_OLLAMA_PORT` | 11434 | Ollama inference |
| `NEMOCLAW_OLLAMA_PROXY_PORT` | 11435 | Ollama auth proxy |
| `NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT` | 11437 | Host-side OpenRouter runtime adapter |
<AgentOnly variant="openclaw,hermes">
| `NEMOCLAW_DASHBOARD_BIND` | *unset* (loopback) | Dashboard or API forward bind address. Set to `0.0.0.0` to opt in to remote bind for SSH-deployed hosts. |
</AgentOnly>
Expand All @@ -3094,7 +3095,8 @@ Passthrough commands do not consume flags intended for the downstream command as
</AgentOnly>

If a port value is not a valid integer or falls outside the allowed range, the CLI exits with an error.
`NEMOCLAW_GATEWAY_PORT` also cannot overlap configured service, vLLM, Ollama, or Ollama proxy ports, and cannot use reserved auto-allocation ranges or the default inference/proxy ports `8000`, `11434`, and `11435`.
`NEMOCLAW_GATEWAY_PORT` also cannot overlap configured service, vLLM, Ollama, Ollama proxy, or OpenRouter runtime adapter ports, and cannot use reserved auto-allocation ranges or the default inference/proxy ports `8000`, `11434`, `11435`, and `11437`.
When you select OpenRouter, `NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT` must also be distinct from the gateway, vLLM, Ollama, and Ollama proxy ports.
When you run multiple NemoClaw gateways with different `NEMOCLAW_GATEWAY_PORT` values, NemoClaw derives a separate gateway name, state directory, and compatibility container name from the port so one gateway does not tear down another.
On non-WSL hosts, `NEMOCLAW_OLLAMA_PORT` and `NEMOCLAW_OLLAMA_PROXY_PORT` must be different.
If you run Ollama on port 11435, set `NEMOCLAW_OLLAMA_PROXY_PORT` to another free port before onboarding.
Expand Down
12 changes: 12 additions & 0 deletions src/lib/core/ports.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ const GATEWAY_VALIDATION_OPTIONS = {
ollamaPort: 11434,
ollamaProxyPort: 11435,
bedrockRuntimeAdapterPort: 11436,
openrouterRuntimeAdapterPort: 11437,
};

describe("parsePort", () => {
Expand Down Expand Up @@ -114,6 +115,7 @@ describe("parseGatewayPort", () => {
["11434", "Ollama inference"],
["11435", "Ollama auth proxy"],
["11436", "Bedrock Runtime adapter"],
["11437", "OpenRouter Runtime adapter"],
])("rejects overlap with default port %s", (port, label) => {
process.env[ENV_KEY] = port;
expect(() => parseGatewayPort(ENV_KEY, 8080, GATEWAY_VALIDATION_OPTIONS)).toThrow(label);
Expand All @@ -128,4 +130,14 @@ describe("parseGatewayPort", () => {
}),
).toThrow("NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT");
});

it("rejects overlap with a configured OpenRouter Runtime adapter port", () => {
process.env[ENV_KEY] = "19003";
expect(() =>
parseGatewayPort(ENV_KEY, 8080, {
...GATEWAY_VALIDATION_OPTIONS,
openrouterRuntimeAdapterPort: 19003,
}),
).toThrow("NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT");
});
});
12 changes: 12 additions & 0 deletions src/lib/core/ports.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ export interface GatewayPortValidationOptions {
ollamaPort: number;
ollamaProxyPort: number;
bedrockRuntimeAdapterPort: number;
openrouterRuntimeAdapterPort: number;
}

/**
Expand Down Expand Up @@ -61,6 +62,11 @@ export const BEDROCK_RUNTIME_ADAPTER_PORT = parsePort(
"NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT",
11436,
);
/** OpenRouter header-injection adapter port (default 11437, override via NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT). */
export const OPENROUTER_RUNTIME_ADAPTER_PORT = parsePort(
"NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT",
11437,
);

export function validateGatewayPort(
envVar: string,
Expand All @@ -78,6 +84,7 @@ export function validateGatewayPort(
{ label: "Ollama inference", port: 11434 },
{ label: "Ollama auth proxy", port: 11435 },
{ label: "Bedrock Runtime adapter", port: 11436 },
{ label: "OpenRouter Runtime adapter", port: 11437 },
];
const reservedDefault = reservedDefaults.find((entry) => entry.port === port);
if (reservedDefault) {
Expand All @@ -95,6 +102,10 @@ export function validateGatewayPort(
envVar: "NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT",
port: options.bedrockRuntimeAdapterPort,
},
{
envVar: "NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT",
port: options.openrouterRuntimeAdapterPort,
},
];
const conflict = conflicts.find((entry) => entry.port === port);
if (conflict) {
Expand Down Expand Up @@ -125,4 +136,5 @@ export const GATEWAY_PORT = parseGatewayPort("NEMOCLAW_GATEWAY_PORT", DEFAULT_GA
ollamaPort: OLLAMA_PORT,
ollamaProxyPort: OLLAMA_PROXY_PORT,
bedrockRuntimeAdapterPort: BEDROCK_RUNTIME_ADAPTER_PORT,
openrouterRuntimeAdapterPort: OPENROUTER_RUNTIME_ADAPTER_PORT,
});
90 changes: 90 additions & 0 deletions src/lib/inference/openrouter-runtime-adapter-common.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

import crypto from "node:crypto";
import http from "node:http";
import path from "node:path";

import { compactText } from "../core/url-utils";
import { OPENROUTER_DEFAULT_HEADERS, OPENROUTER_ENDPOINT_URL } from "./openrouter";
import {
DEFAULT_LOCAL_ADAPTER_STATE_DIR,
appendLocalAdapterJsonLine,
type JsonObject,
} from "./local-adapter-lifecycle";

export const STATE_DIR = DEFAULT_LOCAL_ADAPTER_STATE_DIR;
export const PID_PATH = path.join(STATE_DIR, "openrouter-runtime-adapter.pid");
export const STATE_PATH = path.join(STATE_DIR, "openrouter-runtime-adapter.json");
export const LOCK_PATH = path.join(STATE_DIR, "openrouter-runtime-adapter.lock");
export const LOG_PATH = path.join(STATE_DIR, "openrouter-runtime-adapter.log");
export const ADAPTER_NAME = "openrouter-runtime";

export type AdapterLogFields = Record<string, string | number | boolean | null | undefined>;
export type AdapterLogger = (event: string, fields?: AdapterLogFields) => void;

function normalizeLogField(
value: string | number | boolean | null | undefined,
): string | number | boolean | null {
if (value === undefined) return null;
if (typeof value === "string") return compactText(value).slice(0, 180);
return value;
}

export function defaultAdapterLogger(event: string, fields: AdapterLogFields = {}): void {
try {
const payload: Record<string, string | number | boolean | null> = {
ts: new Date().toISOString(),
event: normalizeLogField(event) as string,
};
for (const [key, value] of Object.entries(fields)) {
payload[key] = normalizeLogField(value);
}
appendLocalAdapterJsonLine(LOG_PATH, payload);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
console.error(`OpenRouter Runtime adapter log write failed: ${compactText(message)}`);
}
}

export function logAdapterEvent(
logger: AdapterLogger,
event: string,
fields: AdapterLogFields = {},
): void {
try {
logger(event, fields);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
console.error(`OpenRouter Runtime adapter logger failed: ${compactText(message)}`);
}
}

function stableJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
if (value && typeof value === "object") {
return `{${Object.keys(value as JsonObject)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson((value as JsonObject)[key])}`)
.join(",")}}`;
}
return JSON.stringify(value);
}

export function adapterConfigHash(upstreamBaseUrl = OPENROUTER_ENDPOINT_URL): string {
return crypto
.createHash("sha256")
.update(
stableJson({
adapter: ADAPTER_NAME,
upstreamBaseUrl,
defaultHeaders: OPENROUTER_DEFAULT_HEADERS,
}),
)
.digest("hex");
}

export function sendJson(res: http.ServerResponse, status: number, body: unknown): void {
res.writeHead(status, { "Content-Type": "application/json" });
Comment thread
github-advanced-security[bot] marked this conversation as resolved.
Fixed
res.end(JSON.stringify(body));
Comment thread
github-advanced-security[bot] marked this conversation as resolved.
Fixed
}
11 changes: 11 additions & 0 deletions src/lib/inference/openrouter-runtime-adapter-entry.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

import { startOpenRouterRuntimeAdapterFromEnv } from "./openrouter-runtime-adapter-server";

try {
startOpenRouterRuntimeAdapterFromEnv();
} catch (err) {
console.error(err instanceof Error ? err.message : String(err));
process.exit(1);
}
103 changes: 103 additions & 0 deletions src/lib/inference/openrouter-runtime-adapter-forward.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

import http from "node:http";
import https from "node:https";

import { compactText } from "../core/url-utils";
import { OPENROUTER_DEFAULT_HEADERS } from "./openrouter";
import { sendJson } from "./openrouter-runtime-adapter-common";

const HOP_BY_HOP_HEADERS = new Set([
"connection",
"host",
"keep-alive",
"proxy-authenticate",
"proxy-authorization",
"te",
"trailer",
"transfer-encoding",
"upgrade",
]);

export function hasBearerAuthorization(actual: string | string[] | undefined): boolean {
const header = Array.isArray(actual) ? actual[0] : actual;
return typeof header === "string" && /^Bearer\s+\S+/.test(header);
}

export function buildUpstreamUrl(upstreamBaseUrl: string, reqUrl: string | undefined): URL {
const incoming = new URL(reqUrl || "/", "http://127.0.0.1");
const upstream = new URL(upstreamBaseUrl);
const basePath = upstream.pathname.replace(/\/+$/, "");
const suffix = incoming.pathname.startsWith("/v1")
? incoming.pathname.slice("/v1".length)
: incoming.pathname;
upstream.pathname = `${basePath}${suffix.startsWith("/") ? suffix : `/${suffix}`}`;
upstream.search = incoming.search;
return upstream;
}

export function buildForwardRequestHeaders(req: http.IncomingMessage): http.OutgoingHttpHeaders {
const headers: http.OutgoingHttpHeaders = {};
for (const [name, value] of Object.entries(req.headers)) {
if (value === undefined || HOP_BY_HOP_HEADERS.has(name.toLowerCase())) continue;
headers[name] = value;
}
for (const [name, value] of OPENROUTER_DEFAULT_HEADERS) {
headers[name] = value;
}
return headers;
}

function buildForwardResponseHeaders(source: http.IncomingHttpHeaders): http.OutgoingHttpHeaders {
const headers: http.OutgoingHttpHeaders = {};
for (const [name, value] of Object.entries(source)) {
if (value === undefined || HOP_BY_HOP_HEADERS.has(name.toLowerCase())) continue;
headers[name] = value;
}
return headers;
}

export function forwardOpenRouterRequest(options: {
req: http.IncomingMessage;
res: http.ServerResponse;
upstreamBaseUrl: string;
}): Promise<number> {
const upstreamUrl = buildUpstreamUrl(options.upstreamBaseUrl, options.req.url);
const transport = upstreamUrl.protocol === "http:" ? http : https;
return new Promise((resolve) => {
const upstreamReq = transport.request(
upstreamUrl,
{
method: options.req.method,
headers: buildForwardRequestHeaders(options.req),
},
(upstreamRes) => {
const status = upstreamRes.statusCode || 502;
options.res.writeHead(status, buildForwardResponseHeaders(upstreamRes.headers));
upstreamRes.pipe(options.res);
upstreamRes.on("end", () => resolve(status));
},
);
upstreamReq.on("error", (err) => {
const message = err instanceof Error ? err.message : String(err);
if (!options.res.headersSent) {
sendJson(options.res, 502, {
error: {
message: compactText(message || "OpenRouter request failed."),
type: "openrouter_runtime_error",
code: "openrouter_runtime_error",
},
});
} else {
options.res.destroy(err instanceof Error ? err : undefined);
}
resolve(502);
});
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
options.req.on("error", () => {
upstreamReq.destroy();
resolve(499);
});
options.req.pipe(upstreamReq);
});
}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
Loading
Loading