Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
import * as fs from "node:fs";
import * as os from "node:os";
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,
type OpenVikingRequestHeaders,
} from "../request-headers.js";
import {
createSetupNetworkProbes,
type SetupApiKeyProbeResult,
type SetupHealthResult,
} from "../services/setup/probe-service.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";
function findPluginPackageRoot(fromDir = path.dirname(fileURLToPath(import.meta.url))): string | null {
let current = path.resolve(fromDir);
for (let depth = 0; depth < 5; depth += 1) {
if (
fs.existsSync(path.join(current, "package.json")) &&
fs.existsSync(path.join(current, "openclaw.plugin.json"))
) {
return current;
}
const parent = path.dirname(current);
if (parent === current) break;
current = parent;
}
return null;
}
function readPluginVersion(): string {
try {
const packageRoot = findPluginPackageRoot();
if (!packageRoot) return "unknown";
const pkgPath = path.join(packageRoot, "package.json");
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
return String(pkg.version ?? "unknown");
} catch {
return "unknown";
}
}
function readCompatRangeFromManifest(): { min: string; max: string } {
try {
const packageRoot = findPluginPackageRoot();
if (!packageRoot) return { min: "", max: "" };
const manifestPath = path.join(packageRoot, "install-manifest.json");
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
const compat = manifest?.compatibility ?? {};
return {
min: String(compat.minOpenvikingVersion ?? ""),
max: String(compat.maxOpenvikingVersion ?? ""),
};
} catch {
return { min: "", max: "" };
}
}
const PLUGIN_VERSION = readPluginVersion();
const { min: COMPATIBLE_SERVER_MIN, max: COMPATIBLE_SERVER_MAX } = readCompatRangeFromManifest();
const CONFIG_KEYS_TO_PRESERVE = [
"contextManagementMode",
"targetUri",
"headers",
"timeoutMs",
"autoCapture",
"captureMode",
"captureMaxLength",
"autoRecall",
"recallResources",
"recallTargetTypes",
"recallLimit",
"recallScoreThreshold",
"recallMaxInjectedChars",
"recallMaxContentChars",
"recallPreferAbstract",
"recallTokenBudget",
"commitTokenThresholdRatio",
"commitRetentionMode",
"commitKeepRecentCount",
"bypassSessionPatterns",
"emitStandardDiagnostics",
"logFindRequests",
] as const;
type PeerRole = "none" | "assistant" | "sender";
const DEFAULT_SETUP_PEER_ROLE: PeerRole = "none";
type RecallTargetType = "resource" | "user" | "agent";
const ALLOWED_RECALL_TARGET_TYPES = ["resource", "user", "agent"] as const;
type CommandProgram = {
command: (name: string) => CommandBuilder;
};
type CommandBuilder = {
description: (desc: string) => CommandBuilder;
option: (flags: string, desc: string) => CommandBuilder;
command: (name: string) => CommandBuilder;
action: (fn: (...args: unknown[]) => void | Promise<void>) => CommandBuilder;
};
type RegisterCliArgs = {
program: CommandProgram;
};
function tr(langZh: boolean, en: string, zh: string): string {
return langZh ? zh : en;
}
function maskKey(key: string): string {
if (key.length <= 8) return "****";
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);
}
function normalizePeerRole(value: unknown): PeerRole | undefined {
if (typeof value !== "string") return undefined;
const role = value.trim().toLowerCase();
if (role === "person") return "sender";
if (role === "none" || role === "assistant" || role === "sender") return role;
return undefined;
}
// `person` survives only in existing configs; setup input must say `sender`.
function normalizePeerRoleInput(value: unknown): PeerRole | undefined {
if (typeof value === "string" && value.trim().toLowerCase() === "person") return undefined;
return normalizePeerRole(value);
}
function resolveExistingPeerRole(existing: Record<string, unknown> | null | undefined): PeerRole {
const explicit = normalizePeerRole(existing?.peer_role);
if (explicit) return explicit;
return DEFAULT_SETUP_PEER_ROLE;
}
function resolveExistingPeerPrefix(existing: Record<string, unknown> | null | undefined): string {
const value = existing?.peer_prefix;
if (typeof value !== "string" || !value.trim()) return "";
const trimmed = value.trim();
return trimmed === "default" ? "" : trimmed;
}
function resolveSetupPeerRole(value: unknown): PeerRole {
if (value === undefined) return DEFAULT_SETUP_PEER_ROLE;
const role = normalizePeerRoleInput(value);
if (role) return role;
throw new Error('peer_role must be "none", "assistant", or "sender" ("person" was renamed to "sender")');
}
function normalizeSetupRecallTargetTypes(value: unknown): RecallTargetType[] | undefined {
if (value === undefined || value === null || value === "") {
return undefined;
}
const entries = Array.isArray(value)
? value
: typeof value === "string"
? value.split(/[,\n]/)
: [];
const seen = new Set<RecallTargetType>();
const normalized: RecallTargetType[] = [];
const unknown: string[] = [];
for (const raw of entries) {
if (typeof raw !== "string") {
continue;
}
const entry = raw.trim();
if (!entry) {
continue;
}
if ((ALLOWED_RECALL_TARGET_TYPES as readonly string[]).includes(entry)) {
const typed = entry as RecallTargetType;
if (!seen.has(typed)) {
seen.add(typed);
normalized.push(typed);
}
} else {
unknown.push(entry);
}
}
if (unknown.length > 0) {
throw new Error(`recall-target-types contains unknown resource types: ${unknown.join(", ")}`);
}
return normalized.length > 0 ? normalized : undefined;
}
function preserveCurrentConfig(existing: Record<string, unknown> | null | undefined) {
const config: Record<string, unknown> = {};
if (!existing) {
return config;
}
for (const key of CONFIG_KEYS_TO_PRESERVE) {
if (key in existing) {
config[key] = existing[key];
}
}
return config;
}
async function askPeerRole(
zh: boolean,
q: (prompt: string, def?: string) => Promise<string>,
defaultValue: PeerRole,
): Promise<PeerRole> {
console.log(
` ${tr(
zh,
"Memory scope — none (default): viking://user/<user_id>/memories, shared across all conversations; " +
"assistant: viking://user/<user_id>/peers/<assistant_id>/memories; " +
"sender: viking://user/<user_id>/peers/<sender_id>/memories.",
"记忆归属 —— none(默认):viking://user/<user_id>/memories,所有对话共享;" +
"assistant:viking://user/<user_id>/peers/<assistant_id>/memories;" +
"sender:viking://user/<user_id>/peers/<sender_id>/memories。",
)}`,
);
while (true) {
const value = await q(
tr(zh, "Memory scope (none/assistant/sender)", "记忆归属(none/assistant/sender)"),
defaultValue,
);
const role = normalizePeerRoleInput(value);
if (role) return role;
console.log(
` ✗ ${tr(
zh,
'Memory scope must be "none", "assistant", or "sender" ("person" was renamed to "sender").',
'记忆归属必须是 "none"、"assistant" 或 "sender"("person" 已更名为 "sender")。',
)}`,
);
}
}
async function askPeerPrefix(
zh: boolean,
q: (prompt: string, def?: string) => Promise<string>,
defaultValue: string,
): Promise<string> {
while (true) {
const value = (await q(
tr(zh, "Peer Prefix (optional)", "Peer Prefix(可选)"),
defaultValue,
)).trim();
if (isValidPeerPrefixInput(value)) {
return value;
}
console.log(
` ✗ ${tr(
zh,
"Peer Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",
"Peer Prefix 只能包含字母、数字、下划线和连字符,或留空。",
)}`,
);
}
}
function ask(rl: readline.Interface, prompt: string, defaultValue = ""): Promise<string> {
const suffix = defaultValue ? ` [${defaultValue}]` : "";
return new Promise((resolve) => {
rl.question(`${prompt}${suffix}: `, (answer) => {
resolve((answer ?? "").trim() || defaultValue);
});
});
}
type VersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";
type HealthResult = SetupHealthResult;
function parseVersionTuple(v: string): number[] | null {
const cleaned = v.replace(/^v/i, "").split("-")[0];
const parts = cleaned.split(".").map(Number);
if (parts.some(isNaN)) return null;
return parts;
}
function compareVersions(a: number[], b: number[]): number {
const len = Math.max(a.length, b.length);
for (let i = 0; i < len; i++) {
const diff = (a[i] ?? 0) - (b[i] ?? 0);
if (diff !== 0) return diff;
}
return 0;
}
function checkVersionCompatibility(serverVersion: string): VersionCompatibility {
if (!serverVersion) return "unknown";
const sv = parseVersionTuple(serverVersion);
if (!sv) return "unknown";
if (COMPATIBLE_SERVER_MIN) {
const minV = parseVersionTuple(COMPATIBLE_SERVER_MIN);
if (minV && compareVersions(sv, minV) < 0) return "server_too_old";
}
if (COMPATIBLE_SERVER_MAX) {
const maxV = parseVersionTuple(COMPATIBLE_SERVER_MAX);
if (maxV && compareVersions(sv, maxV) > 0) return "server_too_new";
}
return "compatible";
}
function formatCompatRange(): string {
if (COMPATIBLE_SERVER_MIN && COMPATIBLE_SERVER_MAX) return `${COMPATIBLE_SERVER_MIN} ~ ${COMPATIBLE_SERVER_MAX}`;
if (COMPATIBLE_SERVER_MIN) return `>= ${COMPATIBLE_SERVER_MIN}`;
if (COMPATIBLE_SERVER_MAX) return `<= ${COMPATIBLE_SERVER_MAX}`;
return "any";
}
type ApiKeyProbeResult = SetupApiKeyProbeResult;
const setupProbes = createSetupNetworkProbes({
pluginVersion: PLUGIN_VERSION,
compatRange: formatCompatRange(),
checkVersionCompatibility,
});
function readOpenClawConfig(configPath: string): Record<string, unknown> {
if (!fs.existsSync(configPath)) return {};
try {
return JSON.parse(fs.readFileSync(configPath, "utf-8"));
} catch {
return {};
}
}
function getExistingPluginConfig(config: Record<string, unknown>): Record<string, unknown> | null {
const plugins = config.plugins as Record<string, unknown> | undefined;
if (!plugins) return null;
const entries = plugins.entries as Record<string, unknown> | undefined;
if (!entries) return null;
const entry = entries.openviking as Record<string, unknown> | undefined;
if (!entry) return null;
const cfg = entry.config as Record<string, unknown> | undefined;
return cfg && cfg.mode ? cfg : null;
}
function backupConfig(configPath: string): string | null {
if (!fs.existsSync(configPath)) return null;
const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
const backupPath = `${configPath}.bak.${timestamp}`;
try {
fs.copyFileSync(configPath, backupPath);
return backupPath;
} catch {
return null;
}
}
function ensureInstallRecord(plugins: Record<string, unknown>): void {
const installs = plugins.installs as Record<string, unknown> | undefined;
if (installs && typeof installs === "object") {
delete installs.openviking;
}
if (!plugins.allow) plugins.allow = [];
const allow = plugins.allow as string[];
if (!allow.includes("openviking")) {
allow.push("openviking");
}
}
function writeConfig(
configPath: string,
pluginCfg: Record<string, unknown>,
): void {
const configDir = path.dirname(configPath);
if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });
backupConfig(configPath);
const config = readOpenClawConfig(configPath);
if (!config.plugins) config.plugins = {};
const plugins = config.plugins as Record<string, unknown>;
if (!plugins.entries) plugins.entries = {};
const entries = plugins.entries as Record<string, unknown>;
const existingEntry = (entries.openviking as Record<string, unknown>) ?? {};
entries.openviking = { ...existingEntry, config: pluginCfg };
ensureInstallRecord(plugins);
fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
}
function detectLangZh(options: Record<string, unknown>): boolean {
if (options.zh) return true;
const lang = getEnv("LANG") || getEnv("LC_ALL") || "";
return /^zh/i.test(lang);
}
function isLegacyLocalMode(existing: Record<string, unknown>): boolean {
const mode = existing.mode;
return mode !== "remote";
}
type SetupResult = {
success: boolean;
action: "configured" | "existing" | "error" | "slot_blocked";
config?: {
mode: string;
baseUrl: string;
apiKey?: string;
peer_role?: PeerRole;
peer_prefix?: string;
accountId?: string;
userId?: string;
recallTargetTypes?: string[];
};
health?: HealthResult;
keyProbe?: ApiKeyProbeResult;
slot: SlotActivationResult;
error?: string;
};
function setExitCodeOnFailure(result: { success: boolean }): void {
if (!result.success) {
process.exitCode = 1;
}
}
type StatusResult = {
configured: boolean;
config?: {
mode: string;
baseUrl: string;
hasApiKey: boolean;
peer_role: PeerRole;
peer_prefix?: string;
hasAccountId: boolean;
hasUserId: boolean;
};
health?: HealthResult;
keyProbe?: ApiKeyProbeResult;
slotActive: boolean;
};
type SlotActivationResult = {
activated: boolean;
previousOwner?: string;
replaced: boolean;
};
function activateContextEngineSlot(configPath: string, force = false): SlotActivationResult {
const config = readOpenClawConfig(configPath);
if (!config.plugins) config.plugins = {};
const plugins = config.plugins as Record<string, unknown>;
if (!plugins.slots) plugins.slots = {};
const slots = plugins.slots as Record<string, unknown>;
const current = slots.contextEngine as string | undefined;
if (current === "openviking") return { activated: false, replaced: false };
if (current && current !== "openviking" && !force) {
return { activated: false, previousOwner: current, replaced: false };
}
slots.contextEngine = "openviking";
fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
return { activated: true, previousOwner: current || undefined, replaced: !!current };
}
function isContextEngineSlotActive(configPath: string): boolean {
const config = readOpenClawConfig(configPath);
const plugins = config.plugins as Record<string, unknown> | undefined;
if (!plugins) return false;
const slots = plugins.slots as Record<string, unknown> | undefined;
return slots?.contextEngine === "openviking";
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function registerSetupCli(api: any): void {
if (!api.registerCli) {
api.logger.info("openviking: registerCli not available, setup command skipped");
return;
}
api.registerCli(
({ program }: RegisterCliArgs) => {
const ovCmd = program.command("openviking").description("OpenViking plugin commands");
ovCmd
.command("setup")
.description("Setup OpenViking plugin (supports both interactive and non-interactive modes)")
.option("--reconfigure", "Force re-entry of all configuration values")
.option("--zh", "Chinese prompts")
.option("--base-url <url>", "OpenViking server URL (enables non-interactive mode)")
.option("--api-key <key>", "API key for authentication")
.option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender)")
.option("--peer-prefix <prefix>", "Prefix for assistant peer_id values")
.option("--account-id <id>", "Account ID (required for root API keys)")
.option("--user-id <id>", "User ID (required for root API keys)")
.option("--recall-target-types <types>", "Comma-separated recall target types: user, agent, resource")
.option("--allow-offline", "Allow config write even if server is unreachable")
.option("--force-slot", "Replace existing contextEngine slot even if owned by another plugin")
.option("--json", "Output result as JSON (machine-readable)")
.action(async (...args: unknown[]) => {
const options = (args[0] ?? {}) as Record<string, unknown>;
const {
reconfigure, zh: zhOpt, baseUrl, apiKey, peerRole, peerPrefix,
accountId, userId, recallTargetTypes, allowOffline, forceSlot, json: jsonOpt,
} = options as {
reconfigure?: boolean; zh?: boolean; baseUrl?: string;
apiKey?: string; peerRole?: string; peerPrefix?: string; accountId?: string;
userId?: string; recallTargetTypes?: string; allowOffline?: boolean; forceSlot?: boolean;
json?: boolean;
};
const zh = detectLangZh(options);
const configPath = path.join(OPENCLAW_DIR, "openclaw.json");
const jsonMode = !!jsonOpt;
const nonInteractive = !!baseUrl;
if (nonInteractive) {
const result = await setupNonInteractive(configPath, {
baseUrl: baseUrl!,
apiKey,
peerRole,
peerPrefix,
accountId,
userId,
recallTargetTypes: normalizeSetupRecallTargetTypes(recallTargetTypes),
allowOffline: !!allowOffline,
forceSlot: !!forceSlot,
});
if (jsonMode) {
console.log(JSON.stringify(result, null, 2));
} else {
printSetupResult(zh, result);
}
setExitCodeOnFailure(result);
return;
}
if (jsonMode && !nonInteractive) {
const result: SetupResult = {
success: false,
action: "error",
slot: { activated: false, replaced: false },
error: "--json requires --base-url for non-interactive mode",
};
console.log(JSON.stringify(result, null, 2));
setExitCodeOnFailure(result);
return;
}
console.log("");
console.log(`🦣 ${tr(zh, "OpenViking Plugin Setup", "OpenViking 插件配置向导")}`);
console.log("");
const config = readOpenClawConfig(configPath);
const existing = getExistingPluginConfig(config);
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const q = (prompt: string, def = "") => ask(rl, prompt, def);
try {
if (existing && !reconfigure) {
if (isLegacyLocalMode(existing)) {
console.log(tr(
zh,
"Existing configuration uses local mode, which is no longer supported.",
"当前配置为本地模式,已不再支持。",
));
console.log(tr(
zh,
"Run `openclaw openviking setup --reconfigure` to configure a remote OpenViking server.",
"请运行 `openclaw openviking setup --reconfigure` 以配置远程 OpenViking 服务。",
));
console.log("");
return;
}
console.log(tr(zh, "Existing configuration found:", "已找到现有配置:"));
console.log(` mode: ${existing.mode}`);
console.log(` baseUrl: ${existing.baseUrl ?? DEFAULT_REMOTE_URL}`);
if (existing.apiKey) console.log(` apiKey: ${maskKey(String(existing.apiKey))}`);
console.log(` peer_role: ${resolveExistingPeerRole(existing)}`);
const existingPeerPrefix = resolveExistingPeerPrefix(existing);
if (existingPeerPrefix) console.log(` peer_prefix: ${existingPeerPrefix}`);
console.log("");
console.log(tr(
zh,
"Press Enter to keep existing values, or use --reconfigure to change.",
"按 Enter 保留现有配置,或使用 --reconfigure 重新配置。",
));
console.log("");
console.log(tr(zh, "✓ Using existing configuration", "✓ 使用现有配置"));
console.log("");
await runRemoteCheck(zh, existing);
const slotResult = activateContextEngineSlot(configPath);
printSlotResult(zh, slotResult);
console.log(tr(zh,
"✓ Plugin is ready. Run `openclaw gateway --force` to activate.",
"✓ 插件已就绪。运行 `openclaw gateway --force` 以激活。",
));
console.log("");
return;
}
if (existing && options.reconfigure) {
console.log(tr(zh, "Existing configuration found:", "已找到现有配置:"));
if (isLegacyLocalMode(existing)) {
console.log(tr(zh,
"(Previous local-mode settings will be replaced with remote settings.)",
"(将用远程模式设置替换此前的本地模式配置。)",
));
} else {
console.log(` mode: ${existing.mode}`);
console.log(` baseUrl: ${existing.baseUrl ?? DEFAULT_REMOTE_URL}`);
if (existing.apiKey) console.log(` apiKey: ${maskKey(String(existing.apiKey))}`);
}
console.log("");
console.log(tr(zh, "Reconfiguring...", "重新配置中..."));
console.log("");
} else {
console.log(tr(zh,
"No existing configuration found. Starting setup wizard.",
"未找到现有配置,开始配置向导。",
));
console.log("");
}
await setupRemote(zh, configPath, existing, q);
} finally {
rl.close();
}
});
ovCmd
.command("status")
.description("Show current OpenViking plugin status and connectivity")
.option("--zh", "Chinese prompts")
.option("--json", "Output result as JSON (machine-readable)")
.action(async (...args: unknown[]) => {
const options = (args[0] ?? {}) as Record<string, unknown>;
const { zh: zhOpt, json: jsonOpt } = options as { zh?: boolean; json?: boolean };
const zh = detectLangZh(options);
const configPath = path.join(OPENCLAW_DIR, "openclaw.json");
const jsonMode = !!jsonOpt;
const result = await getStatus(configPath);
if (jsonMode) {
console.log(JSON.stringify(result, null, 2));
return;
}
printStatus(zh, result);
});
},
{ commands: ["openviking"] },
);
}
function printCompatibilityWarning(zh: boolean, health: HealthResult): void {
if (health.compatibility === "server_too_old") {
console.log(` ⚠ ${tr(zh,
`Server version ${health.version} is older than recommended (${health.compatRange}). Some features may not work. Please upgrade OpenViking server.`,
`服务端版本 ${health.version} 低于推荐范围(${health.compatRange})。部分功能可能不可用,请升级 OpenViking 服务端。`,
)}`);
} else if (health.compatibility === "server_too_new") {
console.log(` ⚠ ${tr(zh,
`Server version ${health.version} is newer than supported (${health.compatRange}). Please upgrade the OpenViking plugin.`,
`服务端版本 ${health.version} 高于插件支持范围(${health.compatRange})。请升级 OpenViking 插件。`,
)}`);
} else if (health.compatibility === "unknown" && health.ok) {
console.log(` ⚠ ${tr(zh,
"Could not determine server version. Compatibility check skipped.",
"无法获取服务端版本,已跳过兼容性检查。",
)}`);
}
}
async function runRemoteCheck(
zh: boolean,
existing: Record<string, unknown>,
): 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 setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
if (health.ok) {
const ver = health.version ? ` (version: ${health.version})` : "";
console.log(` ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
printCompatibilityWarning(zh, health);
} else {
console.log(` ✗ ${tr(zh, `Connection failed: ${health.error}`, `连接失败: ${health.error}`)}`);
}
console.log("");
}
async function setupNonInteractive(
configPath: string,
params: {
baseUrl: string;
apiKey?: string;
peerRole?: string;
peerPrefix?: string;
accountId?: string;
userId?: string;
recallTargetTypes?: string[];
allowOffline?: boolean;
forceSlot?: boolean;
},
): Promise<SetupResult> {
try {
const { baseUrl, apiKey, peerPrefix, accountId, userId, recallTargetTypes, allowOffline, forceSlot } = params;
const resolvedPeerRole = resolveSetupPeerRole(params.peerRole);
const resolvedPeerPrefix = (peerPrefix ?? "").trim();
if (!isValidPeerPrefixInput(resolvedPeerPrefix)) {
throw new Error("peer_prefix may only contain letters, digits, underscores, and hyphens, or be empty");
}
// Phase 1: validate connectivity and key type BEFORE writing config
const health = await setupProbes.checkServiceHealth(baseUrl, apiKey);
if (!health.ok && !allowOffline) {
return {
success: false,
action: "error",
config: { mode: "remote", baseUrl },
health,
slot: { activated: false, replaced: false },
error: `Server unreachable: ${health.error}. Use --allow-offline to save config anyway.`,
};
}
const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey) : undefined;
if (keyProbe?.keyType === "root_key" && (!accountId || !userId)) {
const missing: string[] = [];
if (!accountId) missing.push("--account-id");
if (!userId) missing.push("--user-id");
return {
success: false,
action: "error",
config: {
mode: "remote",
baseUrl,
...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
},
health,
keyProbe,
slot: { activated: false, replaced: false },
error: `Root API key detected. Missing: ${missing.join(", ")}. Re-run with: ${missing.map(f => `${f} <value>`).join(" ")}`,
};
}
// Phase 2: all checks passed (or --allow-offline), write config and activate slot
const pluginCfg: Record<string, unknown> = { mode: "remote", baseUrl };
if (apiKey) pluginCfg.apiKey = apiKey;
pluginCfg.peer_role = resolvedPeerRole;
if (resolvedPeerPrefix) pluginCfg.peer_prefix = resolvedPeerPrefix;
if (accountId) pluginCfg.accountId = accountId;
if (userId) pluginCfg.userId = userId;
if (recallTargetTypes && recallTargetTypes.length > 0) {
pluginCfg.recallTargetTypes = recallTargetTypes;
}
writeConfig(configPath, pluginCfg);
const slot = activateContextEngineSlot(configPath, !!forceSlot);
if (!slot.activated && slot.previousOwner) {
return {
success: false,
action: "slot_blocked",
config: {
mode: "remote",
baseUrl,
...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
peer_role: resolvedPeerRole,
...(resolvedPeerPrefix ? { peer_prefix: resolvedPeerPrefix } : {}),
...(accountId ? { accountId } : {}),
...(userId ? { userId } : {}),
...(recallTargetTypes && recallTargetTypes.length > 0 ? { recallTargetTypes } : {}),
},
health,
keyProbe,
slot,
error: `contextEngine slot is owned by "${slot.previousOwner}". Config was saved but slot was NOT changed. Use --force-slot to replace.`,
};
}
return {
success: true,
action: "configured",
config: {
mode: "remote",
baseUrl,
...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
peer_role: resolvedPeerRole,
...(resolvedPeerPrefix ? { peer_prefix: resolvedPeerPrefix } : {}),
...(accountId ? { accountId } : {}),
...(userId ? { userId } : {}),
...(recallTargetTypes && recallTargetTypes.length > 0 ? { recallTargetTypes } : {}),
},
health,
keyProbe,
slot,
};
} catch (err) {
return {
success: false,
action: "error",
slot: { activated: false, replaced: false },
error: String(err instanceof Error ? err.message : err),
};
}
}
function printSetupResult(zh: boolean, result: SetupResult): void {
console.log("");
if (result.success) {
console.log(`🦣 ${tr(zh, "OpenViking Plugin Setup Complete", "OpenViking 插件配置完成")}`);
console.log("");
if (result.config) {
console.log(` mode: ${result.config.mode}`);
console.log(` baseUrl: ${result.config.baseUrl}`);
if (result.config.apiKey) console.log(` apiKey: ${result.config.apiKey}`);
console.log(` peer_role: ${result.config.peer_role ?? DEFAULT_SETUP_PEER_ROLE}`);
if (result.config.peer_prefix) console.log(` peer_prefix: ${result.config.peer_prefix}`);
if (result.config.accountId) console.log(` accountId: ${result.config.accountId}`);
if (result.config.userId) console.log(` userId: ${result.config.userId}`);
if (result.config.recallTargetTypes) console.log(` recallTargetTypes: ${result.config.recallTargetTypes.join(",")}`);
}
console.log("");
if (result.health?.ok) {
const ver = result.health.version ? ` (version: ${result.health.version})` : "";
console.log(` ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
printCompatibilityWarning(zh, result.health);
} else if (result.health) {
console.log(` ✗ ${tr(zh, `Connection failed: ${result.health.error}`, `连接失败: ${result.health.error}`)}`);
}
if (result.keyProbe) {
printKeyProbeWarning(zh, result.keyProbe);
}
printSlotResult(zh, result.slot);
console.log("");
console.log(tr(zh,
"Run `openclaw gateway --force` to activate the plugin.",
"运行 `openclaw gateway --force` 以激活插件。",
));
} else {
console.log(`✗ ${tr(zh, "Setup failed", "配置失败")}: ${result.error}`);
if (result.keyProbe?.keyType === "root_key") {
printKeyProbeWarning(zh, result.keyProbe);
}
}
console.log("");
}
async function getStatus(configPath: string): Promise<StatusResult> {
const config = readOpenClawConfig(configPath);
const existing = getExistingPluginConfig(config);
const slotActive = isContextEngineSlotActive(configPath);
if (!existing) {
return { configured: false, slotActive };
}
const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey, headers) : undefined;
const peerPrefix = resolveExistingPeerPrefix(existing);
return {
configured: true,
config: {
mode: String(existing.mode ?? "remote"),
baseUrl,
hasApiKey: !!existing.apiKey,
peer_role: resolveExistingPeerRole(existing),
...(peerPrefix ? { peer_prefix: peerPrefix } : {}),
hasAccountId: !!existing.accountId,
hasUserId: !!existing.userId,
},
health,
keyProbe,
slotActive,
};
}
function printSlotResult(zh: boolean, slot: SlotActivationResult): void {
if (slot.activated && slot.replaced) {
console.log(` ⚠ ${tr(zh,
`Replaced context-engine slot: ${slot.previousOwner} → openviking`,
`已替换 context-engine 插槽: ${slot.previousOwner} → openviking`,
)}`);
} else if (slot.activated) {
console.log(` ✓ ${tr(zh, "Activated context-engine slot: openviking", "已激活 context-engine 插槽: openviking")}`);
} else if (slot.previousOwner && slot.previousOwner !== "openviking") {
console.log(` ⚠ ${tr(zh,
`Context-engine slot is owned by "${slot.previousOwner}". Run: openclaw config set plugins.slots.contextEngine openviking`,
`context-engine 插槽当前由 "${slot.previousOwner}" 占用。运行: openclaw config set plugins.slots.contextEngine openviking`,
)}`);
}
}
function printKeyProbeWarning(zh: boolean, probe: ApiKeyProbeResult): void {
if (probe.keyType === "root_key") {
console.log(` ⚠ ${tr(zh,
"Root API key detected. accountId and userId are required for this key type.",
"检测到 Root API Key,此类型密钥需要提供 accountId 和 userId。",
)}`);
if (probe.needsAccountId) {
console.log(` ${tr(zh,
"→ Missing: accountId (use --account-id or set in config)",
"→ 缺少: accountId(使用 --account-id 或在配置中设置)",
)}`);
}
if (probe.needsUserId) {
console.log(` ${tr(zh,
"→ Missing: userId (use --user-id or set in config)",
"→ 缺少: userId(使用 --user-id 或在配置中设置)",
)}`);
}
}
}
function printStatus(zh: boolean, result: StatusResult): void {
console.log("");
console.log(`🦣 ${tr(zh, "OpenViking Plugin Status", "OpenViking 插件状态")}`);
console.log("");
if (!result.configured) {
console.log(` ${tr(zh, "Status: Not configured", "状态: 未配置")}`);
console.log(` ${tr(zh, "Run `openclaw openviking setup` to configure.", "运行 `openclaw openviking setup` 进行配置。")}`);
console.log("");
return;
}
console.log(` ${tr(zh, "Status: Configured", "状态: 已配置")}`);
if (result.config) {
console.log(` mode: ${result.config.mode}`);
console.log(` baseUrl: ${result.config.baseUrl}`);
console.log(` apiKey: ${result.config.hasApiKey ? "set" : "not set"}`);
console.log(` peer_role: ${result.config.peer_role}`);
if (result.config.peer_prefix) console.log(` peer_prefix: ${result.config.peer_prefix}`);
console.log(` accountId: ${result.config.hasAccountId ? "set" : "not set"}`);
console.log(` userId: ${result.config.hasUserId ? "set" : "not set"}`);
}
console.log(` slot: ${result.slotActive ? "active" : "inactive"}`);
console.log("");
if (result.health?.ok) {
const ver = result.health.version ? ` (version: ${result.health.version})` : "";
console.log(` ✓ ${tr(zh, `Server reachable${ver}`, `服务器可达${ver}`)}`);
printCompatibilityWarning(zh, result.health);
} else if (result.health) {
console.log(` ✗ ${tr(zh, `Server unreachable: ${result.health.error}`, `服务器不可达: ${result.health.error}`)}`);
}
if (result.keyProbe) {
printKeyProbeWarning(zh, result.keyProbe);
}
console.log("");
}
async function setupRemote(
zh: boolean,
configPath: string,
existing: Record<string, unknown> | null,
q: (prompt: string, def?: string) => Promise<string>,
): Promise<void> {
console.log("");
console.log(tr(zh, "── Remote Mode Configuration ──", "── 远程模式配置 ──"));
console.log("");
const defaultUrl = existing?.baseUrl && String(existing.baseUrl).trim()
? String(existing.baseUrl)
: DEFAULT_REMOTE_URL;
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 setupProbes.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);
userId = await q(tr(zh, "User ID (required for root key)", "User ID(root key 必填)"), userId);
} else if (probe.keyType === "user_key") {
console.log(tr(zh, " ✓ User key verified", " ✓ User key 已验证"));
}
}
const peerRole = await askPeerRole(zh, q, defaultPeerRole);
const peerPrefix = peerRole === "assistant"
? await askPeerPrefix(zh, q, defaultPeerPrefix)
: "";
console.log("");
console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
const health = await setupProbes.checkServiceHealth(baseUrl, apiKey || undefined, headers);
if (health.ok) {
const ver = health.version ? ` (version: ${health.version})` : "";
console.log(` ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
printCompatibilityWarning(zh, health);
} else {
console.log(` ✗ ${tr(zh, `Connection failed: ${health.error}`, `连接失败: ${health.error}`)}`);
console.log("");
console.log(tr(zh,
" The configuration will still be saved. Make sure the server is reachable\n before starting the gateway.",
" 配置仍会保存。请确保服务器在启动 gateway 前可达。",
));
}
console.log("");
const pluginCfg: Record<string, unknown> = {
...preserveCurrentConfig(existing),
mode: "remote",
baseUrl,
};
if (apiKey) pluginCfg.apiKey = apiKey;
else delete pluginCfg.apiKey;
pluginCfg.peer_role = peerRole;
if (peerPrefix) pluginCfg.peer_prefix = peerPrefix;
else delete pluginCfg.peer_prefix;
if (accountId) pluginCfg.accountId = accountId;
else delete pluginCfg.accountId;
if (userId) pluginCfg.userId = userId;
else delete pluginCfg.userId;
writeConfig(configPath, pluginCfg);
const slotResult = activateContextEngineSlot(configPath);
console.log("");
console.log(` ${tr(zh, "mode:", "模式:")} remote`);
console.log(` baseUrl: ${baseUrl}`);
if (apiKey) console.log(` apiKey: ${maskKey(apiKey)}`);
console.log(` peer_role: ${peerRole}`);
if (peerPrefix) console.log(` peer_prefix: ${peerPrefix}`);
if (accountId) console.log(` accountId: ${accountId}`);
if (userId) console.log(` userId: ${userId}`);
printSlotResult(zh, slotResult);
console.log("");
console.log(tr(zh,
"Run `openclaw gateway --force` to activate the plugin.",
"运行 `openclaw gateway --force` 以激活插件。",
));
console.log("");
}
export const __test__ = {
isLegacyLocalMode,
isValidPeerPrefixInput,
normalizePeerRole,
resolveSetupPeerRole,
normalizeSetupRecallTargetTypes,
activateContextEngineSlot,
isContextEngineSlotActive,
getStatus,
setupNonInteractive,
checkVersionCompatibility,
parseVersionTuple,
compareVersions,
ensureInstallRecord,
findPluginPackageRoot,
readCompatRangeFromManifest,
readPluginVersion,
setExitCodeOnFailure,
};