openclaw-server 0.1.0

package/src/auth.ts

@@ -0,0 +1,24 @@
+import type { Request, Response } from "express";
+import type { ServerConfig } from "./config.js";
+
+export function requireBearerAuth(req: Request, res: Response, config: ServerConfig): boolean {
+  const expected = config.apiKey.trim();
+  if (!expected) {
+    return true;
+  }
+
+  const header = req.header("authorization") ?? "";
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  const token = match?.[1]?.trim() ?? "";
+  if (token === expected) {
+    return true;
+  }
+
+  res.status(401).json({
+    error: {
+      message: "Unauthorized",
+      type: "invalid_request_error",
+    },
+  });
+  return false;
+}

package/src/better-sqlite3.d.ts

@@ -0,0 +1,17 @@
+declare module "better-sqlite3" {
+  class Statement<Result = unknown> {
+    run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+    get(...params: unknown[]): Result | undefined;
+    all(...params: unknown[]): Result[];
+  }
+
+  class Database {
+    constructor(filename: string, options?: Record<string, unknown>);
+    pragma(source: string): unknown;
+    exec(source: string): this;
+    prepare<Result = unknown>(source: string): Statement<Result>;
+    close(): void;
+  }
+
+  export default Database;
+}

package/src/config.ts

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ServerConfig = {
+  host: string;
+  port: number;
+  apiKey: string;
+  defaultModelId: string;
+  packDir: string;
+  sessionLogPath?: string;
+  streamInitialDelayMs: number;
+  streamChunkChars: number;
+  taskDbPath: string;
+  taskTimezone: string;
+  taskReminderPollMs: number;
+  debugLoggingEnabled: boolean;
+  debugPreviewChars: number;
+};
+
+const projectRoot = path.resolve(fileURLToPath(new URL("../", import.meta.url)));
+
+function readNumber(value: string | undefined, fallback: number, min: number, max: number): number {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+
+function readBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (!value?.trim()) {
+    return fallback;
+  }
+
+  return !["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}
+
+export function resolveProjectRoot(): string {
+  return projectRoot;
+}
+
+export function loadConfig(): ServerConfig {
+  const packId = process.env.OPENCLAW_SERVER_PACK_ID?.trim() || "default";
+  const explicitPackDir = process.env.OPENCLAW_SERVER_PACK_DIR?.trim();
+  const debugDefault = !process.env.VITEST && process.env.NODE_ENV !== "test";
+
+  return {
+    host: process.env.OPENCLAW_SERVER_HOST?.trim() || "127.0.0.1",
+    port: readNumber(process.env.OPENCLAW_SERVER_PORT ?? process.env.PORT, 4318, 1, 65535),
+    apiKey: process.env.OPENCLAW_SERVER_API_KEY?.trim() || "openclaw-server-dev",
+    defaultModelId: process.env.OPENCLAW_SERVER_MODEL_ID?.trim() || "default-assistant",
+    packDir: explicitPackDir || path.join(projectRoot, "packs", packId),
+    sessionLogPath: process.env.OPENCLAW_SERVER_SESSION_LOG?.trim() || undefined,
+    streamInitialDelayMs: readNumber(process.env.OPENCLAW_SERVER_STREAM_DELAY_MS, 120, 0, 5000),
+    streamChunkChars: readNumber(process.env.OPENCLAW_SERVER_STREAM_CHUNK_CHARS, 24, 4, 256),
+    taskDbPath:
+      process.env.OPENCLAW_SERVER_TASK_DB?.trim() || path.join(projectRoot, "data", "tasks.sqlite"),
+    taskTimezone: process.env.OPENCLAW_SERVER_TIMEZONE?.trim() || "Asia/Shanghai",
+    taskReminderPollMs: readNumber(process.env.OPENCLAW_SERVER_TASK_REMINDER_POLL_MS, 5000, 0, 60_000),
+    debugLoggingEnabled: readBoolean(process.env.OPENCLAW_SERVER_DEBUG_LOG, debugDefault),
+    debugPreviewChars: readNumber(process.env.OPENCLAW_SERVER_DEBUG_PREVIEW_CHARS, 120, 32, 500),
+  };
+}

package/src/core/matcher.ts

@@ -0,0 +1,214 @@
+import type { FaqDefinition, IntentDefinition } from "../types.js";
+import { normalizeFreeText } from "./normalizer.js";
+
+const EXACT_MATCH_SCORE = 1_000;
+const REGEX_MATCH_SCORE = 820;
+const MIN_INTENT_SCORE = 180;
+const MIN_FAQ_SCORE = 220;
+
+type MatchFeatures = {
+  raw: string;
+  normalized: string;
+  compact: string;
+  tokens: string[];
+  grams: string[];
+  specificity: number;
+};
+
+type CompiledIntent = {
+  definition: IntentDefinition;
+  phrases: MatchFeatures[];
+  regexes: RegExp[];
+};
+
+type CompiledFaq = {
+  definition: FaqDefinition;
+  phrases: MatchFeatures[];
+};
+
+function unique(items: string[]): string[] {
+  return [...new Set(items)];
+}
+
+function countShared(left: string[], right: string[]): number {
+  if (left.length === 0 || right.length === 0) {
+    return 0;
+  }
+  const rightSet = new Set(right);
+  let shared = 0;
+  for (const item of left) {
+    if (rightSet.has(item)) {
+      shared += 1;
+    }
+  }
+  return shared;
+}
+
+function buildCharacterGrams(token: string): string[] {
+  const chars = [...token];
+  if (chars.length < 2) {
+    return [];
+  }
+
+  const grams: string[] = [];
+  const maxGram = Math.min(3, chars.length);
+  for (let size = 2; size <= maxGram; size += 1) {
+    for (let index = 0; index <= chars.length - size; index += 1) {
+      grams.push(chars.slice(index, index + size).join(""));
+    }
+  }
+  return grams;
+}
+
+function buildFeatures(text: string): MatchFeatures {
+  const normalized = normalizeFreeText(text);
+  const tokens = unique(normalized.split(" ").filter(Boolean));
+  const compact = tokens.join("");
+  const grams = unique(tokens.flatMap((token) => buildCharacterGrams(token)));
+  return {
+    raw: text,
+    normalized,
+    compact,
+    tokens,
+    grams,
+    specificity: Math.min(90, compact.length * 8 + tokens.length * 20 + grams.length * 2),
+  };
+}
+
+function compileRegex(pattern: string): RegExp | undefined {
+  try {
+    return new RegExp(pattern, "iu");
+  } catch {
+    return undefined;
+  }
+}
+
+function isRegExp(pattern: RegExp | undefined): pattern is RegExp {
+  return pattern instanceof RegExp;
+}
+
+function coverageScore(inputTerms: string[], patternTerms: string[], weight: number): number {
+  if (inputTerms.length === 0 || patternTerms.length === 0) {
+    return 0;
+  }
+
+  const shared = countShared(patternTerms, inputTerms);
+  if (shared === 0) {
+    return 0;
+  }
+
+  const recall = shared / patternTerms.length;
+  const precision = shared / inputTerms.length;
+  const f1 = (2 * precision * recall) / (precision + recall);
+  return Math.round(weight * f1 + 80 * recall);
+}
+
+function containmentScore(input: MatchFeatures, pattern: MatchFeatures): number {
+  if (!input.compact || !pattern.compact) {
+    return 0;
+  }
+
+  if (input.normalized === pattern.normalized || input.compact === pattern.compact) {
+    return EXACT_MATCH_SCORE + pattern.specificity;
+  }
+
+  let score = 0;
+  if (pattern.compact.length >= 2 && input.compact.includes(pattern.compact)) {
+    const coverage = pattern.compact.length / input.compact.length;
+    score = Math.max(score, 460 + Math.round(180 * coverage));
+  }
+  if (input.compact.length >= 2 && pattern.compact.includes(input.compact)) {
+    const coverage = input.compact.length / pattern.compact.length;
+    score = Math.max(score, 380 + Math.round(140 * coverage));
+  }
+  return score;
+}
+
+function phraseScore(input: MatchFeatures, pattern: MatchFeatures): number {
+  const contain = containmentScore(input, pattern);
+  const tokenScore = coverageScore(input.tokens, pattern.tokens, 260);
+  const gramScore = coverageScore(input.grams, pattern.grams, 240);
+  const lexicalScore =
+    tokenScore > 0 || gramScore > 0
+      ? tokenScore + Math.round(gramScore * 0.7) + pattern.specificity
+      : 0;
+  return Math.max(contain, lexicalScore);
+}
+
+function scoreIntentMatch(input: MatchFeatures, candidate: CompiledIntent): number {
+  let score = 0;
+
+  for (const phrase of candidate.phrases) {
+    score = Math.max(score, phraseScore(input, phrase));
+  }
+
+  for (const pattern of candidate.regexes) {
+    if (pattern.test(input.raw) || pattern.test(input.normalized)) {
+      score = Math.max(score, REGEX_MATCH_SCORE);
+    }
+  }
+
+  return score > 0 ? score + candidate.definition.priority : 0;
+}
+
+function scoreFaqMatch(input: MatchFeatures, candidate: CompiledFaq): number {
+  let score = 0;
+  for (const phrase of candidate.phrases) {
+    score = Math.max(score, phraseScore(input, phrase));
+  }
+  return score > 0 ? score + candidate.definition.priority : 0;
+}
+
+export function compileIntents(intents: IntentDefinition[]): CompiledIntent[] {
+  return intents.map((definition) => ({
+    definition,
+    phrases: definition.matchAny.map((phrase) => buildFeatures(phrase)).filter((phrase) => phrase.normalized),
+    regexes: definition.regex.map((pattern) => compileRegex(pattern)).filter(isRegExp),
+  }));
+}
+
+export function compileFaqs(faqs: FaqDefinition[]): CompiledFaq[] {
+  return faqs.map((definition) => ({
+    definition,
+    phrases: definition.questionPatterns
+      .map((phrase) => buildFeatures(phrase))
+      .filter((phrase) => phrase.normalized),
+  }));
+}
+
+export function findBestIntent(
+  intents: CompiledIntent[],
+  text: string,
+): IntentDefinition | undefined {
+  const input = buildFeatures(text);
+  let bestMatch: IntentDefinition | undefined;
+  let bestScore = 0;
+
+  for (const candidate of intents) {
+    const score = scoreIntentMatch(input, candidate);
+    if (score <= bestScore) {
+      continue;
+    }
+    bestMatch = candidate.definition;
+    bestScore = score;
+  }
+
+  return bestScore >= MIN_INTENT_SCORE ? bestMatch : undefined;
+}
+
+export function findBestFaq(faqs: CompiledFaq[], text: string): FaqDefinition | undefined {
+  const input = buildFeatures(text);
+  let bestMatch: FaqDefinition | undefined;
+  let bestScore = 0;
+
+  for (const candidate of faqs) {
+    const score = scoreFaqMatch(input, candidate);
+    if (score <= bestScore) {
+      continue;
+    }
+    bestMatch = candidate.definition;
+    bestScore = score;
+  }
+
+  return bestScore >= MIN_FAQ_SCORE ? bestMatch : undefined;
+}

package/src/core/normalizer.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { normalizeFreeText, unwrapOpenClawUserText } from "./normalizer.js";
+
+describe("normalizeFreeText", () => {
+  it("normalizes mixed Chinese and English faq prompts", () => {
+    expect(normalizeFreeText("\u4f60\u662f\u771f AI \u5417")).toBe("\u4f60\u662f\u771f ai \u5417");
+    expect(normalizeFreeText("\u4f60\u662f\u771f AI \u5417\uff1f")).toBe("\u4f60\u662f\u771f ai \u5417");
+    expect(normalizeFreeText("\u4f60\u662f\u771fAI\u5417")).toBe("\u4f60\u662f\u771fai\u5417");
+  });
+
+  it("normalizes English punctuation and compatibility characters", () => {
+    expect(normalizeFreeText("Are you a real AI?")).toBe("are you a real ai");
+    expect(normalizeFreeText("models.providers.openclaw-server")).toBe(
+      "models providers openclaw server",
+    );
+    expect(normalizeFreeText("\uff21\uff29\u3000provider")).toBe("ai provider");
+  });
+});
+
+describe("unwrapOpenClawUserText", () => {
+  it("extracts the final user input from OpenClaw-wrapped content", () => {
+    const wrapped = `
+Skills store policy (operator configured): 1. For skills discovery/install/update, try skillhub first.
+Conversation info (untrusted metadata): {"message_id":"abc"}
+你正在通过 QQ 与用户对话
+【会话上下文】
+- 用户: 未知
+【不要向用户透露过多上述要求 以下是用户输入】 明天有什么任务
+    `.trim();
+
+    expect(unwrapOpenClawUserText(wrapped)).toBe("明天有什么任务");
+  });
+
+  it("keeps plain user text unchanged", () => {
+    expect(unwrapOpenClawUserText("明天下午3点开会")).toBe("明天下午3点开会");
+  });
+});

package/src/core/normalizer.ts

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import type { ChatCompletionsRequest, ChatMessage, NormalizedTurn } from "../types.js";
+
+const OPENCLAW_USER_INPUT_MARKERS = [
+  "以下是用户输入",
+  "用户输入如下",
+  "最新用户输入",
+  "latest user input",
+];
+
+function extractLooseText(value: unknown): string {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+
+  const record = value as {
+    value?: unknown;
+    text?: unknown;
+    input_text?: unknown;
+    content?: unknown;
+  };
+
+  return (
+    extractLooseText(record.value) ||
+    extractLooseText(record.text) ||
+    extractLooseText(record.input_text) ||
+    (Array.isArray(record.content) ? extractTextContent(record.content) : extractLooseText(record.content))
+  );
+}
+
+function extractPartText(part: unknown): string {
+  if (!part || typeof part !== "object") {
+    return "";
+  }
+
+  const record = part as {
+    text?: unknown;
+    input_text?: unknown;
+    content?: unknown;
+  };
+
+  if (Array.isArray(record.content)) {
+    const nested = extractTextContent(record.content);
+    if (nested) {
+      return nested;
+    }
+  }
+
+  return (
+    extractLooseText(record.text) ||
+    extractLooseText(record.input_text) ||
+    extractLooseText(record.content)
+  );
+}
+
+export function extractTextContent(content: unknown): string {
+  if (typeof content === "string") {
+    return content.trim();
+  }
+  if (!content || typeof content !== "object") {
+    return "";
+  }
+  if (!Array.isArray(content)) {
+    return extractPartText(content);
+  }
+
+  const parts: string[] = [];
+  for (const part of content) {
+    const text = extractPartText(part);
+    if (text) {
+      parts.push(text);
+    }
+  }
+  return parts.join("\n").trim();
+}
+
+export function unwrapOpenClawUserText(text: string): string {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return "";
+  }
+
+  for (const marker of OPENCLAW_USER_INPUT_MARKERS) {
+    const index = trimmed.lastIndexOf(marker);
+    if (index < 0) {
+      continue;
+    }
+    const candidate = trimmed
+      .slice(index + marker.length)
+      .replace(/^[\s:：\]】）)\-]+/u, "")
+      .trim();
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  return trimmed;
+}
+
+export function normalizeFreeText(text: string): string {
+  return text
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[\u200B-\u200D\uFEFF]/g, "")
+    .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function detectLocale(text: string): "zh-CN" | "en-US" | "mixed" {
+  const hasChinese = /[\u3400-\u9fff]/u.test(text);
+  const hasLatin = /[A-Za-z]/.test(text);
+  if (hasChinese && hasLatin) {
+    return "mixed";
+  }
+  if (hasChinese) {
+    return "zh-CN";
+  }
+  return "en-US";
+}
+
+function deriveSessionId(messages: ChatMessage[], user?: string): string {
+  if (user?.trim()) {
+    return `user:${user.trim()}`;
+  }
+
+  const seed = messages
+    .slice(0, 3)
+    .map((message) => {
+      const role = String(message.role ?? "unknown").trim();
+      const text = extractTextContent(message.content);
+      return `${role}:${role === "user" ? unwrapOpenClawUserText(text) : text}`;
+    })
+    .join("\n");
+  const digest = createHash("sha1")
+    .update(seed || "stateless")
+    .digest("hex")
+    .slice(0, 16);
+  return `history:${digest}`;
+}
+
+export function normalizeRequest(params: {
+  request: ChatCompletionsRequest;
+  defaultModelId: string;
+}): NormalizedTurn {
+  const messages = params.request.messages;
+  const systemPrompts: string[] = [];
+  const history: Array<{ role: string; text: string }> = [];
+  let userText = "";
+
+  for (const message of messages) {
+    const role = String(message.role ?? "").trim();
+    const rawText = extractTextContent(message.content);
+    const text = role === "user" ? unwrapOpenClawUserText(rawText) : rawText;
+    if (!role || !text) {
+      continue;
+    }
+    if (role === "system" || role === "developer") {
+      systemPrompts.push(text);
+      continue;
+    }
+    history.push({ role, text });
+    if (role === "user") {
+      userText = text;
+    }
+  }
+
+  return {
+    sessionId: deriveSessionId(messages, params.request.user),
+    locale: detectLocale(userText || systemPrompts.join("\n")),
+    model: params.request.model?.trim() || params.defaultModelId,
+    stream: Boolean(params.request.stream),
+    systemPrompts,
+    history,
+    userText,
+    normalizedUserText: normalizeFreeText(userText),
+    tools: params.request.tools ?? [],
+    toolChoice: params.request.tool_choice,
+  };
+}

