@openviking/openclaw-plugin 2026.6.18 → 2026.7.11

package/INSTALL-AGENT.md

@@ -153,11 +153,11 @@ openclaw --version
 Requirements:
 
 - Node.js >= 22
-- OpenClaw >= 2026.4.8
+- OpenClaw >= 2026.5.27
 
 Version boundaries:
 
-- `2026.4.8` is the minimum supported OpenClaw version for the current `@openviking/openclaw-plugin` plugin.
+- `2026.5.27` is the minimum supported OpenClaw version for the current `@openviking/openclaw-plugin` plugin.
 - `2026.5.3` starts requiring compiled JavaScript runtime output during package install when a plugin package declares TypeScript entries.
 - `2026.5.4` and later no longer fall back to `.ts` source for installed/global plugin runtime loading when the compiled JavaScript output is missing; the plugin may be skipped.
 - Published ClawHub packages are built before release and include `dist/*.js`, so normal users do not need to build locally.

package/INSTALL-ZH.md

@@ -27,13 +27,13 @@ openclaw plugins install clawhub:@openviking/openclaw-plugin
 | 组件 | 要求 |
 | --- | --- |
 | Node.js | >= 22 |
-| OpenClaw | >= 2026.4.8 |
+| OpenClaw | >= 2026.5.27 |
 
 插件以远程模式连接到已有的 OpenViking 服务。它不会帮你启动 OpenViking server。需要先启动 OpenViking，并保持服务运行，再把插件的 `baseUrl` 指向这个 HTTP 服务。默认本地地址是 `http://127.0.0.1:1933`。
 
 OpenClaw 插件包版本边界：
 
-- `2026.4.8` 是当前插件支持的最低 OpenClaw 版本。
+- `2026.5.27` 是当前插件支持的最低 OpenClaw 版本。这个版本下限包含 2026 年 7 月 2 日 OpenClaw 安全公告批次的修复，包括 GHSA-8wg3-5mcm-fjq8 和 GHSA-83w9-h5wv-j9xm。
 - `2026.5.3` 开始，OpenClaw 在安装包时会校验 TypeScript 插件入口是否有编译后的 JavaScript 产物。
 - `2026.5.4` 及之后，已安装/全局插件如果缺少编译后的 JavaScript，运行时不再回退加载 `.ts` 源码，插件可能被跳过。
 - 推荐的 `openclaw plugins install clawhub:@openviking/openclaw-plugin` 会安装已经发布并包含 `dist/*.js` 的插件包，普通用户不需要本地编译。

package/INSTALL.md

@@ -27,13 +27,13 @@ openclaw plugins install clawhub:@openviking/openclaw-plugin
 | Component | Required |
 | --- | --- |
 | Node.js | >= 22 |
-| OpenClaw | >= 2026.4.8 |
+| OpenClaw | >= 2026.5.27 |
 
 The plugin connects to an existing OpenViking server. It does not start the OpenViking server for you. Start OpenViking first, keep it running, then point the plugin `baseUrl` at that HTTP service. The default local URL is `http://127.0.0.1:1933`.
 
 OpenClaw plugin package boundaries:
 
-- `2026.4.8` is the minimum supported OpenClaw version for the current plugin.
+- `2026.5.27` is the minimum supported OpenClaw version for the current plugin. This floor includes the July 2, 2026 OpenClaw advisory batch fixes, including GHSA-8wg3-5mcm-fjq8 and GHSA-83w9-h5wv-j9xm.
 - `2026.5.3` starts validating package installs so TypeScript plugin entries need compiled JavaScript output.
 - `2026.5.4` and later stop falling back to `.ts` source for installed/global plugin runtime loading when compiled JavaScript is missing.
 - The recommended `openclaw plugins install clawhub:@openviking/openclaw-plugin` path installs a published package that already includes `dist/*.js`.

package/README.md

@@ -204,7 +204,7 @@ That means OpenClaw sees "compressed history summary + archive index + active me
 - it strips injected `<openviking-context>` blocks, historical `<relevant-memories>` blocks, and metadata noise before capture
 - it appends the sanitized turn text into the OpenViking session
 
-After that, the plugin checks `pending_tokens`. Once the session crosses `commitTokenThreshold`, it triggers `commit(wait=false)`:
+After that, the plugin checks `pending_tokens`. Once it reaches `commitTokenThresholdRatio` of the model context window (`tokenBudget`), it triggers `commit(wait=false)`:
 
 - archive generation and Phase 2 memory extraction continue asynchronously on the server
 - the current turn is not blocked waiting for extraction

