openclaw-server 0.1.0

package/readme.md

@@ -0,0 +1,1219 @@
+# openclaw-server 设计方案
+
+## 1. 项目定位
+
+`openclaw-server` 不是一个真正的大模型服务，而是一个“拟态 AI 服务”。
+
+它的目标是：
+
+- 使用 TypeScript 开发一个独立后台服务
+- 以 OpenAI 兼容接口的形式给 OpenClaw 提供模型能力
+- 不调用任何真实 AI API
+- 通过预制回复、规则匹配、场景状态机、模板渲染、受控工具调用，尽量做出“像 AI 一样能对话”的效果
+
+它的本质不是“通用智能”，而是“可控的、场景化的、可运营的智能拟态层”。
+
+## 2. 设计目标与硬约束
+
+### 2.0 硬约束
+
+- 不改动任何 OpenClaw 源代码
+- 不修改 `src/` 下的 provider、gateway、protocol、agent 逻辑
+- 不新增 OpenClaw 内置 provider，不注册新的 OpenClaw 原生 API，不 fork OpenClaw 协议
+- 不修改 `pnpm-workspace.yaml`、根 `package.json`、构建链路来“迁就” `openclaw-server`
+- OpenClaw 侧只允许做部署和配置变更，例如 `openclaw.json`、环境变量、启动脚本
+- `openclaw-server` 必须兼容 OpenClaw 已有的 provider 调用方式，而不是反过来要求 OpenClaw 适配它
+
+### 2.1 目标
+
+- 让 OpenClaw 可以把 `openclaw-server` 当成一个自定义模型提供商使用
+- 支持多轮对话
+- 支持流式输出
+- 支持预制知识包和场景包
+- 支持有限的工具调用能力
+- 支持运营人员持续扩充“像 AI 一样”的回复库
+- 通过服务端逻辑和知识包迭代升级能力，不依赖 OpenClaw 代码变更
+
+### 2.2 非目标
+
+- 不追求开放域推理能力
+- 不追求代码生成、复杂规划、数学推理等真实大模型能力
+- 不保证对任意陌生问题都有高质量回答
+- 不做“假装自己是通用 AGI”的产品定位
+
+## 3. 设计依据
+
+本方案基于当前仓库中 OpenClaw 已有的 provider 接入方式设计，核心依据如下：
+
+- `docs/gateway/local-models.md`
+  说明 OpenClaw 已支持接入 OpenAI 兼容的本地或自定义服务
+- `docs/providers/litellm.md`
+  说明 OpenClaw 可以通过统一兼容协议接入代理网关
+- `src/commands/onboard-auth.config-shared.ts`
+  说明自定义 provider 可以通过 `models.providers` 合并进入模型配置
+- `src/agents/model-auth.ts`
+  说明 OpenClaw 会从 `models.providers.<provider>` 解析 `baseUrl`、`apiKey`
+- `src/agents/model-compat.ts`
+  说明非 OpenAI 官方 `openai-completions` 端点会被视为兼容端点，`developer` role 不应作为强依赖
+- `src/agents/custom-api-registry.ts`
+  说明技术上可以注册原生自定义 API，但这需要 OpenClaw 侧配合，不符合“零源码改动”约束
+
+因此，在“不改动任何 OpenClaw 代码”的前提下，`openclaw-server` 的接入方式必须是：
+
+- 完全适配 OpenClaw 已存在的自定义 provider 机制
+- 通过 `models.providers.openclaw-server` 接入 OpenClaw
+- 以 OpenAI 兼容 HTTP 接口为边界，不要求 OpenClaw 增加新协议
+- 所有新增能力都在 `openclaw-server` 内部完成
+
+## 4. 推荐总体方案
+
+### 4.1 推荐接入模式
+
+推荐 `openclaw-server` 第一阶段提供以下接口：
+
+- `GET /healthz`
+- `GET /v1/models`
+- `POST /v1/chat/completions`
+
+按需可补充以下接口，但它们不是 OpenClaw 零改动接入的前提：
+
+- `POST /v1/responses`
+- `POST /admin/packs/reload`
+- `GET /admin/stats`
+
+### 4.2 推荐协议
+
+第一阶段优先实现 `openai-completions`，原因：
+
+- OpenClaw 已支持用自定义 `baseUrl` 对接 OpenAI 兼容端点
+- 不需要修改 OpenClaw 源码
+- 实现复杂度最低
+- 支持流式输出
+- 便于后续接入其他客户端
+
+### 4.3 推荐产品边界
+
+`openclaw-server` 不应一开始就尝试覆盖“任何问题”。
+
+推荐从闭域场景开始：
+
+- 问候和闲聊
+- OpenClaw 产品问答
+- 常见配置指导
+- 常见错误排查
+- 常见命令解释
+- 固定业务流程问答
+- 限定任务的脚本式交互
+
+也就是说，先做“高覆盖的封闭场景助手”，而不是“低质量的通用助手”。
+
+## 5. 总体架构
+
+```text
+OpenClaw
+  -> models.providers.openclaw-server
+  -> POST /v1/chat/completions
+
+openclaw-server
+  -> API Compatibility Layer
+  -> Request Normalizer
+  -> Session Store
+  -> Intent Router
+  -> Scenario State Machine
+  -> Retrieval and Template Engine
+  -> Tool Decision Layer
+  -> Stream Renderer
+  -> Observability and Admin
+
+Knowledge Packs
+  -> intents
+  -> scenarios
+  -> templates
+  -> faq
+  -> tools
+  -> policies
+```
+
+### 5.1 核心思想
+
+服务端不“生成”答案，而是“选择、组合、渲染、串联”答案。
+
+整体流程分为 7 层：
+
+1. 协议兼容层
+2. 请求归一化层
+3. 会话状态层
+4. 意图识别层
+5. 场景编排层
+6. 文本渲染层
+7. 输出与观测层
+
+## 6. 核心模块设计
+
+### 6.1 API Compatibility Layer
+
+职责：
+
+- 接收 OpenAI 兼容请求
+- 校验请求结构
+- 转换成内部统一格式
+- 输出 OpenAI 兼容响应
+- 支持 SSE 流式返回
+
+建议支持的请求字段：
+
+- `model`
+- `messages`
+- `stream`
+- `temperature`
+- `user`
+- `max_tokens`
+- `tools`
+- `tool_choice`
+
+建议第一阶段忽略或固定处理的字段：
+
+- `temperature`
+- `top_p`
+- `presence_penalty`
+- `frequency_penalty`
+- `logprobs`
+
+原因：
+
+- 这是拟态服务，不是真实采样模型
+- 这些参数不应影响核心业务逻辑
+
+### 6.2 Request Normalizer
+
+职责：
+
+- 提取系统提示、历史对话、当前用户问题
+- 识别语言
+- 归一化标点、空白、数字、时间表达
+- 提取关键词、命令词、实体词
+- 生成查询指纹
+
+输出统一结构：
+
+```ts
+type NormalizedTurn = {
+  requestId: string;
+  sessionId: string;
+  model: string;
+  locale: "zh-CN" | "en-US" | "mixed";
+  systemPrompt: string[];
+  history: Array<{ role: "user" | "assistant" | "tool"; text: string }>;
+  userText: string;
+  tools: ClientToolDef[];
+  toolChoice?: "auto" | "none" | "required" | { name: string };
+  features: {
+    keywords: string[];
+    commands: string[];
+    entities: string[];
+    isQuestion: boolean;
+    isGreeting: boolean;
+    isHelpRequest: boolean;
+  };
+};
+```
+
+### 6.3 Session Store
+
+职责：
+
+- 维护每个会话的上下文状态
+- 保存最近若干轮对话
+- 保存当前场景节点
+- 保存已提取的槽位数据
+- 保存命中的知识包版本
+
+建议第一阶段使用：
+
+- 内存缓存保存热会话
+- JSONL 持久化会话日志
+
+第二阶段可升级：
+
+- SQLite 持久化
+- 支持多实例共享会话
+
+会话结构建议：
+
+```ts
+type SessionState = {
+  sessionId: string;
+  locale: string;
+  activeScenarioId?: string;
+  activeNodeId?: string;
+  slots: Record<string, string>;
+  lastIntent?: string;
+  lastReplyId?: string;
+  turnCount: number;
+  recentHistory: Array<{ role: string; text: string; ts: number }>;
+  debug: {
+    lastMatchedPack?: string;
+    lastMatchedIntent?: string;
+    lastScore?: number;
+  };
+};
+```
+
+### 6.4 Intent Router
+
+职责：
+
+- 将用户输入映射到某个意图
+- 给出候选意图和置信分
+- 决定进入 FAQ、闲聊、流程型场景还是工具调用型场景
+
+推荐采用混合匹配：
+
+- 精确短语匹配
+- 关键词匹配
+- 正则匹配
+- 词组倒排索引
+- 简单相似度评分
+- 历史场景加权
+
+建议打分公式：
+
+```text
+score =
+  0.35 * exact_or_regex_match
+  + 0.25 * keyword_overlap
+  + 0.20 * scenario_context_match
+  + 0.10 * slot_match
+  + 0.10 * locale_match
+```
+
+意图路由结果：
+
+- `faq`
+- `smalltalk`
+- `workflow`
+- `tool_call`
+- `fallback`
+
+### 6.5 Scenario State Machine
+
+职责：
+
+- 管理多轮固定流程
+- 处理“先问 A，再问 B，再给结果”的会话
+- 把看起来像 AI 的多轮交互拆成可控流程
+
+典型场景：
+
+- 首次欢迎
+- 配置引导
+- 故障排查
+- 收集参数
+- 推荐下一步命令
+- 引导用户执行某个 OpenClaw 工具或命令
+
+状态机的核心价值：
+
+- 避免每一轮都重新“猜”上下文
+- 能稳定输出高一致性结果
+- 更适合运营配置和回放排查
+
+### 6.6 Retrieval and Template Engine
+
+职责：
+
+- 从知识包中检索候选答案
+- 按场景和槽位渲染模板
+- 根据用户语气和语言输出不同版本
+
+推荐回答来源优先级：
+
+1. 当前场景节点模板
+2. FAQ 精确匹配
+3. FAQ 模糊匹配
+4. 小闲聊模板
+5. 兜底模板
+
+模板引擎建议支持：
+
+- 变量插值
+- 条件片段
+- 随机同义变体
+- 语言分支
+- 回复后动作
+
+模板示例：
+
+```yaml
+id: troubleshooting.gateway_down.reply
+locale: zh-CN
+variants:
+  - "看起来网关当前没有正常运行。你可以先执行 `openclaw gateway run`，然后再检查一次状态。"
+  - "当前更像是网关未启动的问题。先运行 `openclaw gateway run`，再确认端口和日志。"
+postActions:
+  - suggest_intent: gateway_health_check
+```
+
+### 6.7 Tool Decision Layer
+
+职责：
+
+- 当 OpenClaw 传入 `tools` 时，决定是否返回工具调用
+- 限制只有预定义场景允许触发工具
+- 保证工具参数来自明确规则，不来自自由生成
+
+这是拟态服务里最重要的安全点之一。
+
+原则：
+
+- 工具调用必须是白名单
+- 参数必须经过 schema 校验
+- 不允许“自由拼接”未知工具名
+- 不允许根据模糊意图直接执行高风险工具
+
+推荐策略：
+
+- 第一阶段默认只返回文本，不主动调用工具
+- 第二阶段仅开放少量安全工具
+- 高风险工具永远要求明确命中场景和参数
+
+### 6.8 Stream Renderer
+
+职责：
+
+- 把最终文本拆成流式 chunk 输出
+- 模拟真实 AI 的逐步回复体验
+- 控制首包延迟和 chunk 大小
+
+建议实现：
+
+- 首包延迟 100ms 到 300ms
+- 每个 chunk 8 到 32 字符
+- 标点优先切片
+- 对工具调用场景可直接一次性返回结构化结果
+
+### 6.9 Observability and Admin
+
+职责：
+
+- 记录命中率、兜底率、场景转移、工具调用数
+- 输出结构化日志
+- 支持热加载知识包
+- 支持对低命中问题做运营回补
+
+建议指标：
+
+- `requests_total`
+- `intent_match_rate`
+- `fallback_rate`
+- `scenario_continue_rate`
+- `tool_call_rate`
+- `unknown_query_topn`
+
+## 7. 知识包设计
+
+“预制大量 AI 返回”的关键不在代码，而在知识包体系。
+
+建议把知识包拆成以下文件：
+
+```text
+openclaw-server/
+  packs/
+    default/
+      pack.json
+      intents.yaml
+      scenarios.yaml
+      templates.yaml
+      faq.yaml
+      tools.yaml
+      policies.yaml
+      synonyms.yaml
+```
+
+### 7.1 intents.yaml
+
+职责：
+
+- 定义意图名
+- 提供关键词、正则、例句、优先级
+
+示例：
+
+```yaml
+- id: greeting
+  locale: zh-CN
+  priority: 100
+  keywords: ["你好", "在吗", "嗨", "hello", "hi"]
+  examples: ["你好", "你在吗", "hi"]
+
+- id: gateway_status_help
+  locale: zh-CN
+  priority: 90
+  keywords: ["网关", "gateway", "状态", "启动失败", "日志"]
+  regex:
+    - "(gateway|网关).*(状态|启动|失败|日志)"
+```
+
+### 7.2 faq.yaml
+
+职责：
+
+- 承载高频问答
+- 适合单轮、稳定、标准答案
+
+示例：
+
+```yaml
+- id: faq.install.local
+  intents: ["install_help"]
+  questionPatterns:
+    - "怎么安装"
+    - "如何部署"
+  answerTemplate: install.guide.basic
+```
+
+### 7.3 scenarios.yaml
+
+职责：
+
+- 定义多轮状态机
+- 适合引导式交互
+
+示例：
+
+```yaml
+- id: setup.gateway
+  entryIntents: ["setup_gateway"]
+  nodes:
+    - id: ask_platform
+      replyTemplate: setup.gateway.ask_platform
+      transitions:
+        - whenIntent: setup_platform_linux
+          to: linux_steps
+        - whenIntent: setup_platform_windows
+          to: windows_steps
+
+    - id: linux_steps
+      replyTemplate: setup.gateway.linux_steps
+      end: true
+```
+
+### 7.4 templates.yaml
+
+职责：
+
+- 管理所有回复模板
+- 分语言、分语气、分场景
+
+### 7.5 tools.yaml
+
+职责：
+
+- 定义允许调用的工具
+- 绑定对应场景
+- 约束参数来源
+
+示例：
+
+```yaml
+- id: get_gateway_health
+  toolName: gateway.health
+  allowedIntents: ["gateway_status_help"]
+  argMap:
+    target: "$session.defaultTarget"
+```
+
+### 7.6 policies.yaml
+
+职责：
+
+- 约束不可回答的问题
+- 约束敏感操作
+- 约束不确定回答
+
+示例策略：
+
+- 未命中高置信意图时，不编造事实
+- 涉及删除、重置、密钥泄露的操作时，只给出确认指引，不直接触发工具
+- 对未知问题使用明确兜底模板
+
+## 8. 响应生成策略
+
+### 8.1 文本响应模式
+
+适用于：
+
+- 闲聊
+- FAQ
+- 配置说明
+- 错误排查建议
+
+生成方式：
+
+- 先检索最相关模板
+- 再插入槽位和上下文
+- 最后做风格微调
+
+### 8.2 工具调用模式
+
+适用于：
+
+- 请求明确
+- 工具可安全执行
+- 参数可由规则确定
+
+返回形式：
+
+- OpenAI 兼容 `tool_calls`
+
+### 8.3 兜底模式
+
+适用于：
+
+- 无法识别意图
+- 命中分过低
+- 不确定该回答什么
+
+推荐兜底原则：
+
+- 明确说明能力边界
+- 引导用户换一种问法
+- 给出 2 到 4 个可选问题方向
+
+示例：
+
+> 我现在更适合回答 OpenClaw 的配置、网关、通道、常见故障和固定流程问题。  
+> 你可以继续问我：
+>
+> 1. 如何配置网关
+> 2. 如何查看日志
+> 3. 某个命令怎么用
+> 4. 某个报错怎么排查
+
+## 9. 请求处理流程
+
+```text
+1. OpenClaw 发送 /v1/chat/completions 请求
+2. openclaw-server 校验 token 和请求 schema
+3. Request Normalizer 提取 userText、history、tools
+4. Session Store 读取会话状态
+5. Intent Router 计算候选意图
+6. Scenario Engine 判断是否在已有流程中
+7. Retrieval Engine 选出模板或 FAQ
+8. Tool Layer 决定返回文本还是 tool_call
+9. Stream Renderer 生成兼容响应
+10. Logger 记录匹配结果和兜底情况
+11. Session Store 更新状态
+```
+
+## 10. 对 OpenClaw 的接入方案
+
+### 10.0 接入边界
+
+允许的事情：
+
+- 启动 `openclaw-server`
+- 在 OpenClaw 配置中增加一个自定义 provider
+- 通过环境变量或配置写入 `baseUrl`、`apiKey`、默认模型
+
+不允许的事情：
+
+- 修改 OpenClaw 的 `src/` 代码
+- 向 OpenClaw 增加新的内置 provider 代码
+- 让 OpenClaw 为 `openclaw-server` 新增私有协议
+- 修改 OpenClaw 的构建、workspace、依赖结构来容纳 `openclaw-server`
+
+### 10.1 推荐配置
+
+建议在 OpenClaw 中把 `openclaw-server` 当成一个自定义 provider：
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "openclaw-server/default-assistant" },
+      models: {
+        "openclaw-server/default-assistant": { alias: "OpenClaw Server" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      "openclaw-server": {
+        baseUrl: "http://127.0.0.1:4318/v1",
+        apiKey: "${OPENCLAW_SERVER_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "default-assistant",
+            name: "OpenClaw Server Default Assistant",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 32000,
+            maxTokens: 2048,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### 10.2 为什么用 `openai-completions`
+
+原因：
+
+- 与 OpenClaw 当前自定义 provider 接入方式最吻合
+- 不改动 OpenClaw 源码，仅使用现有配置能力
+- 可以直接复用 OpenClaw 现有模型选择逻辑
+
+### 10.3 兼容注意事项
+
+根据 `src/agents/model-compat.ts`，对非官方 OpenAI 端点：
+
+- 不应依赖 `developer` role
+- 应重点处理 `system` 和 `user` 消息
+
+因此 `openclaw-server` 内部应将：
+
+- `system`
+- `developer`
+
+统一作为“额外系统上下文”处理。
+
+### 10.4 `openclaw-server` 必须兼容的最小行为
+
+- 支持 `Authorization: Bearer <token>`
+- 支持 `POST /v1/chat/completions`
+- 支持 `stream=false` 和 `stream=true`
+- 能处理 `system`、`developer`、`user`、`assistant` 历史消息
+- 对 `developer` role 不做强依赖，内部统一折叠到系统上下文
+- 能接受 `tools` 和 `tool_choice`，即使第一阶段只选择性支持
+- 支持 `GET /v1/models`，方便 OpenClaw 或运维侧探活
+- 即使没有真实 token 统计，也应返回兼容的 `usage` 字段，必要时可填 0
+
+## 11. API 设计
+
+### 11.1 `GET /healthz`
+
+返回：
+
+```json
+{ "ok": true, "version": "0.1.0" }
+```
+
+### 11.2 `GET /v1/models`
+
+返回：
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "default-assistant",
+      "object": "model",
+      "owned_by": "openclaw-server"
+    }
+  ]
+}
+```
+
+### 11.3 `POST /v1/chat/completions`
+
+支持：
+
+- 非流式文本回复
+- 流式 SSE 回复
+- 可选工具调用
+
+文本响应示例：
+
+```json
+{
+  "id": "chatcmpl_123",
+  "object": "chat.completion",
+  "created": 1760000000,
+  "model": "default-assistant",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "当前更像是网关没有启动。你可以先执行 `openclaw gateway run`。"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 0,
+    "completion_tokens": 0,
+    "total_tokens": 0
+  }
+}
+```
+
+工具调用响应示例：
+
+```json
+{
+  "id": "chatcmpl_124",
+  "object": "chat.completion",
+  "created": 1760000001,
+  "model": "default-assistant",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": null,
+        "tool_calls": [
+          {
+            "id": "call_1",
+            "type": "function",
+            "function": {
+              "name": "gateway.health",
+              "arguments": "{\"target\":\"local\"}"
+            }
+          }
+        ]
+      },
+      "finish_reason": "tool_calls"
+    }
+  ]
+}
+```
+
+## 12. 推荐代码结构
+
+在“零源码改动 OpenClaw”的约束下，这里只有一个合理选择：保持 `openclaw-server` 独立。
+
+- 不应把实现迁到 `packages/openclaw-server`
+- 不应修改 `pnpm-workspace.yaml`
+- 不应让 `openclaw-server` 绑定 OpenClaw 仓库内部的构建链路
+
+即使当前暂时放在同一个仓库目录下，也应把它视为独立服务，自带自己的 `package.json`、`tsconfig.json`、启动脚本和发布流程。
+
+建议结构如下：
+
+```text
+openclaw-server/
+  readme.md
+  package.json
+  tsconfig.json
+  src/
+    index.ts
+    server.ts
+    config.ts
+    routes/
+      health.ts
+      models.ts
+      chat-completions.ts
+      admin.ts
+    core/
+      request-normalizer.ts
+      session-store.ts
+      intent-router.ts
+      scenario-engine.ts
+      retrieval-engine.ts
+      template-engine.ts
+      tool-engine.ts
+      stream-renderer.ts
+      response-builder.ts
+    packs/
+      loader.ts
+      validator.ts
+      compiler.ts
+    schemas/
+      openai.ts
+      pack.ts
+    infra/
+      logger.ts
+      metrics.ts
+      jsonl-store.ts
+```
+
+## 13. 技术选型建议
+
+### 13.1 语言与运行时
+
+- TypeScript
+- Node 22+
+- ESM
+
+### 13.2 HTTP 层
+
+推荐：
+
+- `express`
+- `zod`
+
+原因：
+
+- 仓库根依赖里已存在 `express`
+- 实现 OpenAI 兼容接口足够简单
+- 可快速支持 SSE
+
+### 13.3 存储
+
+第一阶段：
+
+- JSON
+- YAML
+- JSONL
+- 内存 LRU
+
+第二阶段：
+
+- SQLite
+
+### 13.4 观测
+
+- 结构化日志
+- Prometheus 风格 metrics
+- 命中调试信息写入日志
+
+## 14. 实施阶段
+
+### Phase 0: 文档和样例包
+
+产出：
+
+- README 设计文档
+- 基础 pack schema
+- 一套中文默认知识包
+
+### Phase 1: 可运行 MVP
+
+范围：
+
+- `GET /healthz`
+- `GET /v1/models`
+- `POST /v1/chat/completions`
+- 非流式文本回复
+- 流式文本回复
+- FAQ 和闲聊
+- 基础会话状态
+- 兜底模板
+
+验收标准：
+
+- OpenClaw 在零源码改动前提下，能通过现有 provider 配置直接调用它
+- 可稳定回答 50 到 100 个高频问题
+- 兜底率可观测
+
+### Phase 2: 场景化引导
+
+范围：
+
+- 状态机场景
+- 槽位提取
+- 多轮引导
+- pack 热加载
+
+验收标准：
+
+- 至少 5 个可复用多轮流程
+- 多轮一致性明显提升
+
+### Phase 3: 受控工具调用
+
+范围：
+
+- 支持 OpenAI 兼容 `tools`
+- 白名单工具映射
+- 参数模板化
+
+验收标准：
+
+- 只在明确场景下触发工具
+- 无未知工具名
+- 无未校验参数
+
+### Phase 4: 运营系统
+
+范围：
+
+- 未命中问题分析
+- pack 版本管理
+- 问题聚类和人工补录
+
+验收标准：
+
+- 可以根据日志持续扩充拟态能力
+- 新增知识包无需改核心代码
+
+## 15. 测试方案
+
+### 15.1 单元测试
+
+覆盖：
+
+- 意图匹配
+- 场景转移
+- 模板渲染
+- 工具参数生成
+- 请求 schema 校验
+
+### 15.2 集成测试
+
+覆盖：
+
+- `/v1/chat/completions` 非流式
+- `/v1/chat/completions` 流式
+- OpenClaw provider 接入
+- 会话连续多轮
+
+### 15.3 回归测试
+
+建立固定用例集：
+
+- 闲聊 20 条
+- FAQ 50 条
+- 故障排查 30 条
+- 工具调用 20 条
+- 兜底 20 条
+
+每次 pack 更新都跑一遍。
+
+## 16. 风险与限制
+
+### 16.1 最大风险
+
+如果知识包覆盖不够，用户会很快发现这不是真 AI。
+
+所以项目成败主要取决于：
+
+- 场景收敛是否清晰
+- 预制内容是否充足
+- 兜底设计是否体面
+- 多轮状态机是否自然
+
+### 16.2 核心限制
+
+- 无法覆盖开放域复杂推理
+- 容易在陌生问题上重复兜底
+- 需要持续运营维护知识包
+- 不能把“模板拼装”误认为“模型理解”
+
+### 16.3 风险控制建议
+
+- 只对封闭域宣称能力
+- 对未知问题明确说不知道
+- 工具调用必须白名单
+- 对高风险动作始终要求二次确认
+
+## 17. 最终结论
+
+`openclaw-server` 最合理的定位，不是“造一个假的大模型”，而是“造一个 OpenAI 兼容、场景化、可运营、可扩充的智能应答引擎”。
+
+推荐路线是：
+
+1. 用 TypeScript 实现独立服务
+2. 先提供 OpenAI Chat Completions 兼容接口
+3. 通过 `models.providers.openclaw-server` 接入 OpenClaw
+4. 以知识包、状态机、模板、白名单工具调用为核心能力
+5. 先把封闭场景做到像 AI，再逐步扩展
+
+如果后续进入编码阶段，建议先做 Phase 1 MVP；后续扩展也应继续保持“OpenClaw 零源码改动、由 openclaw-server 单向适配”的边界。
+
+## 18. 当前实现状态
+
+当前 `openclaw-server` 已实现以下能力：
+
+- 独立 TypeScript 服务，不依赖 OpenClaw 构建链路
+- `GET /healthz`
+- `GET /v1/models`
+- `POST /v1/chat/completions`
+- `POST /v1/responses`
+- `POST /v1/tasks/chat`
+- `GET /v1/tasks`
+- `GET /v1/tasks/reminders/pending`
+- `GET /v1/tasks/stats`
+- `GET /admin/stats`
+- `POST /admin/packs/reload`
+- Bearer Token 鉴权
+- 非流式文本回复
+- SSE 流式回复
+- OpenAI Responses API 兼容子集（文本、SSE、受控 tool call）
+- 基于 SQLite 的任务提醒机器人（自然语言建任务、提醒、完成/延后/取消、统计）
+- 基于知识包的意图匹配和 FAQ 检索
+- 简单多轮场景继续
+- 受控工具调用骨架和 `tool_choice` 前置校验
+
+当前目录结构：
+
+```text
+openclaw-server/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+  packs/default/
+  readme.md
+```
+
+## 19. 本地运行
+
+### 19.1 启动服务
+
+在仓库根目录执行：
+
+```bash
+cd openclaw-server
+pnpm exec tsx src/index.ts
+```
+
+也可以先设置环境变量：
+
+```bash
+export OPENCLAW_SERVER_PORT=4318
+export OPENCLAW_SERVER_API_KEY=openclaw-server-dev
+pnpm exec tsx src/index.ts
+```
+
+Windows PowerShell 示例：
+
+```powershell
+$env:OPENCLAW_SERVER_PORT = "4318"
+$env:OPENCLAW_SERVER_API_KEY = "openclaw-server-dev"
+pnpm exec tsx src/index.ts
+```
+
+### 19.2 直接验证接口
+
+健康检查：
+
+```bash
+curl http://127.0.0.1:4318/healthz
+```
+
+查看模型：
+
+```bash
+curl http://127.0.0.1:4318/v1/models \
+  -H 'Authorization: Bearer openclaw-server-dev'
+```
+
+聊天请求：
+
+```bash
+curl http://127.0.0.1:4318/v1/chat/completions \
+  -H 'Authorization: Bearer openclaw-server-dev' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "default-assistant",
+    "messages": [{"role": "user", "content": "你好"}]
+  }'
+```
+
+Responses 请求：
+
+```bash
+curl http://127.0.0.1:4318/v1/responses \
+  -H 'Authorization: Bearer openclaw-server-dev' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "default-assistant",
+    "input": "gateway status",
+    "tools": [
+      {
+        "type": "function",
+        "function": { "name": "gateway.health" }
+      }
+    ],
+    "tool_choice": "required"
+  }'
+```
+
+任务机器人请求：
+
+```bash
+curl http://127.0.0.1:4318/v1/tasks/chat \
+  -H 'Authorization: Bearer openclaw-server-dev' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "user": "demo-user",
+    "text": "明天下午3点开会",
+    "now": "2026-03-12T09:00:00+08:00"
+  }'
+```
+
+查询待提醒任务：
+
+```bash
+curl 'http://127.0.0.1:4318/v1/tasks/reminders/pending?user=demo-user&now=2026-03-13T14%3A45%3A00%2B08%3A00' \
+  -H 'Authorization: Bearer openclaw-server-dev'
+```
+
+查看统计：
+
+```bash
+curl http://127.0.0.1:4318/admin/stats \
+  -H 'Authorization: Bearer openclaw-server-dev'
+```
+
+重载知识包：
+
+```bash
+curl -X POST http://127.0.0.1:4318/admin/packs/reload \
+  -H 'Authorization: Bearer openclaw-server-dev'
+```
+
+## 20. OpenClaw 零改动接入示例
+
+OpenClaw 侧只需要改配置，不需要改源码：
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "openclaw-server/default-assistant" },
+      models: {
+        "openclaw-server/default-assistant": { alias: "OpenClaw Server" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      "openclaw-server": {
+        baseUrl: "http://127.0.0.1:4318/v1",
+        apiKey: "${OPENCLAW_SERVER_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "default-assistant",
+            name: "OpenClaw Server Default Assistant",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 32000,
+            maxTokens: 2048,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## 21. 当前已验证项
+
+本地已验证：
+
+- `openclaw-server` 单元测试通过
+- 服务真实启动成功
+- `/healthz` 可访问
+- `/v1/chat/completions` 可返回回复
+- `/v1/responses` 可返回文本和受控工具调用
+- `/v1/tasks/chat` 可完成自然语言任务创建与提醒确认
+- `/v1/tasks/reminders/pending` 可返回到点提醒
+- `/v1/tasks/stats` 可返回任务统计
+- `/admin/stats` 可返回运行时统计
+- `/admin/packs/reload` 可触发知识包重载
+
+
+