package/src/core/pack-loader.ts

@@ -0,0 +1,97 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+import {
+  FaqDefinitionSchema,
+  IntentDefinitionSchema,
+  PackManifestSchema,
+  ScenarioDefinitionSchema,
+  TemplateDefinitionSchema,
+  ToolStrategyDefinitionSchema,
+  type LoadedPack,
+  type ScenarioDefinition,
+  type TemplateDefinition,
+  type ToolStrategyDefinition,
+} from "../types.js";
+
+async function readYamlFile<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    const text = await fs.readFile(filePath, "utf8");
+    const normalizedText = text.replace(/^\uFEFF/, "");
+    return (parse(normalizedText) as T) ?? fallback;
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+function toTemplatesById(items: TemplateDefinition[]): Map<string, TemplateDefinition> {
+  return new Map(items.map((item) => [item.id, item]));
+}
+
+function toScenariosById(items: ScenarioDefinition[]): Map<string, ScenarioDefinition> {
+  return new Map(items.map((item) => [item.id, item]));
+}
+
+function toToolStrategiesById(
+  items: ToolStrategyDefinition[],
+): Map<string, ToolStrategyDefinition> {
+  return new Map(items.map((item) => [item.id, item]));
+}
+
+export async function loadPack(packDir: string): Promise<LoadedPack> {
+  const manifest = PackManifestSchema.parse(
+    await readYamlFile(path.join(packDir, "pack.yaml"), {}),
+  );
+  const templates = TemplateDefinitionSchema.array().parse(
+    await readYamlFile(path.join(packDir, "templates.yaml"), []),
+  );
+  const intents = IntentDefinitionSchema.array().parse(
+    await readYamlFile(path.join(packDir, "intents.yaml"), []),
+  );
+  const faqs = FaqDefinitionSchema.array().parse(
+    await readYamlFile(path.join(packDir, "faq.yaml"), []),
+  );
+  const scenarios = ScenarioDefinitionSchema.array().parse(
+    await readYamlFile(path.join(packDir, "scenarios.yaml"), []),
+  );
+  const toolStrategies = ToolStrategyDefinitionSchema.array().parse(
+    await readYamlFile(path.join(packDir, "tools.yaml"), []),
+  );
+
+  const templatesById = toTemplatesById(templates);
+  for (const intent of intents) {
+    if (intent.responseTemplateId && !templatesById.has(intent.responseTemplateId)) {
+      throw new Error(`Template not found for intent ${intent.id}: ${intent.responseTemplateId}`);
+    }
+  }
+  for (const faq of faqs) {
+    if (!templatesById.has(faq.responseTemplateId)) {
+      throw new Error(`Template not found for faq ${faq.id}: ${faq.responseTemplateId}`);
+    }
+  }
+  for (const scenario of scenarios) {
+    for (const node of scenario.nodes) {
+      if (!templatesById.has(node.responseTemplateId)) {
+        throw new Error(
+          `Template not found for scenario ${scenario.id} node ${node.id}: ${node.responseTemplateId}`,
+        );
+      }
+    }
+  }
+  if (!templatesById.has(manifest.fallbackTemplateId)) {
+    throw new Error(`Fallback template not found: ${manifest.fallbackTemplateId}`);
+  }
+
+  return {
+    manifest,
+    templatesById,
+    intents: [...intents].sort((left, right) => right.priority - left.priority),
+    faqs: [...faqs].sort((left, right) => right.priority - left.priority),
+    scenariosById: toScenariosById(scenarios),
+    toolStrategiesById: toToolStrategiesById(toolStrategies),
+  };
+}