@nextclaw/nextclaw-engine-codex-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw 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,35 @@
+# @nextclaw/nextclaw-engine-codex-sdk
+
+Independent NextClaw engine plugin that registers `codex-sdk` using OpenAI official `@openai/codex-sdk`.
+
+## Build
+
+```bash
+pnpm -C packages/extensions/nextclaw-engine-plugin-codex-sdk build
+```
+
+## Usage (local path)
+
+Add plugin load path to config:
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": [
+        "/absolute/path/to/packages/extensions/nextclaw-engine-plugin-codex-sdk"
+      ]
+    }
+  },
+  "agents": {
+    "defaults": {
+      "engine": "codex-sdk",
+      "model": "openai/gpt-5-codex",
+      "engineConfig": {
+        "apiBase": "https://your-relay.example.com/v1",
+        "apiKey": "sk-xxx"
+      }
+    }
+  }
+}
+```

package/codex-sdk-loader.cjs

@@ -0,0 +1,17 @@
+let cachedCtor = null;
+
+async function loadCodexConstructor() {
+  if (cachedCtor) {
+    return cachedCtor;
+  }
+  const mod = await import("@openai/codex-sdk");
+  if (!mod || typeof mod.Codex !== "function") {
+    throw new Error("[codex-sdk] failed to load Codex constructor from @openai/codex-sdk");
+  }
+  cachedCtor = mod.Codex;
+  return cachedCtor;
+}
+
+module.exports = {
+  loadCodexConstructor
+};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AgentEngineFactoryContext, AgentEngine } from '@nextclaw/core';
+
+type PluginApi = {
+    registerEngine: (factory: (context: AgentEngineFactoryContext) => AgentEngine, opts?: {
+        kind?: string;
+    }) => void;
+};
+type PluginDefinition = {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: Record<string, unknown>;
+    register: (api: PluginApi) => void;
+};
+declare const plugin: PluginDefinition;
+
+export { plugin as default };

package/dist/index.js

@@ -0,0 +1,308 @@
+import { createRequire } from "node:module";
+import {
+  getApiBase,
+  getProvider,
+  SkillsLoader
+} from "@nextclaw/core";
+function readString(input, key) {
+  const value = input[key];
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function readBoolean(input, key) {
+  const value = input[key];
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return void 0;
+}
+function readStringRecord(input, key) {
+  const value = input[key];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  const out = {};
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    if (typeof entryValue !== "string") {
+      continue;
+    }
+    const normalized = entryValue.trim();
+    if (!normalized) {
+      continue;
+    }
+    out[entryKey] = normalized;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function readRecord(input, key) {
+  const value = input[key];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function readStringArray(input, key) {
+  const value = input[key];
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const normalized = value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter(Boolean);
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readRequestedSkills(metadata) {
+  if (!metadata) {
+    return [];
+  }
+  const raw = metadata.requested_skills ?? metadata.requestedSkills;
+  const values = [];
+  if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      if (typeof entry !== "string") {
+        continue;
+      }
+      const trimmed = entry.trim();
+      if (trimmed) {
+        values.push(trimmed);
+      }
+    }
+  } else if (typeof raw === "string") {
+    values.push(
+      ...raw.split(/[,\s]+/g).map((entry) => entry.trim()).filter(Boolean)
+    );
+  }
+  return Array.from(new Set(values)).slice(0, 8);
+}
+function readReasoningEffort(input, key) {
+  const value = readString(input, key);
+  if (value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh") {
+    return value;
+  }
+  return void 0;
+}
+function readSandboxMode(input, key) {
+  const value = readString(input, key);
+  if (value === "read-only" || value === "workspace-write" || value === "danger-full-access") {
+    return value;
+  }
+  return void 0;
+}
+function readApprovalPolicy(input, key) {
+  const value = readString(input, key);
+  if (value === "never" || value === "on-request" || value === "on-failure" || value === "untrusted") {
+    return value;
+  }
+  return void 0;
+}
+function readWebSearchMode(input, key) {
+  const value = readString(input, key);
+  if (value === "disabled" || value === "cached" || value === "live") {
+    return value;
+  }
+  return void 0;
+}
+function resolveEngineConfig(config, model, engineConfig) {
+  const provider = getProvider(config, model);
+  const apiKey = readString(engineConfig, "apiKey") ?? provider?.apiKey ?? void 0;
+  const apiBase = readString(engineConfig, "apiBase") ?? getApiBase(config, model) ?? void 0;
+  return { apiKey, apiBase };
+}
+const require2 = createRequire(import.meta.url);
+const codexLoader = require2("../codex-sdk-loader.cjs");
+class PluginCodexSdkEngine {
+  constructor(options) {
+    this.options = options;
+    this.defaultModel = options.model;
+    this.threadOptions = options.threadOptions;
+    this.skillsLoader = new SkillsLoader(options.workspace);
+  }
+  kind = "codex-sdk";
+  codexPromise = null;
+  threads = /* @__PURE__ */ new Map();
+  defaultModel;
+  threadOptions;
+  skillsLoader;
+  async handleInbound(params) {
+    const reply = await this.processDirect({
+      content: params.message.content,
+      sessionKey: params.sessionKey,
+      channel: params.message.channel,
+      chatId: params.message.chatId,
+      metadata: params.message.metadata
+    });
+    if (!reply.trim()) {
+      return null;
+    }
+    const outbound = {
+      channel: params.message.channel,
+      chatId: params.message.chatId,
+      content: reply,
+      media: [],
+      metadata: {}
+    };
+    if (params.publishResponse ?? true) {
+      await this.options.bus.publishOutbound(outbound);
+    }
+    return outbound;
+  }
+  async processDirect(params) {
+    const sessionKey = typeof params.sessionKey === "string" && params.sessionKey.trim() ? params.sessionKey : "cli:direct";
+    const channel = typeof params.channel === "string" && params.channel.trim() ? params.channel : "cli";
+    const chatId = typeof params.chatId === "string" && params.chatId.trim() ? params.chatId : "direct";
+    const model = readString(params.metadata ?? {}, "model") ?? this.defaultModel;
+    const requestedSkills = readRequestedSkills(params.metadata ?? {});
+    const session = this.options.sessionManager.getOrCreate(sessionKey);
+    const userExtra = { channel, chatId };
+    if (requestedSkills.length > 0) {
+      userExtra.requested_skills = requestedSkills;
+    }
+    const userEvent = this.options.sessionManager.addMessage(session, "user", params.content, userExtra);
+    params.onSessionEvent?.(userEvent);
+    const requestedSkillsContent = this.skillsLoader.loadSkillsForContext(requestedSkills);
+    const prompt = requestedSkillsContent.trim().length > 0 ? [
+      "## Requested Skills",
+      "Use the following selected skills for this turn:",
+      requestedSkillsContent,
+      "## User Message",
+      params.content
+    ].join("\n\n") : params.content;
+    const thread = await this.resolveThread(sessionKey, model);
+    const streamed = await thread.runStreamed(prompt);
+    const itemTextById = /* @__PURE__ */ new Map();
+    const completedAgentMessages = [];
+    for await (const event of streamed.events) {
+      const streamEvent = this.options.sessionManager.appendEvent(session, {
+        type: `engine.codex.${event.type}`,
+        data: { event },
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      params.onSessionEvent?.(streamEvent);
+      this.emitAssistantDelta(event, itemTextById, params.onAssistantDelta);
+      if (event.type === "item.completed" && event.item.type === "agent_message") {
+        const text = event.item.text.trim();
+        if (text) {
+          completedAgentMessages.push(text);
+        }
+      }
+      if (event.type === "turn.failed") {
+        throw new Error(event.error.message);
+      }
+      if (event.type === "error") {
+        throw new Error(event.message);
+      }
+    }
+    const reply = completedAgentMessages.join("\n").trim();
+    const assistantEvent = this.options.sessionManager.addMessage(session, "assistant", reply, {
+      channel,
+      chatId
+    });
+    params.onSessionEvent?.(assistantEvent);
+    this.options.sessionManager.save(session);
+    return reply;
+  }
+  applyRuntimeConfig(_config) {
+  }
+  async getCodex() {
+    if (!this.codexPromise) {
+      this.codexPromise = codexLoader.loadCodexConstructor().then(
+        (Ctor) => new Ctor({
+          apiKey: this.options.apiKey,
+          baseUrl: this.options.apiBase,
+          ...this.options.codexPathOverride ? { codexPathOverride: this.options.codexPathOverride } : {},
+          ...this.options.env ? { env: this.options.env } : {},
+          ...this.options.cliConfig ? { config: this.options.cliConfig } : {}
+        })
+      );
+    }
+    return this.codexPromise;
+  }
+  async resolveThread(sessionKey, model) {
+    const cached = this.threads.get(sessionKey);
+    if (cached) {
+      return cached;
+    }
+    const codex = await this.getCodex();
+    const thread = codex.startThread({
+      ...this.threadOptions,
+      model
+    });
+    this.threads.set(sessionKey, thread);
+    return thread;
+  }
+  emitAssistantDelta(event, itemTextById, onAssistantDelta) {
+    if (!onAssistantDelta) {
+      return;
+    }
+    if (event.type !== "item.updated" && event.type !== "item.completed") {
+      return;
+    }
+    if (event.item.type !== "agent_message") {
+      return;
+    }
+    const current = event.item.text ?? "";
+    const previous = itemTextById.get(event.item.id) ?? "";
+    if (current.length <= previous.length) {
+      itemTextById.set(event.item.id, current);
+      return;
+    }
+    const delta = current.slice(previous.length);
+    if (delta) {
+      onAssistantDelta(delta);
+    }
+    itemTextById.set(event.item.id, current);
+  }
+}
+const plugin = {
+  id: "nextclaw-engine-codex-sdk",
+  name: "NextClaw Codex SDK Engine",
+  description: "Registers engine kind `codex-sdk` backed by OpenAI Codex SDK.",
+  configSchema: {
+    type: "object",
+    additionalProperties: true,
+    properties: {}
+  },
+  register(api) {
+    api.registerEngine(
+      (context) => {
+        const engineConfig = context.engineConfig ?? {};
+        const model = readString(engineConfig, "model") ?? context.model;
+        const resolved = resolveEngineConfig(context.config, model, engineConfig);
+        if (!resolved.apiKey) {
+          throw new Error(
+            `[codex-sdk] missing apiKey. Set agents.defaults.engineConfig.apiKey or providers.*.apiKey for model "${model}".`
+          );
+        }
+        return new PluginCodexSdkEngine({
+          bus: context.bus,
+          sessionManager: context.sessionManager,
+          model,
+          workspace: context.workspace,
+          apiKey: resolved.apiKey,
+          apiBase: resolved.apiBase,
+          codexPathOverride: readString(engineConfig, "codexPathOverride"),
+          env: readStringRecord(engineConfig, "env"),
+          cliConfig: readRecord(engineConfig, "config"),
+          threadOptions: {
+            model,
+            sandboxMode: readSandboxMode(engineConfig, "sandboxMode"),
+            workingDirectory: readString(engineConfig, "workingDirectory") ?? context.workspace,
+            skipGitRepoCheck: readBoolean(engineConfig, "skipGitRepoCheck"),
+            modelReasoningEffort: readReasoningEffort(engineConfig, "modelReasoningEffort"),
+            networkAccessEnabled: readBoolean(engineConfig, "networkAccessEnabled"),
+            webSearchMode: readWebSearchMode(engineConfig, "webSearchMode"),
+            webSearchEnabled: readBoolean(engineConfig, "webSearchEnabled"),
+            approvalPolicy: readApprovalPolicy(engineConfig, "approvalPolicy"),
+            additionalDirectories: readStringArray(engineConfig, "additionalDirectories")
+          }
+        });
+      },
+      { kind: "codex-sdk" }
+    );
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default
+};

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "nextclaw-engine-codex-sdk",
+  "name": "NextClaw Codex SDK Engine",
+  "description": "Registers engine kind `codex-sdk` backed by OpenAI Codex SDK.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nextclaw/nextclaw-engine-codex-sdk",
+  "version": "0.2.0",
+  "private": false,
+  "description": "NextClaw Codex engine plugin backed by OpenAI Codex SDK.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "codex-sdk-loader.cjs",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  },
+  "dependencies": {
+    "@nextclaw/core": "^0.7.0",
+    "@openai/codex-sdk": "^0.107.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}