@n8n-as-code/n8nac 2026.4.1 → 2026.5.0-next.9

package/README.md

@@ -23,10 +23,12 @@ Restart the gateway, then run the setup wizard:
 openclaw n8nac:setup
 ```
 
-The wizard asks for your n8n host URL and API key once, saves them via
+The wizard asks for your n8n host URL and API key once, saves an instance config via
 `n8nac init-auth`, selects your project, and generates an AI context file
 (`AGENTS.md`) in the workspace (`~/.openclaw/n8nac/`).
 
+After setup, saved instance configs can also be listed, selected, and deleted through the same shared `n8nac` instance library used by the CLI and VS Code extension.
+
 ## Usage
 
 Once setup is done, just talk to OpenClaw:
@@ -63,7 +65,7 @@ All files live in `~/.openclaw/n8nac/`:
 
 ```
 ~/.openclaw/n8nac/
-  n8nac-config.json     ← project binding (written by n8nac init-project)
+  n8nac-config.json     ← saved instance configs + active selection
   AGENTS.md             ← AI context (written by n8nac update-ai)
   workflows/            ← .workflow.ts files (your n8n workflows)
 ```
@@ -75,8 +77,11 @@ The plugin registers the `n8nac` tool with these actions:
 | Action | Description |
 |---|---|
 | `setup_check` | Check initialization state |
-| `init_auth` | Save n8n credentials |
+| `init_auth` | Save n8n credentials; pass `newInstance: true` to add another saved config |
 | `init_project` | Select n8n project |
+| `instance_list` | List saved instance configs |
+| `instance_select` | Select the active saved instance config |
+| `instance_delete` | Delete a saved instance config |
 | `list` | List all workflows |
 | `pull` | Download a workflow by ID |
 | `push` | Upload a workflow file |
@@ -119,7 +124,7 @@ openclaw n8nac:setup
 ```
 
 Enter your n8n host and API key when prompted. The wizard writes
-`~/.openclaw/n8nac/n8nac-config.json` and generates `AGENTS.md`.
+`~/.openclaw/n8nac/n8nac-config.json` with the saved instance configs and active selection, then generates `AGENTS.md`.
 
 ### 4. Iterate on the code
 
@@ -141,7 +146,7 @@ The plugin prefixes all `api.logger` calls with `[n8nac]`.
 
 ```
 ~/.openclaw/n8nac/
-  n8nac-config.json   ← written by init-project
+  n8nac-config.json   ← saved instance configs + active selection
   AGENTS.md           ← written by update-ai
   workflows/          ← .workflow.ts files
 ```

package/index.ts

