openclaw-nexos-provider 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openclaw-nexos-provider contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# openclaw-nexos-provider
+
+An [OpenClaw](https://openclaw.ai) provider plugin for [Nexos AI](https://nexos.ai) —
+a unified AI gateway that exposes Claude, GPT, Gemini, Grok, and 60+ other models
+through a single API endpoint and one API key.
+
+The plugin registers two providers backed by the same `NEXOS_API_KEY`:
+
+| Provider          | Transport                       | Used for                                              |
+| ----------------- | ------------------------------- | ----------------------------------------------------- |
+| `nexos`           | `openai-completions` (`/v1/chat/completions`) | Every model that does not advertise the Anthropic `messages` endpoint |
+| `nexos-anthropic` | `anthropic-messages` (`/v1/messages`)         | Claude models that advertise `messages` (native tool_use, caching)    |
+
+Models are **discovered dynamically** from the Nexos `/v1/models` API at runtime,
+so the catalog always reflects what your account can access — there is no
+hard-coded model list to keep in sync.
+
+## Install
+
+```bash
+openclaw plugins install clawhub:openclaw-nexos-provider
+# or from npm during the launch cutover:
+openclaw plugins install openclaw-nexos-provider
+```
+
+## Configure
+
+Set your Nexos API key (either works):
+
+```bash
+export NEXOS_API_KEY="your-nexos-key"
+# or, interactively:
+openclaw onboard --nexos-api-key "your-nexos-key"
+```
+
+Then pick a model:
+
+```bash
+openclaw models list --provider nexos
+openclaw models list --provider nexos-anthropic
+openclaw agent --model "nexos/<model-id>" --message "hello"
+```
+
+Model definitions (context window, max output tokens, transport) are supplied by
+the plugin; OpenClaw's catalog machinery marks the models available and shows
+them in the model picker like any first-class provider.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck   # requires the openclaw peer dependency
+npm run test        # pure catalog/discovery unit tests (no OpenClaw runtime)
+npm run build       # bundles src/index.ts -> dist/index.js (openclaw externalized)
+```
+
+- `src/nexos-models.ts` — pure, dependency-free catalog logic (fetch, project,
+  split by endpoint, build provider config). Fully unit-tested.
+- `src/index.ts` — the plugin entry: registers the two providers and their model
+  catalogs against the OpenClaw Plugin SDK.
+
+## Status
+
+Community/open-source plugin. Built to follow the OpenClaw maintainers' guidance
+that optional gateway/provider integrations ship as ClawHub/npm plugins rather
+than in core (see openclaw/openclaw#44963). Intended to be transferable to Nexos
+AI for long-term maintenance.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,218 @@
+// src/index.ts
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth";
+
+// src/nexos-models.ts
+var NEXOS_BASE_URL = "https://api.nexos.ai/v1";
+var NEXOS_PROVIDER_COMPLETIONS = "nexos";
+var NEXOS_PROVIDER_ANTHROPIC = "nexos-anthropic";
+var DEFAULT_MAX_TOKENS = 8192;
+var DEFAULT_CONTEXT_WINDOW = 2e5;
+var MODEL_REGEX_PRIORITIES = {
+  "\\bgpt[\\s-_]5(.\\d+)?": 100
+};
+var MODEL_PREFIX_PRIORITIES = {
+  gpt: 200,
+  gemini: 300,
+  claude: 400,
+  "anthropic.claude": 400,
+  grok: 600
+};
+function beautifyName(name) {
+  return name.replace(/-/g, " ").replace(/\./g, " ").replace(/@/g, " @ ").replace(/\b\w/g, (l) => l.toUpperCase());
+}
+function prioritizeModel(name) {
+  for (const [pattern, priority] of Object.entries(MODEL_REGEX_PRIORITIES)) {
+    if (new RegExp(pattern, "i").test(name)) {
+      return priority;
+    }
+  }
+  const prefix = (name.replace(" ", "-").split("-")[0] ?? "").toLowerCase();
+  return MODEL_PREFIX_PRIORITIES[prefix] ?? 200;
+}
+function buildNexosCatalog(apiData) {
+  const data = apiData?.data;
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  const models = [];
+  for (const model of data) {
+    const nexosModelId = model.nexos_model_id;
+    const rawName = model.name;
+    if (!nexosModelId || !rawName) {
+      continue;
+    }
+    const alias = `Nexos ${beautifyName(rawName)}`;
+    const endpoints = Array.isArray(model.endpoints) ? model.endpoints : ["chat_completions"];
+    models.push({
+      alias,
+      nexosModelId,
+      priority: prioritizeModel(rawName),
+      endpoints,
+      definition: {
+        id: nexosModelId,
+        name: alias,
+        reasoning: true,
+        input: ["text", "image"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        maxTokens: DEFAULT_MAX_TOKENS,
+        contextWindow: DEFAULT_CONTEXT_WINDOW,
+        compat: {
+          supportsStore: true,
+          supportsDeveloperRole: true,
+          supportsReasoningEffort: false
+        }
+      }
+    });
+  }
+  models.sort((a, b) => a.priority - b.priority);
+  return models;
+}
+function splitByEndpoint(models) {
+  const completions = [];
+  const anthropic = [];
+  for (const model of models) {
+    if (model.endpoints.includes("messages")) {
+      anthropic.push(model);
+    } else {
+      completions.push(model);
+    }
+  }
+  return { completions, anthropic };
+}
+function buildProviderConfig(params) {
+  const models = params.models.map((model) => model.definition);
+  if (params.kind === "anthropic") {
+    return {
+      baseUrl: NEXOS_BASE_URL,
+      apiKey: params.apiKey,
+      api: "anthropic-messages",
+      auth: "token",
+      authHeader: true,
+      models
+    };
+  }
+  return {
+    baseUrl: NEXOS_BASE_URL,
+    apiKey: params.apiKey,
+    api: "openai-completions",
+    auth: "api-key",
+    models
+  };
+}
+async function fetchNexosModels(apiKey, fetchImpl = fetch) {
+  const response = await fetchImpl(`${NEXOS_BASE_URL}/models`, {
+    headers: { Authorization: `Bearer ${apiKey}` }
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Nexos model list request failed: ${response.status} ${response.statusText}`
+    );
+  }
+  return response.json();
+}
+
+// src/index.ts
+var CATALOG_TTL_MS = 6e4;
+var catalogCache = /* @__PURE__ */ new Map();
+async function getNexosCatalog(apiKey) {
+  const cached = catalogCache.get(apiKey);
+  if (cached && Date.now() - cached.fetchedAt < CATALOG_TTL_MS) {
+    return cached.models;
+  }
+  const models = buildNexosCatalog(await fetchNexosModels(apiKey));
+  catalogCache.set(apiKey, { fetchedAt: Date.now(), models });
+  return models;
+}
+function resolveNexosApiKey(ctx, providerId) {
+  const tryResolve = (id) => {
+    try {
+      return ctx.resolveProviderApiKey?.(id)?.apiKey;
+    } catch {
+      return void 0;
+    }
+  };
+  return tryResolve(providerId) || tryResolve(NEXOS_PROVIDER_COMPLETIONS) || process.env.NEXOS_API_KEY || void 0;
+}
+function selectModels(models, providerId) {
+  const { completions, anthropic } = splitByEndpoint(models);
+  return providerId === NEXOS_PROVIDER_ANTHROPIC ? anthropic : completions;
+}
+function registerNexosProvider(api, providerId, label) {
+  const kind = providerId === NEXOS_PROVIDER_ANTHROPIC ? "anthropic" : "completions";
+  api.registerProvider({
+    id: providerId,
+    label,
+    docsPath: "/providers/nexos",
+    envVars: ["NEXOS_API_KEY"],
+    auth: [
+      createProviderApiKeyAuthMethod({
+        providerId,
+        methodId: "api-key",
+        label: "Nexos AI API key",
+        hint: "API key from your Nexos AI dashboard",
+        optionKey: "nexosApiKey",
+        flagName: "--nexos-api-key",
+        envVar: "NEXOS_API_KEY",
+        promptMessage: "Enter your Nexos AI API key"
+      })
+    ],
+    catalog: {
+      order: "simple",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      run: async (ctx) => {
+        const apiKey = resolveNexosApiKey(ctx, providerId);
+        if (!apiKey) {
+          return null;
+        }
+        let models;
+        try {
+          models = await getNexosCatalog(apiKey);
+        } catch {
+          return null;
+        }
+        const selected = selectModels(models, providerId);
+        if (selected.length === 0) {
+          return null;
+        }
+        return { provider: buildProviderConfig({ models: selected, apiKey, kind }) };
+      }
+    }
+  });
+  api.registerModelCatalogProvider({
+    provider: providerId,
+    kinds: ["text"],
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    liveCatalog: async (ctx) => {
+      const apiKey = resolveNexosApiKey(ctx, providerId);
+      if (!apiKey) {
+        return null;
+      }
+      let models;
+      try {
+        models = await getNexosCatalog(apiKey);
+      } catch {
+        return null;
+      }
+      return selectModels(models, providerId).map((model) => ({
+        kind: "text",
+        provider: providerId,
+        model: model.nexosModelId,
+        label: model.alias,
+        source: "live"
+      }));
+    }
+  });
+}
+var index_default = definePluginEntry({
+  id: "nexos",
+  name: "Nexos AI",
+  description: "Nexos AI unified gateway \u2014 access Claude, GPT, Gemini, Grok and 60+ models through one API key.",
+  register(api) {
+    registerNexosProvider(api, NEXOS_PROVIDER_COMPLETIONS, "Nexos AI");
+    registerNexosProvider(api, NEXOS_PROVIDER_ANTHROPIC, "Nexos AI (Claude)");
+  }
+});
+export {
+  index_default as default
+};