package/auto-recall.ts

@@ -19,7 +19,6 @@ import {
 import { sanitizeUserTextForCapture } from "./text-utils.js";
 import { estimateTextTokens } from "./token-estimator.js";
 
-const AUTO_RECALL_TIMEOUT_MS = 5_000;
 const RECALL_QUERY_MAX_CHARS = 4_000;
 export const AUTO_RECALL_SOURCE_MARKER = "Source: openviking-auto-recall";
 
@@ -512,7 +511,7 @@ export async function buildAutoRecallContext(params: {
       await recordTrace(memories.slice(0, memoryLines.length), memoryLines.length, estimatedTokens);
       return { block, memoryCount: memoryLines.length, estimatedTokens };
     })(),
-    AUTO_RECALL_TIMEOUT_MS,
+    cfg.autoRecallTimeoutMs,
     "openviking: auto-recall search timeout",
   );
 }

package/client.ts

@@ -41,6 +41,7 @@ function userSessionUri(sessionId: string): string {
 
 export type OpenVikingClientOptions = {
   transport?: HttpTransport;
+  headers?: Record<string, string>;
   resourcePackager?: ResourcePackager;
   now?: () => number;
   sleep?: (ms: number) => Promise<void>;
@@ -48,7 +49,7 @@ export type OpenVikingClientOptions = {
 
 export type CommitSessionResult = {
   session_id: string;
-  /** "accepted" (async), "completed", "failed", or "timeout" (wait mode). */
+  /** "accepted" (async), "skipped" (no archive), "completed", "failed", or "timeout" (wait mode). */
   status: string;
   task_id?: string;
   archive_uri?: string;
@@ -254,6 +255,7 @@ async function cleanupUploadTempPath(path?: string): Promise<void> {
 
 export class OpenVikingClient {
   private readonly transport: HttpTransport;
+  private readonly configuredHeaders: Record<string, string>;
   private readonly now: () => number;
   private readonly sleep: (ms: number) => Promise<void>;
   private readonly resourcePackager: ResourcePackager;
@@ -277,6 +279,7 @@ export class OpenVikingClient {
 	        ? optionsOrLegacyUserScope
 	        : (legacyOptions ?? {});
 	    this.transport = options.transport ?? defaultHttpTransport;
+    this.configuredHeaders = options.headers ?? {};
 	    this.now = options.now ?? Date.now;
 	    this.sleep = options.sleep ?? sleep;
     this.resourcePackager = options.resourcePackager ?? defaultResourcePackager;
@@ -357,6 +360,11 @@ export class OpenVikingClient {
       if (actorPeerHeader) {
         headers.set("X-OpenViking-Actor-Peer", actorPeerHeader);
       }
+      for (const [key, value] of Object.entries(this.configuredHeaders)) {
+        if (key && typeof value === "string" && value.trim()) {
+          headers.set(key, value);
+        }
+      }
       if (init.body && !(init.body instanceof FormData) && !headers.has("Content-Type")) {
         headers.set("Content-Type", "application/json");
       }
@@ -751,19 +759,19 @@ export class OpenVikingClient {
     }>,
     actorPeerId?: string,
     createdAt?: string,
-    roleId?: string,
+    peerId?: string,
   ): Promise<void> {
     const body: {
       role: string;
-      role_id?: string;
+      peer_id?: string;
       parts: typeof parts;
       created_at?: string;
     } = { role, parts };
     if (createdAt) {
       body.created_at = createdAt;
     }
-    if (roleId) {
-      body.role_id = roleId;
+    if (peerId) {
+      body.peer_id = peerId;
     }
     await this.emitRoutingDebug(
       "session message POST (with parts)",
@@ -771,7 +779,7 @@ export class OpenVikingClient {
         path: `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
         sessionId,
         role,
-        role_id: roleId ?? null,
+        peer_id: peerId ?? null,
         partCount: parts.length,
         created_at: createdAt ?? null,
       },

package/commands/setup.ts

@@ -4,6 +4,11 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { getEnv } from "../runtime-utils.js";
+import {
+  cleanOpenVikingRequestHeaders,
+  resolveOpenVikingRequestHeaders,
+  type OpenVikingRequestHeaders,
+} from "../request-headers.js";
 
 const HOME = os.homedir();
 const OPENCLAW_DIR = getEnv("OPENCLAW_STATE_DIR") || path.join(HOME, ".openclaw");
@@ -58,6 +63,7 @@ const PLUGIN_VERSION = readPluginVersion();
 const { min: COMPATIBLE_SERVER_MIN, max: COMPATIBLE_SERVER_MAX } = readCompatRangeFromManifest();
 const CONFIG_KEYS_TO_PRESERVE = [
   "targetUri",
+  "headers",
   "timeoutMs",
   "autoCapture",
   "captureMode",
@@ -71,7 +77,7 @@ const CONFIG_KEYS_TO_PRESERVE = [
   "recallMaxContentChars",
   "recallPreferAbstract",
   "recallTokenBudget",
-  "commitTokenThreshold",
+  "commitTokenThresholdRatio",
   "commitKeepRecentCount",
   "bypassSessionPatterns",
   "emitStandardDiagnostics",
@@ -107,6 +113,11 @@ function maskKey(key: string): string {
   return `${key.slice(0, 4)}...${key.slice(-4)}`;
 }
 
+function nonEmptyOpenVikingRequestHeaders(value: unknown): OpenVikingRequestHeaders | undefined {
+  const headers = cleanOpenVikingRequestHeaders(value);
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
 function isValidPeerPrefixInput(value: string): boolean {
   const trimmed = value.trim();
   return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);
@@ -301,14 +312,21 @@ type ApiKeyProbeResult = {
   detail: string;
 };
 
-async function probeApiKeyType(baseUrl: string, apiKey?: string): Promise<ApiKeyProbeResult> {
+async function probeApiKeyType(
+  baseUrl: string,
+  apiKey?: string,
+  configuredHeaders?: OpenVikingRequestHeaders,
+): Promise<ApiKeyProbeResult> {
   if (!apiKey) return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
 
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), 10_000);
   const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
   try {
-    const headers: Record<string, string> = { "X-API-Key": apiKey };
+    const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
+    const headers: Record<string, string> = {};
+    headers["X-API-Key"] = apiKey;
+    Object.assign(headers, configuredRequestHeaders);
     const response = await fetch(sessionsUrl, {
       headers,
       signal: controller.signal,
@@ -347,6 +365,7 @@ async function probeApiKeyType(baseUrl: string, apiKey?: string): Promise<ApiKey
           "X-API-Key": apiKey,
           "X-OpenViking-Account": "__probe__",
           "X-OpenViking-User": "__probe__",
+          ...configuredRequestHeaders,
         };
         const probe2 = await fetch(sessionsUrl, {
           headers: probeHeaders,
@@ -376,12 +395,20 @@ async function probeApiKeyType(baseUrl: string, apiKey?: string): Promise<ApiKey
   }
 }
 
-async function checkServiceHealth(baseUrl: string, apiKey?: string): Promise<HealthResult> {
+async function checkServiceHealth(
+  baseUrl: string,
+  apiKey?: string,
+  configuredHeaders?: OpenVikingRequestHeaders,
+): Promise<HealthResult> {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), 10_000);
   try {
+    const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
     const headers: Record<string, string> = {};
-    if (apiKey) headers["X-API-Key"] = apiKey;
+    if (apiKey) {
+      headers["X-API-Key"] = apiKey;
+    }
+    Object.assign(headers, configuredRequestHeaders);
     const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/health`, {
       headers,
       signal: controller.signal,
@@ -772,8 +799,9 @@ async function runRemoteCheck(
 ): Promise<void> {
   const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
   const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
+  const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
   console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-  const health = await checkServiceHealth(baseUrl, apiKey);
+  const health = await checkServiceHealth(baseUrl, apiKey, headers);
   if (health.ok) {
     const ver = health.version ? ` (version: ${health.version})` : "";
     console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -955,8 +983,9 @@ async function getStatus(configPath: string): Promise<StatusResult> {
 
   const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
   const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
-  const health = await checkServiceHealth(baseUrl, apiKey);
-  const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+  const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
+  const health = await checkServiceHealth(baseUrl, apiKey, headers);
+  const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey, headers) : undefined;
 
   const peerPrefix = resolveExistingPeerPrefix(existing);
   return {
@@ -1068,6 +1097,7 @@ async function setupRemote(
   const defaultApiKey = existing?.apiKey ? String(existing.apiKey) : "";
   const defaultPeerRole = resolveExistingPeerRole(existing);
   const defaultPeerPrefix = resolveExistingPeerPrefix(existing);
+  const headers = nonEmptyOpenVikingRequestHeaders(existing?.headers);
 
   const baseUrl = await q(tr(zh, "OpenViking server URL", "OpenViking 服务器地址"), defaultUrl);
   const apiKey = await q(tr(zh, "API Key (optional)", "API Key（可选）"), defaultApiKey);
@@ -1077,7 +1107,7 @@ async function setupRemote(
 
   if (apiKey) {
     console.log(tr(zh, "  Detecting API key type...", "  正在检测 API Key 类型..."));
-    const probe = await probeApiKeyType(baseUrl, apiKey);
+    const probe = await probeApiKeyType(baseUrl, apiKey, headers);
     if (probe.keyType === "root_key") {
       console.log(tr(zh,
         "  ⚠ Root API key detected. accountId and userId are required.",
@@ -1098,7 +1128,7 @@ async function setupRemote(
   console.log("");
 
   console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-  const health = await checkServiceHealth(baseUrl, apiKey || undefined);
+  const health = await checkServiceHealth(baseUrl, apiKey || undefined, headers);
   if (health.ok) {
     const ver = health.version ? ` (version: ${health.version})` : "";
     console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);

package/config.ts

@@ -8,6 +8,8 @@ export type MemoryOpenVikingConfig = {
   peer_role?: "none" | "assistant" | "person";
   peer_prefix?: string;
   apiKey?: string;
+  /** Optional HTTP headers merged into every OpenViking request. */
+  headers?: Record<string, string>;
   /** Advanced option. Only needed when explicitly sending tenant identity headers. With a user key the server derives identity from the key. */
   accountId?: string;
   /** Advanced option. Only needed when explicitly sending tenant identity headers. */
@@ -31,7 +33,15 @@ export type MemoryOpenVikingConfig = {
   recallPreferAbstract?: boolean;
   /** @deprecated Use recallMaxInjectedChars. */
   recallTokenBudget?: number;
-  commitTokenThreshold?: number;
+  /**
+   * Auto-commit threshold expressed as a fraction (0-1) of the model context
+   * window (tokenBudget). afterTurn triggers an async commit once estimated
+   * pending tokens reach `commitTokenThresholdRatio * tokenBudget`
+   * (e.g. 0.5 = 50% of the window). Replaces the former absolute
+   * `commitTokenThreshold` (still accepted but ignored for backward
+   * compatibility). Set to 0 to commit every turn.
+   */
+  commitTokenThresholdRatio?: number;
   /**
    * WM v2: number of most-recent messages to keep live after an afterTurn
    * commit so the next turn still has immediate context. Forwarded to the
@@ -109,7 +119,7 @@ const DEFAULT_RECALL_SCORE_THRESHOLD = 0.15;
 const DEFAULT_RECALL_MAX_CONTENT_CHARS = 5000;
 const DEFAULT_RECALL_PREFER_ABSTRACT = false;
 const DEFAULT_RECALL_MAX_INJECTED_CHARS = 4000;
-const DEFAULT_COMMIT_TOKEN_THRESHOLD = 20000;
+const DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO = 0.5;
 const DEFAULT_COMMIT_KEEP_RECENT_COUNT = 10;
 const DEFAULT_BYPASS_SESSION_PATTERNS: string[] = [];
 const DEFAULT_EMIT_STANDARD_DIAGNOSTICS = false;
@@ -280,6 +290,24 @@ function toRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
+function toStringRecord(value: unknown, label: string): Record<string, string> {
+  if (value === undefined || value === null) {
+    return {};
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const record = value as Record<string, unknown>;
+  const out: Record<string, string> = {};
+  for (const [key, val] of Object.entries(record)) {
+    if (typeof val !== "string") {
+      throw new Error(`${label}.${key} must be a string`);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
 function expandToolSelectors(value: unknown, fallback: string[], label: string): OpenVikingToolName[] {
   const entries = toStringArray(value, fallback);
   const seen = new Set<OpenVikingToolName>();
@@ -377,6 +405,7 @@ export const memoryOpenVikingConfigSchema = {
         "peer_prefix",
         "serverAuthMode",
         "apiKey",
+        "headers",
         "accountId",
         "userId",
         "targetUri",
@@ -394,6 +423,7 @@ export const memoryOpenVikingConfigSchema = {
         "recallPreferAbstract",
         "recallTokenBudget",
         "commitTokenThreshold",
+        "commitTokenThresholdRatio",
         "commitKeepRecentCount",
         "bypassSessionPatterns",
         "ingestReplyAssist",
@@ -479,6 +509,7 @@ export const memoryOpenVikingConfigSchema = {
       peer_role: peerRole,
       peer_prefix: peerPrefix,
       apiKey: rawApiKey ? resolveEnvVars(rawApiKey) : "",
+      headers: toStringRecord(cfg.headers, "openviking config headers"),
       accountId,
       userId,
       targetUri: typeof cfg.targetUri === "string" ? cfg.targetUri : DEFAULT_TARGET_URI,
@@ -510,9 +541,9 @@ export const memoryOpenVikingConfigSchema = {
           : DEFAULT_RECALL_PREFER_ABSTRACT,
       recallMaxInjectedChars,
       recallTokenBudget: recallMaxInjectedChars,
-      commitTokenThreshold: Math.max(
+      commitTokenThresholdRatio: Math.max(
         0,
-        Math.min(100_000, Math.floor(toNumber(cfg.commitTokenThreshold, DEFAULT_COMMIT_TOKEN_THRESHOLD))),
+        Math.min(1, toNumber(cfg.commitTokenThresholdRatio, DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO)),
       ),
       commitKeepRecentCount: Math.max(
         0,
@@ -649,6 +680,11 @@ export const memoryOpenVikingConfigSchema = {
       placeholder: "${OPENVIKING_API_KEY}",
       help: "Optional API key for OpenViking server",
     },
+    headers: {
+      label: "Headers",
+      advanced: true,
+      help: "Optional HTTP headers merged into every OpenViking request.",
+    },
     accountId: {
       label: "Account ID",
       placeholder: "(derived from API key)",
@@ -747,11 +783,11 @@ export const memoryOpenVikingConfigSchema = {
       help: "Completely bypass OpenViking for matching session keys. Use * within one segment and ** across segments.",
       advanced: true,
     },
-    commitTokenThreshold: {
-      label: "Commit Token Threshold",
-      placeholder: String(DEFAULT_COMMIT_TOKEN_THRESHOLD),
+    commitTokenThresholdRatio: {
+      label: "Commit Token Threshold Ratio",
+      placeholder: String(DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO),
       advanced: true,
-      help: "Minimum estimated pending tokens before auto-commit triggers. Set to 0 to commit every turn.",
+      help: "Auto-commit triggers once estimated pending tokens reach this fraction (0-1) of the model context window (e.g. 0.5 = 50%). Set to 0 to commit every turn.",
     },
     commitKeepRecentCount: {
       label: "Commit Keep Recent Count",

package/context-engine.ts

@@ -370,12 +370,14 @@ export function createMemoryOpenVikingContextEngine(params: {
     },
 
     async afterTurn(afterTurnParams): Promise<void> {
+      const tokenBudget = validTokenBudget(afterTurnParams.tokenBudget) ?? 128_000;
       await afterTurnOpenVikingSession({
         sessionId: afterTurnParams.sessionId,
         sessionKey: resolveSessionKey(afterTurnParams),
         messages: afterTurnParams.messages,
         prePromptMessageCount: afterTurnParams.prePromptMessageCount,
         isHeartbeat: afterTurnParams.isHeartbeat,
+        tokenBudget,
         runtimeContext: afterTurnParams.runtimeContext,
         cfg,
         getClient,

package/dist/auto-recall.js

@@ -3,7 +3,6 @@ import { quickRecallPrecheck, withTimeout } from "./process-manager.js";
 import { resolveRecallSearchPlan, } from "./registries/recall-resource-types.js";
 import { sanitizeUserTextForCapture } from "./text-utils.js";
 import { estimateTextTokens } from "./token-estimator.js";
-const AUTO_RECALL_TIMEOUT_MS = 5_000;
 const RECALL_QUERY_MAX_CHARS = 4_000;
 export const AUTO_RECALL_SOURCE_MARKER = "Source: openviking-auto-recall";
 const WRITE_OR_EFFECT_RE = /\b(write|edit|modify|delete|remove|migrate|deploy|release|publish|configure|patch)\b|写|改|修改|删除|迁移|部署|发布|配置|打补丁/i;
@@ -359,5 +358,5 @@ export async function buildAutoRecallContext(params) {
         verbose?.(`openviking: inject-detail ${toJsonLog({ count: memories.length, memories: summarizeInjectionMemories(memories) })}`);
         await recordTrace(memories.slice(0, memoryLines.length), memoryLines.length, estimatedTokens);
         return { block, memoryCount: memoryLines.length, estimatedTokens };
-    })(), AUTO_RECALL_TIMEOUT_MS, "openviking: auto-recall search timeout");
+    })(), cfg.autoRecallTimeoutMs, "openviking: auto-recall search timeout");
 }

package/dist/client.js

@@ -51,6 +51,7 @@ export class OpenVikingClient {
     userId;
     routingDebugLog;
     transport;
+    configuredHeaders;
     now;
     sleep;
     resourcePackager;
@@ -70,6 +71,7 @@ export class OpenVikingClient {
             ? optionsOrLegacyUserScope
             : (legacyOptions ?? {});
         this.transport = options.transport ?? defaultHttpTransport;
+        this.configuredHeaders = options.headers ?? {};
         this.now = options.now ?? Date.now;
         this.sleep = options.sleep ?? sleep;
         this.resourcePackager = options.resourcePackager ?? defaultResourcePackager;
@@ -131,6 +133,11 @@ export class OpenVikingClient {
             if (actorPeerHeader) {
                 headers.set("X-OpenViking-Actor-Peer", actorPeerHeader);
             }
+            for (const [key, value] of Object.entries(this.configuredHeaders)) {
+                if (key && typeof value === "string" && value.trim()) {
+                    headers.set(key, value);
+                }
+            }
             if (init.body && !(init.body instanceof FormData) && !headers.has("Content-Type")) {
                 headers.set("Content-Type", "application/json");
             }
@@ -387,19 +394,19 @@ export class OpenVikingClient {
             await this.resourcePackager.cleanup(packagedSource);
         }
     }
-    async addSessionMessage(sessionId, role, parts, actorPeerId, createdAt, roleId) {
+    async addSessionMessage(sessionId, role, parts, actorPeerId, createdAt, peerId) {
         const body = { role, parts };
         if (createdAt) {
             body.created_at = createdAt;
         }
-        if (roleId) {
-            body.role_id = roleId;
+        if (peerId) {
+            body.peer_id = peerId;
         }
         await this.emitRoutingDebug("session message POST (with parts)", {
             path: `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
             sessionId,
             role,
-            role_id: roleId ?? null,
+            peer_id: peerId ?? null,
             partCount: parts.length,
             created_at: createdAt ?? null,
         }, actorPeerId);

package/dist/commands/setup.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { getEnv } from "../runtime-utils.js";
+import { cleanOpenVikingRequestHeaders, resolveOpenVikingRequestHeaders, } from "../request-headers.js";
 const HOME = os.homedir();
 const OPENCLAW_DIR = getEnv("OPENCLAW_STATE_DIR") || path.join(HOME, ".openclaw");
 const DEFAULT_REMOTE_URL = "http://127.0.0.1:1933";
@@ -55,6 +56,7 @@ const PLUGIN_VERSION = readPluginVersion();
 const { min: COMPATIBLE_SERVER_MIN, max: COMPATIBLE_SERVER_MAX } = readCompatRangeFromManifest();
 const CONFIG_KEYS_TO_PRESERVE = [
     "targetUri",
+    "headers",
     "timeoutMs",
     "autoCapture",
     "captureMode",
@@ -68,7 +70,7 @@ const CONFIG_KEYS_TO_PRESERVE = [
     "recallMaxContentChars",
     "recallPreferAbstract",
     "recallTokenBudget",
-    "commitTokenThreshold",
+    "commitTokenThresholdRatio",
     "commitKeepRecentCount",
     "bypassSessionPatterns",
     "emitStandardDiagnostics",
@@ -84,6 +86,10 @@ function maskKey(key) {
         return "****";
     return `${key.slice(0, 4)}...${key.slice(-4)}`;
 }
+function nonEmptyOpenVikingRequestHeaders(value) {
+    const headers = cleanOpenVikingRequestHeaders(value);
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
 function isValidPeerPrefixInput(value) {
     const trimmed = value.trim();
     return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);
@@ -234,14 +240,17 @@ function formatCompatRange() {
         return `<= ${COMPATIBLE_SERVER_MAX}`;
     return "any";
 }
-async function probeApiKeyType(baseUrl, apiKey) {
+async function probeApiKeyType(baseUrl, apiKey, configuredHeaders) {
     if (!apiKey)
         return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 10_000);
     const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
     try {
-        const headers = { "X-API-Key": apiKey };
+        const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
+        const headers = {};
+        headers["X-API-Key"] = apiKey;
+        Object.assign(headers, configuredRequestHeaders);
         const response = await fetch(sessionsUrl, {
             headers,
             signal: controller.signal,
@@ -278,6 +287,7 @@ async function probeApiKeyType(baseUrl, apiKey) {
                     "X-API-Key": apiKey,
                     "X-OpenViking-Account": "__probe__",
                     "X-OpenViking-User": "__probe__",
+                    ...configuredRequestHeaders,
                 };
                 const probe2 = await fetch(sessionsUrl, {
                     headers: probeHeaders,
@@ -307,13 +317,16 @@ async function probeApiKeyType(baseUrl, apiKey) {
         clearTimeout(timeoutId);
     }
 }
-async function checkServiceHealth(baseUrl, apiKey) {
+async function checkServiceHealth(baseUrl, apiKey, configuredHeaders) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 10_000);
     try {
+        const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
         const headers = {};
-        if (apiKey)
+        if (apiKey) {
             headers["X-API-Key"] = apiKey;
+        }
+        Object.assign(headers, configuredRequestHeaders);
         const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/health`, {
             headers,
             signal: controller.signal,
@@ -602,8 +615,9 @@ function printCompatibilityWarning(zh, health) {
 async function runRemoteCheck(zh, existing) {
     const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
     const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
+    const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
     console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-    const health = await checkServiceHealth(baseUrl, apiKey);
+    const health = await checkServiceHealth(baseUrl, apiKey, headers);
     if (health.ok) {
         const ver = health.version ? ` (version: ${health.version})` : "";
         console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -771,8 +785,9 @@ async function getStatus(configPath) {
     }
     const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
     const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
-    const health = await checkServiceHealth(baseUrl, apiKey);
-    const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+    const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
+    const health = await checkServiceHealth(baseUrl, apiKey, headers);
+    const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey, headers) : undefined;
     const peerPrefix = resolveExistingPeerPrefix(existing);
     return {
         configured: true,
@@ -858,13 +873,14 @@ async function setupRemote(zh, configPath, existing, q) {
     const defaultApiKey = existing?.apiKey ? String(existing.apiKey) : "";
     const defaultPeerRole = resolveExistingPeerRole(existing);
     const defaultPeerPrefix = resolveExistingPeerPrefix(existing);
+    const headers = nonEmptyOpenVikingRequestHeaders(existing?.headers);
     const baseUrl = await q(tr(zh, "OpenViking server URL", "OpenViking 服务器地址"), defaultUrl);
     const apiKey = await q(tr(zh, "API Key (optional)", "API Key（可选）"), defaultApiKey);
     let accountId = existing?.accountId ? String(existing.accountId) : "";
     let userId = existing?.userId ? String(existing.userId) : "";
     if (apiKey) {
         console.log(tr(zh, "  Detecting API key type...", "  正在检测 API Key 类型..."));
-        const probe = await probeApiKeyType(baseUrl, apiKey);
+        const probe = await probeApiKeyType(baseUrl, apiKey, headers);
         if (probe.keyType === "root_key") {
             console.log(tr(zh, "  ⚠ Root API key detected. accountId and userId are required.", "  ⚠ 检测到 Root API Key，需要提供 accountId 和 userId。"));
             accountId = await q(tr(zh, "Account ID (required for root key)", "Account ID（root key 必填）"), accountId);
@@ -880,7 +896,7 @@ async function setupRemote(zh, configPath, existing, q) {
         : "";
     console.log("");
     console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-    const health = await checkServiceHealth(baseUrl, apiKey || undefined);
+    const health = await checkServiceHealth(baseUrl, apiKey || undefined, headers);
     if (health.ok) {
         const ver = health.version ? ` (version: ${health.version})` : "";
         console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);