mirror of https://github.com/hansjone/oclaw.git synced 2026-10-09 03:30:48 +08:00

oliver 420abac9f1 refactor: root-package imports (svc/runtime/interfaces) and fix PYTHONPATH

- Rename platform/ to svc/ to avoid shadowing stdlib platform.
- Replace from oclaw.* with from svc/runtime/interfaces; update -m CLI paths.
- tests/conftest: prepend repo root to sys.path (no parent-folder package name).
- CI: paths and offline_eval script under repo root.
- Ops scripts: PYTHONPATH must be repo root for python -m runtime.* (fixes gateway/WhatsApp sidecar startup).
- Fix default oclaw.json path in tabular/file attachment limits; stabilize attachment test config.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-13 14:51:17 +08:00

25 KiB

Raw Blame History

运行手册（RUNBOOK）

本文档面向“日常运维与排障”场景，聚焦可直接执行的命令与操作顺序。

关联文档：

trace 字段与阶段对照：docs/oclaw-trace-taxonomy.md
skill 安装/执行排障：docs/oclaw-skill-troubleshooting.md

1. 统一入口（只保留最新）

所有运维命令统一通过 scripts/，不要再使用 python -m runtime.operations ... 或历史 .bat 方式。

补充：工具脚本也统一放在 scripts/（例如 seed_mcp_registry.py、ws_probe.py）。

路径基准约定（开源必读）：

运行目录固定为仓库根（.../oclaw），不要把网关/worker 常驻进程放到上一级目录。
默认配置文件路径为仓库根下的 oclaw.json（可用 OCLAW_CONFIG_PATH 覆盖）。
默认数据目录为仓库根下的 data/（主库：data/ai_ops.sqlite）。
相对路径一律按仓库根解析；不要在代码里拼接 oclaw/... 二级前缀。

开源前路径自检清单：

把仓库目录临时重命名后，scripts/start_gateway.ps1 -SkipInstall -Background 仍能启动。
http://127.0.0.1:8787/chat 返回 200，且后台日志中不出现 .../oclaw/oclaw/... 路径。
python -m pytest tests/test_workspace_path_guard.py tests/test_oclaw_startup_workspace_resolution.py -q 通过。

1.1 开源快速安装（从零到跑起来）

若你只需要一页「开箱即用」清单（复制 _local/system.env、bootstrap、启动网关、可选 netx），可先读仓库根目录 README.md 中的 开箱即用（从零跑起来），再回到本节按需启用微信/WhatsApp。

本节面向“第一次拿到开源仓库的用户”，目标是 15 分钟内跑通：

网关（Admin + Chat）
微信（Personal WeChat）收消息、回消息（官方插件 + 本地原生宿主 /weixin/native/reply）
WhatsApp（实验）：收消息、回消息（本仓库 Baileys sidecar + 本地 /inbound/whatsapp）

1.1.1 前置依赖

Windows 10/11
Python：建议 3.11+（仓库脚本默认会创建 .venv/）
Node.js：要求 >=22（官方微信插件声明 engines.node >=22）
npm：随 Node 安装
（可选）Git：用于拉取仓库

注意：Node 版本过低会导致微信插件/sidecar 无法运行。

1.1.2 初始化 Python venv（Windows）

在仓库根目录执行：

powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap_venv.ps1

1.1.3 启动网关（建议后台）

powershell -ExecutionPolicy Bypass -File .\scripts\start_gateway.ps1 -SkipInstall -Background

访问：

Admin：http://127.0.0.1:8787/admin
Chat：http://127.0.0.1:8787/chat

停止网关（如果遇到“端口被占用 / 重启不生效”，务必加 -Force）：

powershell -ExecutionPolicy Bypass -File .\scripts\stop_gateway.ps1 -Force

1.1.4 安装官方微信插件（Personal WeChat）

这一步会安装/更新微信 sidecar 运行时到：data/channel_sidecar/oclaw-weixin/

powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\weixin_install.ps1

1.1.5 扫码登录（绑定账号）

powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\weixin_login.ps1