package/docs/providers/nexos.md

@@ -0,0 +1,47 @@
+---
+title: "Nexos AI"
+summary: "Use Nexos AI's unified gateway (Claude, GPT, Gemini, Grok, and more) in OpenClaw via one API key"
+---
+
+Nexos AI is a unified AI gateway that provides OpenAI-compatible access to models
+from many providers — Anthropic, OpenAI, Google, xAI, Mistral, and more — through
+a single API endpoint and API key.
+
+This plugin registers two OpenClaw providers, both authenticated with
+`NEXOS_API_KEY`:
+
+- **`nexos`** — OpenAI-compatible `/v1/chat/completions` transport for all
+  general models.
+- **`nexos-anthropic`** — Anthropic-style `/v1/messages` transport for Claude
+  models that advertise the `messages` endpoint (native tool_use and caching).
+
+## Getting started
+
+1. Get an API key from your Nexos AI dashboard.
+2. Provide it to OpenClaw:
+
+   ```bash
+   openclaw onboard --nexos-api-key "$NEXOS_API_KEY"
+   # or set NEXOS_API_KEY in the environment
+   ```
+
+3. Verify the models are available:
+
+   ```bash
+   openclaw models list --provider nexos
+   openclaw models list --provider nexos-anthropic
+   ```
+
+## Model discovery
+
+The plugin fetches the Nexos `/v1/models` list at runtime and projects each model
+into an OpenClaw model definition, so the catalog reflects exactly what your
+account can access. Models advertising the `messages` endpoint are routed through
+`nexos-anthropic`; the rest through `nexos`.
+
+## Notes
+
+- One API key, many providers — no separate accounts/keys per model vendor.
+- Cost is tracked centrally by Nexos; the plugin reports zeroed per-token cost.
+- A conservative `maxTokens`/`contextWindow` default is applied because Nexos
+  does not advertise per-model output limits.

