oclaw/docs/RUNBOOK.md

运行手册（RUNBOOK）

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

关联文档：

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

---

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

所有运维命令统一通过 scripts/，不要再使用 python -m oclaw.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 通过。

---

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

（含微信 sidecar）：

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

（含微信 sidecar + wiki worker）：

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

查看状态：

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

（含微信 sidecar）：

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

（含微信 sidecar + wiki worker）：

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

停止：

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

（含微信 sidecar）：

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

（含微信 sidecar + wiki worker）：

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

说明：

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

---

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（列表与读接口均只认该表）。处理方式（需在维护窗口评估数据归属）：

1. 自行 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 (...)。
2. 在 Python 控制台 仅在确认整库孤儿会话均属同一用户时，可显式调用 SqliteStore.backfill_orphan_chat_sessions_for_user（该方法会一次性把当前仍无 owner 的全部会话绑到传入的 user_id，不适合多用户已混用生产库）。
3. 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 运维流程（管理台）

推荐顺序：

1. Install（或 Reinstall）
2. Health
3. Sync Tools
4. 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 微信能收不能回 / 回不去

按顺序检查：

1. 网关是否健康（/health 必须快速返回）
2. sidecar 是否运行（weixin_status.ps1）
3. 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

注意：

• 脚本支持两种模式：

  • 官方插件模式：-UseOpenclawCli（不校验 runner.ts/login.ts）
  • 本地 sidecar 模式：-LocalSourcePath（会强校验 runner.ts/login.ts）

• 默认按本地 sidecar 模式处理：必须传 -LocalSourcePath（指向你们自研 weixin sidecar 源码目录）。

powershell -ExecutionPolicy Bypass -File .\scripts\weixin_install.ps1 -LocalSourcePath "D:\path\to\your-weixin-module"

• 若你要临时切回官方链路，可显式指定：

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

• 仅本地 sidecar 模式会强校验 runner.ts / login.ts 是否存在；官方插件模式不做该校验。

安装目录：

• 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

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：完全不回放签名元字段（最严格模式）。

推荐：

• 常规生产：保持默认 auto。
• 若遇到特定模型 tool-loop 连续性问题：临时设为 on 验证，再收敛到最小白名单。

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）

---