按提示扫码完成绑定（会写入账号 ID / token 等状态到 data/channel_sidecar/oclaw-weixin/state/）。

说明：weixin_install.ps1 不要求你全局安装 openclaw（不需要 npm install -g openclaw）。脚本会在 data/channel_sidecar/oclaw-weixin/ 下安装本地运行时依赖与官方插件包（node_modules），全流程不依赖 %USERPROFILE%\.openclaw。

1.1.6 启动微信 sidecar（原生模式）

powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\weixin_start.ps1

检查状态：

powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\weixin_status.ps1

1.1.7 常见问题

发消息无回复
- 先确认网关活着：访问 http://127.0.0.1:8787/health 应返回 {"ok":"1"}
- 再看微信 sidecar 日志：
  - data/channel_sidecar/oclaw-weixin/logs/weixin_sidecar.log
  - data/channel_sidecar/oclaw-weixin/logs/weixin_sidecar.err.log
启动网关提示端口占用 / 你以为重启了但没生效
- 用 stop_gateway.ps1 -Force 强制按端口清理旧监听进程，然后再启动。
Node 版本不对
- 官方插件要求 node >=22；请升级 Node 后重新执行 weixin_install.ps1。

2. 首次初始化

Windows:

powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap_venv.ps1

Linux/macOS:

./scripts/start_ops.sh

3. 配置企业微信（Bot 模式）

在网关启动后，统一在管理台完成通道配置，不再使用旧 CLI 命令入口。

4. 启停运行栈

启动：

powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background

开源默认友好行为：若本机尚未安装微信/WhatsApp sidecar，start_all.ps1 会自动跳过对应通道并打印 [WARN] ... sidecar skipped，不会中断 gateway + desktop 启动。

默认即包含微信 sidecar：

powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background

不启动微信 sidecar（可选）：

powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background -WithoutWeixin

不启动 WhatsApp sidecar（可选）：

powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background -WithoutWhatsApp

（含 wiki worker）：

powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background -WithWikiWorker

查看状态：

powershell -ExecutionPolicy Bypass -File .\scripts\status_all.ps1

默认即包含微信 sidecar：

powershell -ExecutionPolicy Bypass -File .\scripts\status_all.ps1

不检查微信 sidecar（可选）：

powershell -ExecutionPolicy Bypass -File .\scripts\status_all.ps1 -WithoutWeixin

不检查 WhatsApp sidecar（可选）：

powershell -ExecutionPolicy Bypass -File .\scripts\status_all.ps1 -WithoutWhatsApp

（含 wiki worker）：

powershell -ExecutionPolicy Bypass -File .\scripts\status_all.ps1 -WithWikiWorker

停止：

powershell -ExecutionPolicy Bypass -File .\scripts\stop_all.ps1

默认即包含微信 sidecar：

powershell -ExecutionPolicy Bypass -File .\scripts\stop_all.ps1

不停止微信 sidecar（可选）：

powershell -ExecutionPolicy Bypass -File .\scripts\stop_all.ps1 -WithoutWeixin

不停止 WhatsApp sidecar（可选）：

powershell -ExecutionPolicy Bypass -File .\scripts\stop_all.ps1 -WithoutWhatsApp

（含 wiki worker）：

powershell -ExecutionPolicy Bypass -File .\scripts\stop_all.ps1 -WithWikiWorker

说明：

stack up 不会启动 Streamlit
聊天页面统一使用 http://127.0.0.1:8787/chat
--with-ui 为历史参数，不再生效

4.1 微信（Personal WeChat）当前接入模式

当前默认链路已经切到“官方插件优先”：

官方插件模块负责：
- 扫码登录
- 持久化账号 ID / bot token / context token
- 直接调用微信云端 ilink/bot/getupdates、ilink/bot/sendmessage
- 复用官方媒体下载/上传实现
本仓库宿主适配负责：
- 把官方入站消息转换成 oclaw 可消费的本地 payload
- 通过本地 /weixin/native/reply 同步生成回复