package/openclaw.plugin.json

@@ -0,0 +1,38 @@
+{
+  "id": "nexos",
+  "name": "Nexos AI",
+  "description": "Nexos AI unified gateway — access Claude, GPT, Gemini, Grok and 60+ models through one API key.",
+  "providers": ["nexos", "nexos-anthropic"],
+  "modelSupport": {
+    "modelPrefixes": ["nexos/", "nexos-anthropic/"]
+  },
+  "setup": {
+    "providers": [
+      { "id": "nexos", "envVars": ["NEXOS_API_KEY"] },
+      { "id": "nexos-anthropic", "envVars": ["NEXOS_API_KEY"] }
+    ]
+  },
+  "providerAuthAliases": {
+    "nexos-anthropic": "nexos"
+  },
+  "providerAuthChoices": [
+    {
+      "provider": "nexos",
+      "method": "api-key",
+      "choiceId": "nexos-api-key",
+      "choiceLabel": "Nexos AI API key",
+      "groupId": "nexos",
+      "groupLabel": "Nexos AI",
+      "cliFlag": "--nexos-api-key",
+      "cliOption": "--nexos-api-key <key>",
+      "cliDescription": "Nexos AI API key"
+    }
+  ],
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "openclaw-nexos-provider",
+  "version": "0.1.0",
+  "description": "Nexos AI model provider plugin for OpenClaw — access Claude, GPT, Gemini, Grok and 60+ models through one API key.",
+  "type": "module",
+  "license": "MIT",
+  "author": "fizikiukas",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fizikiukas/openclaw-nexos-provider.git"
+  },
+  "homepage": "https://github.com/fizikiukas/openclaw-nexos-provider#readme",
+  "bugs": {
+    "url": "https://github.com/fizikiukas/openclaw-nexos-provider/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "clawhub",
+    "nexos",
+    "nexos-ai",
+    "llm",
+    "ai",
+    "model-provider"
+  ],
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --out-dir dist --target node22 --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.7.1-2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "2026.7.1-2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.9"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "providers": [
+      "nexos",
+      "nexos-anthropic"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.7.1-2",
+      "minGatewayVersion": "2026.7.1-2"
+    },
+    "build": {
+      "openclawVersion": "2026.7.1-2",
+      "pluginSdkVersion": "2026.7.1-2"
+    }
+  }
+}