@@ -1,9 +1,9 @@
-import { accessSync, constants, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { accessSync, constants, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { registerN8nAcCli } from "./src/cli.js";
 import { createN8nAcTool } from "./src/tool.js";
-import { getWorkspaceDir, isWorkspaceInitialized } from "./src/workspace.js";
+import { getWorkspaceDir, isWorkspaceInitialized, readWorkspaceBinding } from "./src/workspace.js";
 
 // ---------------------------------------------------------------------------
 // Lightweight prompt context
@@ -21,17 +21,8 @@ Once you have both, call the \`n8nac\` tool with \`action: "init_auth"\`, then
 \`action: "init_project"\` to finish setup.
 `;
 
-function readConfig(workspaceDir: string): Record<string, string> {
-  try {
-    const raw = readFileSync(join(workspaceDir, "n8nac-config.json"), "utf-8");
-    return JSON.parse(raw) as Record<string, string>;
-  } catch {
-    return {};
-  }
-}
-
 function buildStatusHeader(workspaceDir: string): string {
-  const cfg = readConfig(workspaceDir);
+  const cfg = readWorkspaceBinding(workspaceDir);
   const host = cfg.host ?? "(unknown)";
   const project = cfg.projectName ?? cfg.projectId ?? "(unknown)";
   return [
@@ -40,6 +31,7 @@ function buildStatusHeader(workspaceDir: string): string {
     "**The workspace is already fully initialized. Do NOT ask the user for credentials.**",
     "",
     `- Workspace directory: \`${workspaceDir}\``,
+    `- Active instance: \`${cfg.activeInstanceName ?? cfg.activeInstanceId ?? "(unknown)"}\``,
     `- n8n host: \`${host}\``,
     `- Active project: \`${project}\``,
   ].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n-as-code/n8nac",
-  "version": "2026.4.1",
+  "version": "2026.5.0-next.9",
   "description": "OpenClaw plugin for n8n-as-code — create and manage n8n workflows from OpenClaw",
   "keywords": [
     "n8n",

package/skills/n8n-architect/SKILL.md

@@ -12,11 +12,12 @@ Use this skill only for explicit n8n workflow work.
 1. Check whether `n8nac-config.json` exists in the workspace root.
 2. If the workspace is initialized, read `AGENTS.md` from the workspace root before making workflow changes. It is the detailed, workspace-specific source of truth generated by `n8nac update-ai`.
 3. If `AGENTS.md` is missing or unreadable, regenerate it with `npx --yes n8nac update-ai` or run the `openclaw n8nac:setup` command before attempting workflow authoring.
-4. If the workspace is not initialized, ask the user for the n8n host URL and API key, then use the `n8nac` tool with `action: "init_auth"` and `action: "init_project"` to complete setup yourself.
+4. If the workspace is not initialized, ask the user for the n8n host URL and API key, then use the `n8nac` tool with `action: "init_auth"` and `action: "init_project"` to complete setup yourself. If you need to add a second saved instance later, call `action: "init_auth"` with `newInstance: true` first.
 
 ## Using the n8nac tool
 
-- Use the `n8nac` tool for setup checks, workflow list/pull/push/verify, validation, and `skills` lookups.
+- Use the `n8nac` tool for setup checks, saved instance config management, workflow list/pull/push/verify, validation, and `skills` lookups.
+- Use `action: "instance_list"` to inspect saved configs, `action: "instance_select"` to switch the active config, and `action: "instance_delete"` to remove a stale saved config.
 - Use `action: "skills"` whenever you need node search or schema details.
 - Never guess node parameters. The schema lookup is the source of truth.
 - Treat `AGENTS.md` as the authoritative workflow-engineering protocol once this skill is active.

package/src/tool.ts

@@ -11,6 +11,9 @@ const ACTIONS = [
   "setup_check",
   "init_auth",
   "init_project",
+  "instance_list",
+  "instance_select",
+  "instance_delete",
   "list",
   "pull",
   "push",
@@ -28,8 +31,11 @@ const N8nAcToolSchema = Type.Object({
     description: [
       "Action to perform:",
       "  setup_check  — check whether the workspace is initialized.",
-      "  init_auth    — save n8n credentials. Requires n8nHost and n8nApiKey.",
+      "  init_auth    — save n8n credentials. Requires n8nHost and n8nApiKey. Pass newInstance: true to add another saved config.",
       "  init_project — select the n8n project. Optionally pass projectId, projectName, or projectIndex (1-based, default 1).",
+      "  instance_list   — list saved n8n instance configs as JSON.",
+      "  instance_select — switch the active saved instance config. Requires instanceId, instanceName, or instanceIndex.",
+      "  instance_delete — delete a saved instance config. Requires instanceId, instanceName, or instanceIndex.",
       "  list         — list all workflows with their sync status.",
       "  pull         — download a workflow from n8n. Requires workflowId.",
       "  push         — upload a local workflow file. Requires filename (e.g. my-flow.workflow.ts).",
@@ -43,12 +49,17 @@ const N8nAcToolSchema = Type.Object({
     Type.String({ description: "n8n host URL (for init_auth). Example: https://your-n8n.example.com" }),
   ),
   n8nApiKey: Type.Optional(Type.String({ description: "n8n API key (for init_auth)" })),
+  newInstance: Type.Optional(Type.Boolean({ description: "Save credentials as a new saved instance config instead of updating the current one (for init_auth)." })),
   // init_project
   projectId: Type.Optional(Type.String({ description: "n8n project ID (for init_project)" })),
   projectName: Type.Optional(Type.String({ description: "n8n project name (for init_project)" })),
   projectIndex: Type.Optional(
     Type.Number({ description: "n8n project index, 1-based (for init_project, default: 1)" }),
   ),
+  // instance_select / instance_delete
+  instanceId: Type.Optional(Type.String({ description: "Saved instance config ID (for instance_select, instance_delete)." })),
+  instanceName: Type.Optional(Type.String({ description: "Saved instance config name (for instance_select, instance_delete)." })),
+  instanceIndex: Type.Optional(Type.Number({ description: "Saved instance config index, 1-based (for instance_select, instance_delete)." })),
   listScope: Type.Optional(
     Type.Unsafe<(typeof LIST_SCOPES)[number]>({
       type: "string",
@@ -229,7 +240,7 @@ export function createN8nAcTool(opts: { workspaceDir: string }) {
     label: "n8n-as-code",
     description:
       "Create and manage n8n workflows using n8n-as-code. " +
-      "Handles workspace initialization (init_auth → init_project), " +
+      "Handles workspace initialization (init_auth → init_project), saved instance config management, " +
       "workflow sync (list, pull, push, verify), and AI knowledge lookup (skills, validate). " +
       "Always call setup_check first to determine initialization state.",
     parameters: N8nAcToolSchema,
@@ -244,7 +255,7 @@ export function createN8nAcTool(opts: { workspaceDir: string }) {
           initialized,
           workspaceDir,
           next: initialized
-            ? "Workspace is ready. Use list, pull, push, verify, or skills."
+            ? "Workspace is ready. Use instance_list, instance_select, list, pull, push, verify, or skills."
             : "Workspace not initialized. Ask the user for their n8n host URL and API key, then call init_auth.",
         });
       }
@@ -256,7 +267,11 @@ export function createN8nAcTool(opts: { workspaceDir: string }) {
         if (!host || !key) {
           return ok({ error: "n8nHost and n8nApiKey are required for init_auth" });
         }
-        const r = await runNpx(["init-auth", "--host", host, "--api-key-stdin"], workspaceDir, key);
+        const args = ["init-auth", "--host", host, "--api-key-stdin"];
+        if (params.newInstance === true) {
+          args.push("--new-instance");
+        }
+        const r = await runNpx(args, workspaceDir, key);
         if (r.exitCode !== 0) {
           return ok({ error: r.stderr || r.stdout, exitCode: r.exitCode });
         }
@@ -299,6 +314,48 @@ export function createN8nAcTool(opts: { workspaceDir: string }) {
         });
       }
 
+      // ---- instance_list -----------------------------------------------
+      if (action === "instance_list") {
+        const r = await runNpx(["instance", "list", "--json"], workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      // ---- instance_select ---------------------------------------------
+      if (action === "instance_select") {
+        const instanceId = str(params.instanceId);
+        const instanceName = str(params.instanceName);
+        const instanceIndex = typeof params.instanceIndex === "number" ? params.instanceIndex : undefined;
+        if (!instanceId && !instanceName && instanceIndex === undefined) {
+          return ok({ error: "instanceId, instanceName, or instanceIndex is required for instance_select" });
+        }
+
+        const args = ["instance", "select"];
+        if (instanceId) args.push("--instance-id", instanceId);
+        else if (instanceName) args.push("--instance-name", instanceName);
+        else args.push("--instance-index", String(instanceIndex));
+
+        const r = await runNpx(args, workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      // ---- instance_delete ---------------------------------------------
+      if (action === "instance_delete") {
+        const instanceId = str(params.instanceId);
+        const instanceName = str(params.instanceName);
+        const instanceIndex = typeof params.instanceIndex === "number" ? params.instanceIndex : undefined;
+        if (!instanceId && !instanceName && instanceIndex === undefined) {
+          return ok({ error: "instanceId, instanceName, or instanceIndex is required for instance_delete" });
+        }
+
+        const args = ["instance", "delete", "--yes"];
+        if (instanceId) args.push("--instance-id", instanceId);
+        else if (instanceName) args.push("--instance-name", instanceName);
+        else args.push("--instance-index", String(instanceIndex));
+
+        const r = await runNpx(args, workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
       // ---- list ---------------------------------------------------------
       if (action === "list") {
         const scope = str(params.listScope) || "all";

package/src/workspace.ts

@@ -2,6 +2,15 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+export type WorkspaceBinding = {
+  host?: string;
+  projectId?: string;
+  projectName?: string;
+  syncFolder?: string;
+  activeInstanceId?: string;
+  activeInstanceName?: string;
+};
+
 /**
  * Fixed workspace directory for V1.
  * All n8nac files (n8nac-config.json, AGENTS.md, workflows/) live here.
@@ -10,22 +19,63 @@ export function getWorkspaceDir(): string {
   return join(homedir(), ".openclaw", "n8nac");
 }
 
-/**
- * Returns true when n8nac has been initialized in the given directory,
- * meaning the config exists and contains a selected project + sync folder.
- */
-export function isWorkspaceInitialized(workspaceDir: string): boolean {
+function readString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function resolveActiveInstance(config: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (!Array.isArray(config.instances)) {
+    return undefined;
+  }
+
+  const instances = config.instances.filter((value): value is Record<string, unknown> => !!value && typeof value === "object");
+  if (!instances.length) {
+    return undefined;
+  }
+
+  const activeInstanceId = readString(config.activeInstanceId);
+  if (activeInstanceId) {
+    return instances.find((instance) => readString(instance.id) === activeInstanceId) || instances[0];
+  }
+
+  return instances[0];
+}
+
+export function readWorkspaceBinding(workspaceDir: string): WorkspaceBinding {
   const configPath = join(workspaceDir, "n8nac-config.json");
-  if (!existsSync(configPath)) return false;
+  if (!existsSync(configPath)) {
+    return {};
+  }
 
   try {
     const raw = readFileSync(configPath, "utf-8");
     const config = JSON.parse(raw) as Record<string, unknown>;
-    const projectId = typeof config.projectId === "string" ? config.projectId.trim() : "";
-    const projectName = typeof config.projectName === "string" ? config.projectName.trim() : "";
-    const syncFolder = typeof config.syncFolder === "string" ? config.syncFolder.trim() : "";
-    return projectId.length > 0 && projectName.length > 0 && syncFolder.length > 0;
+    const activeInstance = resolveActiveInstance(config);
+    const configActiveInstanceId = readString(config.activeInstanceId);
+    const resolvedActiveInstanceId = readString(activeInstance?.id);
+    const activeInstanceId =
+      resolvedActiveInstanceId && resolvedActiveInstanceId === configActiveInstanceId
+        ? configActiveInstanceId
+        : resolvedActiveInstanceId || undefined;
+
+    return {
+      host: readString(activeInstance?.host) || readString(config.host) || undefined,
+      projectId: readString(activeInstance?.projectId) || readString(config.projectId) || undefined,
+      projectName: readString(activeInstance?.projectName) || readString(config.projectName) || undefined,
+      syncFolder: readString(activeInstance?.syncFolder) || readString(config.syncFolder) || undefined,
+      activeInstanceId,
+      activeInstanceName: readString(activeInstance?.name) || undefined,
+    };
   } catch {
-    return false;
+    return {};
   }
 }
+
+/**
+ * Returns true when n8nac has been initialized in the given directory,
+ * meaning the config exists and contains a selected project + sync folder.
+ */
+export function isWorkspaceInitialized(workspaceDir: string): boolean {
+  const binding = readWorkspaceBinding(workspaceDir);
+  return Boolean(binding.projectId && binding.projectName && binding.syncFolder);
+}