对应脚本行为：

runtime/operations/scripts/weixin_install.ps1
- 安装官方 openclaw-weixin 插件
- 安装运行官方模块所需的本地 Node 依赖
- 同步 runtime/operations/weixin_bridge/official_runner.ts / login.ts
runtime/operations/scripts/weixin_start.ps1
- 仅启动 official_runner.ts（官方单链路）

现阶段主路径建议：

官方登录态
官方收发与媒体模块
本仓库本地 reply 宿主适配

Admin 可视化调度（新增）：

Stack 页面提供 Weixin dispatch 控制卡。
可直接选择专家并执行：
- 绑定专家（写入 expert + specialist）
- 综合（写入 comprehensive + specialist）
通道默认值：expert + generalist。

账号级调度（新增）：

在 用户/渠道绑定 页面选择 channel=weixin 后，可按账号配置：
- 专家（默认 generalist）
- 模式：绑定专家 / 综合
生效优先级：账号级配置 > 通道全局配置 > 默认值。

注意：当模型侧返回“OpenAI key 缺失”兜底文本时，微信通道会静默抑制该类回复（不向微信用户下发错误文案）。

4.2 WhatsApp（实验接入）

当前默认链路为 本仓库自研 WhatsApp Web（Baileys）sidecar（不依赖 openclaw）：

runtime/operations/scripts/whatsapp_install.ps1
runtime/operations/scripts/whatsapp_login.ps1
runtime/operations/scripts/whatsapp_start.ps1
runtime/operations/scripts/whatsapp_status.ps1
runtime/operations/scripts/whatsapp_stop.ps1

常用命令：

powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\whatsapp_install.ps1
powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\whatsapp_login.ps1
powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\whatsapp_start.ps1
powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\whatsapp_status.ps1
powershell -ExecutionPolicy Bypass -File .\runtime\operations\scripts\whatsapp_stop.ps1

说明：

whatsapp_login.ps1 会在控制台打印二维码，请用 WhatsApp 手机端的“关联设备”扫码完成绑定。
登录态会落盘在 data/channel_sidecar/whatsapp/state/auth/，重启后无需重复扫码。
sidecar 收到消息后会调用本地网关 POST /inbound/whatsapp 获取 replies[] 并回发。

Admin 可视化调度（新增）：

Stack 页面提供 WhatsApp dispatch 控制卡（绑定专家 / 综合）。
用户/渠道绑定 页面选择 channel=whatsapp 后可按账号单独配置专家/模式。
默认值同微信：expert + generalist。

5. 仅启动网关

powershell -ExecutionPolicy Bypass -File .\scripts\start_gateway.ps1

6. 管理台与认证

先启动网关，再访问：

http://127.0.0.1:8787/admin
http://127.0.0.1:8787/chat

7. Admin Chat：WS 请求超时（`ws_send_timeout:*`）

现象：

管理台聊天页流式请求中途提示：请求失败: Error: ws_send_timeout:180000（或其他毫秒值）

说明：

这是前端在 interfaces/admin/static/chat.js 中实现的 WS “无活动超时”看门狗（不是后端限流/超时）。
触发条件通常为：在指定毫秒窗口内（默认曾为 180000ms）没有收到任何 WS 活动（delta / event / ack 等）。
某些模型/网关可能会出现“长时间无增量、最终一次性返回”的情况，此时该看门狗会误判并提前报错。

当前默认行为：

默认已禁用（WS_CHAT_SEND_TIMEOUT_MS = 0）。

如何调整：

修改 interfaces/admin/static/chat.js 中常量 WS_CHAT_SEND_TIMEOUT_MS：
- 0：禁用
- > 0：启用并作为无活动超时毫秒数

6.1 初始化管理员（幂等）

curl -X POST http://127.0.0.1:8787/admin/api/auth/bootstrap

6.2 登录获取 Bearer Token

curl -X POST http://127.0.0.1:8787/admin/api/auth/login \
  -H "content-type: application/json" \
  -d '{"tenant_id":"<tenant_id>","username":"administrator","password":"<pwd>","purpose":"console"}'

6.3 带 Token 调用受保护接口

curl http://127.0.0.1:8787/admin/api/users?tenant_id=<tenant_id> \
  -H "authorization: Bearer <token>"

RBAC 规则要点：

owner 拥有完整管理权限
其它角色权限由 role_permission + user_permission 决定
跨租户写操作会被拒绝（403）

6.4 `/chat` 会话与用户隔离（排障）

Admin Chat 依赖表 ui_session_owner（session_id → tenant_id + user_id）判定「谁可见、谁可写」某条 chat_session。列表、读消息、流式回复、停止生成、导出等均经该归属校验。

请勿依赖的历史行为（已移除）

用户会话列表为空时，不再自动把库内所有「无 owner」会话划给该用户（否则多用户会互相看到对方会话）。
读取某 session_id 时，不会再「若无 owner 则绑定到当前请求用户」（否则谁先打开链接谁抢走归属）。

若升级后有人看不到旧会话

说明这些 chat_session 从未写入 ui_session_owner（列表与读接口均只认该表）。处理方式（需在维护窗口评估数据归属）：

自行 SQL 排查：SELECT s.id, s.title, s.created_at FROM chat_session s LEFT JOIN ui_session_owner o ON o.session_id = s.id WHERE o.session_id IS NULL; 确认归属后按需 INSERT INTO ui_session_owner(session_id, tenant_id, user_id, created_at) VALUES (...)。
在 Python 控制台 仅在确认整库孤儿会话均属同一用户时，可显式调用 SqliteStore.backfill_orphan_chat_sessions_for_user（该方法会一次性把当前仍无 owner 的全部会话绑到传入的 user_id，不适合多用户已混用生产库）。
administrator 在 /chat 侧边栏与普通用户相同，只列出 自己名下（ui_session_owner.user_id = 管理员账号）的会话，不会把他人会话混进自己的列表。查看本租户全部会话请用 审计 / Session Monitor 或接口 GET /admin/api/chat/admin/sessions（需相应权限）。单会话消息读写在管理员仍可按租户校验（便于从监控打开指定 session_id）。

浏览器端

独立 /chat 页在检测到 登录租户/用户 与上次不一致时会丢弃 URL 中的 ?session_id=，避免同一浏览器换账号后仍打开上一用户的深链。

工作区 extra_roots（与编排临时会话）

管理台为用户配置的 user_workspace_path_allowlist.extra_roots 通过 ui_session_owner 解析到租户+用户。全能者编排里专家步往往在无 owner 的临时 chat_session 上落库中间消息：内置路径类工具会携带 用户 UI 会话 id 作为 fallback，仍按该用户策略合并 extra_roots；MCP filesystem 启动参数本就按用户聊天 session_id（policy）合并，二者现已对齐。

6.5 主库路径与「删掉的会话又回来了 / 新建用户不见了」

默认主库为 data/ai_ops.sqlite（未设置 OPS_ASSISTANT_DB_PATH 时）。历史上曾把库放在 ../data/ai_ops.sqlite 或 oclaw/platform/data/ai_ops.sqlite；首次启动若检测到这些旧位置且新主库尚不存在，会把整库复制到 data/ai_ops.sqlite，并把旧路径下的附件补拷到 data/attachments/（不覆盖已有文件）。确认新主库生效后，本机可按需清理旧目录（避免磁盘上留着陈旧副本）。

历史上若旧库里的 chat_session 行数大于当前主库，会用整份旧库覆盖主库。用户大量删除会话后主库行数变少，会误触发该逻辑，表现为：已删会话从旧快照恢复、只在主库里出现的新用户/新数据被整库覆盖掉。

当前版本已关闭该自动覆盖；仅当显式设置环境变量 OPS_LEGACY_DB_FORCE_PREMERGE=1 时才允许按旧规则合并（仍会先把当前主库备份到 data/_pre_merge_sqlite_<时间戳>/）。

排障建议：确认所有网关/进程使用同一 OPS_ASSISTANT_DB_PATH（或统一依赖默认 data/ai_ops.sqlite）；若曾出现覆盖，可在 data/_pre_merge_sqlite_* 中找回被备份出去的主库副本。

7. 常用脚本入口

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\start_gateway.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\status_all.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\stop_gateway.ps1
（联动）powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background
（联动）powershell -ExecutionPolicy Bypass -File .\scripts\stop_all.ps1

Linux/macOS:

./scripts/start_ops.sh
./scripts/status_ops.sh
./scripts/stop_ops.sh

8. MCP 运维流程（管理台）

推荐顺序：

Install（或 Reinstall）
Health
Sync Tools
Check Installed（批量体检）

若失败，重点看错误码：

mcp_runtime_timeout
mcp_runtime_protocol_mismatch
mcp_runtime_bad_json
mcp_tools_list_invalid

详细开发与接入参考：docs/MCP_LOCAL_SERVER.md

8.1 `images-mcp`（Windows）安装与 Health 通过指引

现象：

Install 显示成功，但 Health 报错：mcp_runtime_empty_response
手动执行 npx -y images-mcp 只输出 CLI 帮助并退出

根因：

images-mcp 的 npm bin 入口默认是 CLI（cli.ts），不是 MCP stdio 服务入口。
健康检查要求进程保持 MCP JSON-RPC（stdio）模式；CLI 进程会立即退出，导致空响应。

前置检查（PowerShell）：

where bun
where bunx
bun --version
bunx --version

若 where bun 无结果，先安装/修复 Bun，再重启终端与网关进程。

推荐安装方式（本地 runtime 目录）：

mkdir D:\tools\images-mcp-runtime -Force
cd D:\tools\images-mcp-runtime
npm init -y
npm install images-mcp

将 MCP Server 启动配置改为（管理台或数据库）：

entry_command: powershell
entry_args: ["-NoProfile","-Command","Set-Location D:\\tools\\images-mcp-runtime; bun run node_modules/images-mcp/mcp.ts"]

预期结果：

手动验证启动命令时，会看到 Images MCP server running on stdio
管理台 Health 返回 ok
Sync Tools 后应看到 2 个工具（OpenAI / Gemini）

排障补充：

若仍失败，优先检查 entry_args 是否仍是 npx -y images-mcp（该配置会回到 CLI 模式，Health 继续失败）。
若提示找不到 bun，确认网关进程启动时的 PATH 已包含 C:\Users\<用户名>\.bun\bin。

9. 向量记忆配置（可选）

可通过环境变量或管理台配置：

MEMORY_VECTOR_ENABLED (0/1)
MEMORY_VECTOR_BACKEND (sqlite / chroma / qdrant)
MEMORY_VECTOR_TOPK（默认 5）
MEMORY_WRITE_ENABLED (0/1)
MEMORY_WRITE_MIN_CONFIDENCE（默认 0.75）

故障降级策略：

向量后端不可用时，读写回退到 SQLite 向量实现
关闭写入时，不影响聊天主流程

10. 常见故障速查

10.1 管理台无法登录

是否设置 AIA_ASSISTANT_PASSWORD
是否重启服务并让新环境变量生效

10.2 MCP 显示可用但工具数为 0

先执行 Health
再执行 Sync Tools
再执行 Check Installed

10.3 Check Installed 全红

检查 server 是否输出标准 JSON-RPC（stdout）
日志必须写 stderr，避免协议污染
确认 entry_command/entry_args 正确

10.4 微信能收不能回 / 回不去

按顺序检查：

网关是否健康（/health 必须快速返回）
sidecar 是否运行（weixin_status.ps1）
sidecar 日志是否有 sendmessage 失败提示（weixin_sidecar.err.log）

如果 8787 端口被僵尸进程占用，先执行：

powershell -ExecutionPolicy Bypass -File .\scripts\stop_gateway.ps1 -Force
powershell -ExecutionPolicy Bypass -File .\scripts\start_gateway.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\weixin_stop.ps1 -Force
powershell -ExecutionPolicy Bypass -File .\scripts\weixin_start.ps1

11. 个人微信（官方 ClawBot）接入

说明：本项目采用「A 模式」接入。微信插件由本地 sidecar 运行，直接调用本地 Python gateway。

前置条件：

微信端已开通并启用 ClawBot 插件
当前目录为 D:/project/chatgpt/oclaw
已安装 Node.js（建议 22+）与 npm
网关可访问：http://127.0.0.1:8787/health

11.1 安装 sidecar 依赖

powershell -ExecutionPolicy Bypass -File .\scripts\weixin_install.ps1

注意：当前仅保留官方插件单链路，直接执行 weixin_install.ps1 即可。且为纯 sidecar 方案：不会写入 %USERPROFILE%\.openclaw\。

安装目录：

data/channel_sidecar/oclaw-weixin/

11.2 扫码登录（获取 bot token）

powershell -ExecutionPolicy Bypass -File .\scripts\weixin_login.ps1

登录态写入：

data/channel_sidecar/oclaw-weixin/state/oclaw-weixin/accounts/*.json
data/channel_sidecar/oclaw-weixin/state/oclaw-weixin/accounts.json
不会写入 %USERPROFILE%\.openclaw\openclaw-weixin\

11.3 启动微信 sidecar

powershell -ExecutionPolicy Bypass -File .\scripts\weixin_start.ps1

查看状态：

powershell -ExecutionPolicy Bypass -File .\scripts\weixin_status.ps1

停止：

powershell -ExecutionPolicy Bypass -File .\scripts\weixin_stop.ps1

日志文件：

data/channel_sidecar/oclaw-weixin/logs/weixin_sidecar.log
data/channel_sidecar/oclaw-weixin/logs/weixin_sidecar.err.log

11.4 当前行为说明

微信回复为“整段返回”，非逐 token 流式
发送前会清理推理/工具痕迹（如 <redacted_thinking>...</redacted_thinking>）
发送前会处理文本换行（含字面量 \n）

12. LLM 回放策略（reasoning / content / tool）

适用范围：oclaw 运行时构建“下一轮发给模型”的消息序列。

12.1 设计原则

content 与 reasoning 分离：正文走 assistant_text，推理走独立 reasoning 事件。
默认不回放推理文本：回放只包含正文 + tool（及必要的配对字段）。
历史兼容：旧数据中若正文含 <think>...</think> 或 <redacted_thinking>...</redacted_thinking>，在回放构建时会剥离。

12.2 工具回放分层

最近 3 轮工具调用保留全量结果。
更早工具结果降级为摘要（保留 tool_call_id 配对信息，避免网关拒绝）。
单条内容仍受现有超长截断限制。

12.3 推理签名白名单（provider 兼容）

只针对“签名元字段”而非推理文本。用于部分 provider 在工具连续调用时保持上下文连续性。

环境变量：AIA_REPLAY_REASONING_SIGNATURE_POLICY

auto（默认）：仅在白名单 provider 路径回放签名元字段（当前包含 Gemini 路径）。
on：所有模型都回放签名元字段（调试/兼容兜底）。
off：完全不回放签名元字段（最严格模式）。

12.4 `.env` 最小配置示例

# 工具回放：最近 3 轮全量（默认 3，可按需调整）
AIA_REPLAY_TOOL_FULL_ROUNDS=3

# 推理签名回放策略：auto / on / off
# 生产建议 auto：仅白名单 provider 回放签名元字段
AIA_REPLAY_REASONING_SIGNATURE_POLICY=auto

13. memory-wiki 插件启用与排障

13.1 启用配置（oclaw.json）

将 memory-wiki 放入启用列表，并建议把 memory slot 指向它：

{
  "plugins": {
    "enabled": ["memory-wiki"],
    "slots": {
      "memory": "memory-wiki"
    },
    "entries": {
      "memory-wiki": {
        "wiki_root": "docs/memory-system/wiki",
        "max_search_results": 20,
        "max_get_lines": 800,
        "auto": {
          "enabled": true,
          "inject": {
            "max_chars": 1800,
            "top_k": 6
          },
          "worker": {
            "enabled": true
          },
          "topic_routing": {
            "rules": [
              {
                "topic": "network",
                "keywords": ["vlan", "router", "switch", "network", "dns", "gateway"]
              },
              {
                "topic": "devops",
                "keywords": ["deploy", "k8s", "kubernetes", "docker", "ci", "ops"]
              },
              {
                "topic": "engineering",
                "keywords": ["bug", "fix", "todo", "feature", "refactor", "test"]
              }
            ]
          }
        }
      }
    }
  }
}

13.2 会话可用工具（预期）

wiki_status
wiki_get
wiki_search
wiki_lint
wiki_apply

13.3 常见故障

invalid_arguments：参数缺失或 path 非 .md / 越界到 wiki 根目录外。
wiki_not_found：目标文件不存在（wiki_get / wiki_apply delete）。
invalid_action：wiki_apply 的 action 仅支持 write|append|delete。
wiki_runtime_error：运行期异常（编码、权限、IO），先检查路径权限与文件占用。

13.4 回退方案

临时禁用 wiki 插件：从 plugins.enabled 移除 memory-wiki 后重启 gateway。
或仅关闭 memory slot：plugins.slots.memory 设为 "none"（保留插件安装但不作为 memory 槽位）。

13.5 自动化链路自检（smoke test）

在 gateway + wiki worker 运行时，执行：

python .\scripts\wiki_auto_smoke_test.py

该脚本会：

投递一条 wiki_capture 任务到 oclaw_task
轮询任务状态直到 done/failed/timeout
输出当前写入产物状态（merged-turns.md、topic-index.json、index.json、LINT_REPORT.md）

25 KiB Raw Blame History Unescape Escape

运行手册（RUNBOOK）

1. 统一入口（只保留最新）

1.1 开源快速安装（从零到跑起来）

1.1.1 前置依赖

1.1.2 初始化 Python venv（Windows）

1.1.3 启动网关（建议后台）

1.1.4 安装官方微信插件（Personal WeChat）

1.1.5 扫码登录（绑定账号）

1.1.6 启动微信 sidecar（原生模式）

1.1.7 常见问题

2. 首次初始化

3. 配置企业微信（Bot 模式）

4. 启停运行栈

4.1 微信（Personal WeChat）当前接入模式

4.2 WhatsApp（实验接入）

5. 仅启动网关

6. 管理台与认证

7. Admin Chat：WS 请求超时（ws_send_timeout:*）

6.1 初始化管理员（幂等）

6.2 登录获取 Bearer Token

6.3 带 Token 调用受保护接口

6.4 /chat 会话与用户隔离（排障）

6.5 主库路径与「删掉的会话又回来了 / 新建用户不见了」

7. 常用脚本入口

8. MCP 运维流程（管理台）

8.1 images-mcp（Windows）安装与 Health 通过指引

9. 向量记忆配置（可选）

10. 常见故障速查

10.1 管理台无法登录

10.2 MCP 显示可用但工具数为 0

10.3 Check Installed 全红

10.4 微信能收不能回 / 回不去

11. 个人微信（官方 ClawBot）接入

11.1 安装 sidecar 依赖

11.2 扫码登录（获取 bot token）

11.3 启动微信 sidecar

11.4 当前行为说明

12. LLM 回放策略（reasoning / content / tool）

12.1 设计原则

12.2 工具回放分层

12.3 推理签名白名单（provider 兼容）

12.4 .env 最小配置示例

13. memory-wiki 插件启用与排障

13.1 启用配置（oclaw.json）

13.2 会话可用工具（预期）

13.3 常见故障

13.4 回退方案

13.5 自动化链路自检（smoke test）

25 KiB

Raw Blame History

7. Admin Chat：WS 请求超时（`ws_send_timeout:*`）

6.4 `/chat` 会话与用户隔离（排障）

8.1 `images-mcp`（Windows）安装与 Health 通过指引

12.4 `.env` 最小配置示例