1 line
367 KiB
JSON
1 line
367 KiB
JSON
{"repo": "ai45lab/clawsentry", "files": {"site-docs/operations/troubleshooting.md": {"2a3a826bb731cb18db88f84be9a6dd3974a321f9": {"t": 1785746525.2354927, "n": 22163, "h": "c3be16411946cadd", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n<section class=\"cs-doc-hero cs-doc-hero--ops\" markdown>\n<div class=\"cs-eyebrow\">ClawSentry 运维</div>\n## 故障排查\n常见问题诊断与解决方案，覆盖启动错误、连接失败和 hook 集成问题。\n<div class=\"cs-actions\" markdown>\n[生产部署](deployment.md){ .md-button .md-button--primary }\n[Benchmark 模式](benchmark-mode.md){ .md-button }\n[CLI 命令](../cli/index.md){ .md-button }\n</div>\n</section>\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 配置来源与 env-file\n\n??? question \"`.clawsentry.env.local` / `.env.clawsentry` 中的配置没有生效\"\n\n **症状**：`CS_AUTH_TOKEN` 为空、LLM provider 未加载、端口/预算仍是默认值，或 `config show --effective` 显示来源不是你预期的文件。\n\n **诊断**：\n ```bash\n clawsentry config show --effective --env-file .clawsentry.env.local\n clawsentry config show --effective --env-file .env.clawsentry # 仅迁移旧文件时使用\n ```\n\n **原因**：\n\n 1. 没有自动发现的 ClawSentry env file；`.clawsentry.env.example` 也必须显式传入。\n 2. `.clawsentry.env.local` 和旧 `.env.clawsentry` 都不会自动加载；必须显式 `--env-file PATH` 或设置 `CLAWSENTRY_ENV_FILE=PATH`。\n 3. 进程/部署环境变量优先于 env-file；如果 shell 已经 export 同名 `CS_*`，文件中的值不会覆盖它。\n 4. `CS_FRAMEWORK` / `CS_ENABLED_FRAMEWORKS` 只用于旧脚本迁移，框架启用请看 `CS_FRAMEWORK / CS_ENABLED_FRAMEWORKS`。\n\n **解决方案**：\n ```bash\n clawsentry start --env-file .clawsentry.env.local\n clawsentry test-llm --env-file .clawsentry.env.local --json\n clawsentry doctor --env-file .clawsentry.env.local\n ```\n\n 如果只是本地体验且未设置 `CS_AUTH_TOKEN`，`clawsentry start` 会生成仅本次进程内有效的临时 token，并在启动 banner / Web UI URL 中展示；它不会写入 env file。\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY = sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN = your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN = $CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保进程环境或显式 `--env-file` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致；若未设置 token，请复制本次 `start` banner 打印的 URL/token\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM token budget exhausted；基于 provider 真实 usage 降级/阻断，旧 `CS_LLM_DAILY_BUDGET_USD` 仅兼容提示 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "7142b814512b95d716a2fa98bef5e33bd5578bc9": {"t": 1785765292.2331958, "n": 22163, "h": "c3be16411946cadd", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n<section class=\"cs-doc-hero cs-doc-hero--ops\" markdown>\n<div class=\"cs-eyebrow\">ClawSentry 运维</div>\n## 故障排查\n常见问题诊断与解决方案，覆盖启动错误、连接失败和 hook 集成问题。\n<div class=\"cs-actions\" markdown>\n[生产部署](deployment.md){ .md-button .md-button--primary }\n[Benchmark 模式](benchmark-mode.md){ .md-button }\n[CLI 命令](../cli/index.md){ .md-button }\n</div>\n</section>\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 配置来源与 env-file\n\n??? question \"`.clawsentry.env.local` / `.env.clawsentry` 中的配置没有生效\"\n\n **症状**：`CS_AUTH_TOKEN` 为空、LLM provider 未加载、端口/预算仍是默认值，或 `config show --effective` 显示来源不是你预期的文件。\n\n **诊断**：\n ```bash\n clawsentry config show --effective --env-file .clawsentry.env.local\n clawsentry config show --effective --env-file .env.clawsentry # 仅迁移旧文件时使用\n ```\n\n **原因**：\n\n 1. 没有自动发现的 ClawSentry env file；`.clawsentry.env.example` 也必须显式传入。\n 2. `.clawsentry.env.local` 和旧 `.env.clawsentry` 都不会自动加载；必须显式 `--env-file PATH` 或设置 `CLAWSENTRY_ENV_FILE=PATH`。\n 3. 进程/部署环境变量优先于 env-file；如果 shell 已经 export 同名 `CS_*`，文件中的值不会覆盖它。\n 4. `CS_FRAMEWORK` / `CS_ENABLED_FRAMEWORKS` 只用于旧脚本迁移，框架启用请看 `CS_FRAMEWORK / CS_ENABLED_FRAMEWORKS`。\n\n **解决方案**：\n ```bash\n clawsentry start --env-file .clawsentry.env.local\n clawsentry test-llm --env-file .clawsentry.env.local --json\n clawsentry doctor --env-file .clawsentry.env.local\n ```\n\n 如果只是本地体验且未设置 `CS_AUTH_TOKEN`，`clawsentry start` 会生成仅本次进程内有效的临时 token，并在启动 banner / Web UI URL 中展示；它不会写入 env file。\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY = sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN = your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN = $CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保进程环境或显式 `--env-file` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致；若未设置 token，请复制本次 `start` banner 打印的 URL/token\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM token budget exhausted；基于 provider 真实 usage 降级/阻断，旧 `CS_LLM_DAILY_BUDGET_USD` 仅兼容提示 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "34bed15baf9e7a7dc93b8170b04909af1c2645f6": {"t": 1785765296.0971904, "n": 22162, "h": "63e300226ceb245b", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n<section class=\"cs-doc-hero cs-doc-hero--ops\" markdown>\n<div class=\"cs-eyebrow\">ClawSentry 运维</div>\n## 故障排查\n常见问题诊断与解决方案，覆盖启动错误、连接失败和 hook 集成问题。\n<div class=\"cs-actions\" markdown>\n[生产部署](deployment.md){ .md-button .md-button--primary }\n[Benchmark 模式](benchmark-mode.md){ .md-button }\n[CLI 命令](../cli/index.md){ .md-button }\n</div>\n</section>\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 配置来源与 env-file\n\n??? question \"`.clawsentry.env.local` / `.env.clawsentry` 中的配置没有生效\"\n\n **症状**：`CS_AUTH_TOKEN` 为空、LLM provider 未加载、端口/预算仍是默认值，或 `config show --effective` 显示来源不是你预期的文件。\n\n **诊断**：\n ```bash\n clawsentry config show --effective --env-file .clawsentry.env.local\n clawsentry config show --effective --env-file .env.clawsentry # 仅迁移旧文件时使用\n ```\n\n **原因**：\n\n 1. 没有自动发现的 ClawSentry env file；`.clawsentry.env.example` 也必须显式传入。\n 2. `.clawsentry.env.local` 和旧 `.env.clawsentry` 都不会自动加载；必须显式 `--env-file PATH` 或设置 `CLAWSENTRY_ENV_FILE=PATH`。\n 3. 进程/部署环境变量优先于 env-file；如果 shell 已经 export 同名 `CS_*`，文件中的值不会覆盖它。\n 4. `CS_FRAMEWORK` / `CS_ENABLED_FRAMEWORKS` 只用于旧脚本迁移，框架启用请看 `CS_FRAMEWORK / CS_ENABLED_FRAMEWORKS`。\n\n **解决方案**：\n ```bash\n clawsentry start --env-file .clawsentry.env.local\n clawsentry test-llm --env-file .clawsentry.env.local --json\n clawsentry doctor --env-file .clawsentry.env.local\n ```\n\n 如果只是本地体验且未设置 `CS_AUTH_TOKEN`，`clawsentry start` 会生成仅本次进程内有效的临时 token，并在启动 banner / Web UI URL 中展示；它不会写入 env file。\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY = <openai-api-key>\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=<anthropic-api-key>\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN = your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN = $CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保进程环境或显式 `--env-file` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致；若未设置 token，请复制本次 `start` banner 打印的 URL/token\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM token budget exhausted；基于 provider 真实 usage 降级/阻断，旧 `CS_LLM_DAILY_BUDGET_USD` 仅兼容提示 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "6f2af117e622318dc7d4fa48064ab3c8cbb8c3ef": {"t": 1785765299.6051195, "n": 22163, "h": "c3be16411946cadd", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n<section class=\"cs-doc-hero cs-doc-hero--ops\" markdown>\n<div class=\"cs-eyebrow\">ClawSentry 运维</div>\n## 故障排查\n常见问题诊断与解决方案，覆盖启动错误、连接失败和 hook 集成问题。\n<div class=\"cs-actions\" markdown>\n[生产部署](deployment.md){ .md-button .md-button--primary }\n[Benchmark 模式](benchmark-mode.md){ .md-button }\n[CLI 命令](../cli/index.md){ .md-button }\n</div>\n</section>\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 配置来源与 env-file\n\n??? question \"`.clawsentry.env.local` / `.env.clawsentry` 中的配置没有生效\"\n\n **症状**：`CS_AUTH_TOKEN` 为空、LLM provider 未加载、端口/预算仍是默认值，或 `config show --effective` 显示来源不是你预期的文件。\n\n **诊断**：\n ```bash\n clawsentry config show --effective --env-file .clawsentry.env.local\n clawsentry config show --effective --env-file .env.clawsentry # 仅迁移旧文件时使用\n ```\n\n **原因**：\n\n 1. 没有自动发现的 ClawSentry env file；`.clawsentry.env.example` 也必须显式传入。\n 2. `.clawsentry.env.local` 和旧 `.env.clawsentry` 都不会自动加载；必须显式 `--env-file PATH` 或设置 `CLAWSENTRY_ENV_FILE=PATH`。\n 3. 进程/部署环境变量优先于 env-file；如果 shell 已经 export 同名 `CS_*`，文件中的值不会覆盖它。\n 4. `CS_FRAMEWORK` / `CS_ENABLED_FRAMEWORKS` 只用于旧脚本迁移，框架启用请看 `CS_FRAMEWORK / CS_ENABLED_FRAMEWORKS`。\n\n **解决方案**：\n ```bash\n clawsentry start --env-file .clawsentry.env.local\n clawsentry test-llm --env-file .clawsentry.env.local --json\n clawsentry doctor --env-file .clawsentry.env.local\n ```\n\n 如果只是本地体验且未设置 `CS_AUTH_TOKEN`，`clawsentry start` 会生成仅本次进程内有效的临时 token，并在启动 banner / Web UI URL 中展示；它不会写入 env file。\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY = sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN = your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN = $CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保进程环境或显式 `--env-file` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致；若未设置 token，请复制本次 `start` banner 打印的 URL/token\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM token budget exhausted；基于 provider 真实 usage 降级/阻断，旧 `CS_LLM_DAILY_BUDGET_USD` 仅兼容提示 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "1a4c27be628fb3d9beaf5cb8708d788281ae653c": {"t": 1785765302.2684946, "n": 21830, "h": "cbc0328434a7cc8b", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 配置来源与 env-file\n\n??? question \"`.clawsentry.env.local` / `.env.clawsentry` 中的配置没有生效\"\n\n **症状**：`CS_AUTH_TOKEN` 为空、LLM provider 未加载、端口/预算仍是默认值，或 `config show --effective` 显示来源不是你预期的文件。\n\n **诊断**：\n ```bash\n clawsentry config show --effective --env-file .clawsentry.env.local\n clawsentry config show --effective --env-file .env.clawsentry # 仅迁移旧文件时使用\n ```\n\n **原因**：\n\n 1. 没有自动发现的 ClawSentry env file；`.clawsentry.env.example` 也必须显式传入。\n 2. `.clawsentry.env.local` 和旧 `.env.clawsentry` 都不会自动加载；必须显式 `--env-file PATH` 或设置 `CLAWSENTRY_ENV_FILE=PATH`。\n 3. 进程/部署环境变量优先于 env-file；如果 shell 已经 export 同名 `CS_*`，文件中的值不会覆盖它。\n 4. `CS_FRAMEWORK` / `CS_ENABLED_FRAMEWORKS` 只用于旧脚本迁移，框架启用请看 `CS_FRAMEWORK / CS_ENABLED_FRAMEWORKS`。\n\n **解决方案**：\n ```bash\n clawsentry start --env-file .clawsentry.env.local\n clawsentry test-llm --env-file .clawsentry.env.local --json\n clawsentry doctor --env-file .clawsentry.env.local\n ```\n\n 如果只是本地体验且未设置 `CS_AUTH_TOKEN`，`clawsentry start` 会生成仅本次进程内有效的临时 token，并在启动 banner / Web UI URL 中展示；它不会写入 env file。\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY = sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN = your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN = $CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保进程环境或显式 `--env-file` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致；若未设置 token，请复制本次 `start` banner 打印的 URL/token\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM token budget exhausted；基于 provider 真实 usage 降级/阻断，旧 `CS_LLM_DAILY_BUDGET_USD` 仅兼容提示 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "6c4daf9674951fe4e5b24b1a6a388fca35f372ae": {"t": 1785765306.6910994, "n": 21787, "h": "45d44a9efaf6b644", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 配置来源与 env-file\n\n??? question \"`.clawsentry.env.local` / `.env.clawsentry` 中的配置没有生效\"\n\n **症状**：`CS_AUTH_TOKEN` 为空、LLM provider 未加载、端口/预算仍是默认值，或 `config show --effective` 显示来源不是你预期的文件。\n\n **诊断**：\n ```bash\n clawsentry config show --effective --env-file .clawsentry.env.local\n clawsentry config show --effective --env-file .env.clawsentry # 仅迁移旧文件时使用\n ```\n\n **原因**：\n\n 1. `.clawsentry.toml` 是唯一自动发现的项目配置。\n 2. `.clawsentry.env.local` 和旧 `.env.clawsentry` 都不会自动加载；必须显式 `--env-file PATH` 或设置 `CLAWSENTRY_ENV_FILE=PATH`。\n 3. 进程/部署环境变量优先于 env-file；如果 shell 已经 export 同名 `CS_*`，文件中的值不会覆盖它。\n 4. `CS_FRAMEWORK` / `CS_ENABLED_FRAMEWORKS` 只用于旧脚本迁移，框架启用请看 `.clawsentry.toml [frameworks]`。\n\n **解决方案**：\n ```bash\n clawsentry start --env-file .clawsentry.env.local\n clawsentry test-llm --env-file .clawsentry.env.local --json\n clawsentry doctor --env-file .clawsentry.env.local\n ```\n\n 如果只是本地体验且未设置 `CS_AUTH_TOKEN`，`clawsentry start` 会生成仅本次进程内有效的临时 token，并在启动 banner / Web UI URL 中展示；它不会写入 env file。\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN=$CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保进程环境或显式 `--env-file` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致；若未设置 token，请复制本次 `start` banner 打印的 URL/token\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM token budget exhausted；基于 provider 真实 usage 降级/阻断，旧 `CS_LLM_DAILY_BUDGET_USD` 仅兼容提示 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "ada085c44e2810cd3829c50645f0c7a035a45363": {"t": 1785765309.088266, "n": 20698, "h": "d8d71ea96e319970", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN=$CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保 `.env.clawsentry` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM token budget exhausted；基于 provider 真实 usage 降级/阻断，旧 `CS_LLM_DAILY_BUDGET_USD` 仅兼容提示 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "2dd2f82ad0ec698dd1ba5893ec245dd8f1e5b3d8": {"t": 1785765311.6549525, "n": 20653, "h": "fb8393d7e8596d79", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n - 如果页面提示 `Gateway unavailable`，先检查 Gateway 是否启动、端口是否正确以及本机代理是否拦截；这不是 bad token\n - 代理环境下为本机 Gateway 设置：`export NO_PROXY=localhost,127.0.0.1,::1`\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN=$CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保 `.env.clawsentry` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM 日费用超出 CS_LLM_DAILY_BUDGET_USD 限额，降级 L1 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "4211f42b43546960004cd10119d4d4331f086f4a": {"t": 1785765315.501397, "n": 20496, "h": "7ecd426af7d24547", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n??? question \"已启用自进化模式库，但一直看不到候选模式或确认结果\"\n\n **症状**：已经设置 `CS_EVOLVING_ENABLED=true`，但 `clawsentry watch`、SSE 或 `/ahp/patterns` 看不到 `pattern_candidate` / `pattern_evolved` 事件，列表也始终为空。\n\n **诊断**：\n ```bash\n echo $CS_EVOLVING_ENABLED\n echo $CS_EVOLVED_PATTERNS_PATH\n\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/ahp/patterns\n\n curl -N -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n \"http://127.0.0.1:8080/report/stream?types=pattern_candidate,pattern_evolved\"\n ```\n\n **解决方案**：\n\n 1. **先看 `/ahp/patterns` 顶层状态字段**：\n - `enabled=false`：说明 Gateway 当前并未启用自进化模式库。\n - `store_path=\"\"`：说明没有配置持久化路径。\n - `count=0` 且 `candidate_count=0`：说明还没有候选模式被成功提取。\n\n 2. **确认功能确实已启用且可持久化**：\n ```bash\n export CS_EVOLVING_ENABLED=true\n export CS_EVOLVED_PATTERNS_PATH=/var/lib/clawsentry/evolved_patterns.yaml\n ```\n `CS_EVOLVED_PATTERNS_PATH` 所在目录必须对 Gateway 进程可写；否则候选模式无法落盘。\n\n 3. **确认触发条件满足**：\n 只有在自进化已启用时，且事件被判为 `high` / `critical`，Gateway 才会提取候选模式并广播 `pattern_candidate`。普通 `low` / `medium` 事件不会触发。\n\n 4. **区分“候选已提取”和“模式已确认”**：\n - `pattern_candidate`：说明刚刚提取出候选模式。\n - `pattern_evolved`：说明有人通过 `POST /ahp/patterns/confirm` 提交了确认/误报反馈，状态发生了生命周期变化。\n\n 5. **手动确认反馈链路**：\n ```bash\n curl -X POST http://127.0.0.1:8080/ahp/patterns/confirm \\\n -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern_id\":\"EV-XXXXXXXX\",\"confirmed\":true}'\n ```\n 成功后应看到 `pattern_evolved` 事件，同时 `/ahp/patterns` 中对应模式的 `status`、`confirmed_count`、`candidate_count` / `active_count` 会变化。\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN=$CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保 `.env.clawsentry` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM 日费用超出 CS_LLM_DAILY_BUDGET_USD 限额，降级 L1 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "747c60784a50d2fe9b64ee35058784b4db13f1d2": {"t": 1785765318.053241, "n": 18841, "h": "c40d54fc5712a17e", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过显式 SDK Transport（stdio 或 HTTP）接入 ClawSentry，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN=$CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保 `.env.clawsentry` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径；如果 session 目录尚不存在，会写入 `CS_CODEX_WATCH_ENABLED=true`，让 Gateway 后续从 `$CODEX_HOME/sessions` 自动探测。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 未启用自动探测**：如果没有显式设置 `CS_CODEX_SESSION_DIR`，确认 `CS_CODEX_WATCH_ENABLED=true`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $CS_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export CS_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM 日费用超出 CS_LLM_DAILY_BUDGET_USD 限额，降级 L1 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "6fe2f7e67a64a89a42b71236661a881eaa15e085": {"t": 1785765326.6963594, "n": 18713, "h": "67f7f91805a05826", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry init openclaw --setup` 自动配置：\n ```bash\n clawsentry init openclaw --setup --dry-run # 预览变更\n clawsentry init openclaw --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --gateway-url http://127.0.0.1:9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过 stdio 传输，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN=$CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保 `.env.clawsentry` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径并配置 `CS_CODEX_SESSION_DIR`。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 被禁用**：确认 `CS_CODEX_WATCH_ENABLED` 未设置为 `false`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $AHP_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export AHP_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM 日费用超出 CS_LLM_DAILY_BUDGET_USD 限额，降级 L1 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "7ad01c27624609131eee088a5e899b7a0dca1f44": {"t": 1785765328.6885743, "n": 18671, "h": "dbfa2556da542674", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry gateway --setup` 自动配置：\n ```bash\n clawsentry gateway --setup --dry-run # 预览变更\n clawsentry gateway --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --port 9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过 stdio 传输，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## Claude Code 集成\n\n??? question \"Claude Code hook 未被触发\"\n\n **症状**：ClawSentry 运行正常，但执行 Claude Code 操作时 Gateway 无事件进入\n\n **诊断**：\n ```bash\n # 检查 hooks 配置\n cat ~/.claude/settings.json | python3 -m json.tool\n # 查看 harness 入口\n which clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **重新初始化**：\n ```bash\n clawsentry init claude-code\n ```\n 此命令自动写入 `~/.claude/settings.json` 的 `hooks` 配置。\n\n 2. **手动检查 hooks 结构**：确认 `settings.json` 包含以下字段：\n ```json\n {\n \"hooks\": {\n \"PreToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness\"}],\n \"PostToolUse\": [{\"type\": \"command\", \"command\": \"clawsentry-harness --async\"}]\n }\n }\n ```\n\n 3. **harness 路径错误**：如果 Python 环境不在 PATH 中：\n ```bash\n # 使用绝对路径\n which clawsentry-harness # 获取完整路径\n # 然后在 settings.json 中填入完整路径\n ```\n\n??? question \"clawsentry-harness 每次调用都返回非零退出码\"\n\n **症状**：Claude Code 执行操作时报错 `hook exited with non-zero status`\n\n **诊断**：\n ```bash\n # 手动测试 harness（模拟 Claude Code hook 调用）\n echo '{\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"bash\",\"tool_input\":{\"command\":\"ls\"}}' | \\\n CS_AUTH_TOKEN=$CS_AUTH_TOKEN clawsentry-harness\n ```\n\n **解决方案**：\n\n 1. **Gateway 未运行**：先启动 Gateway\n ```bash\n clawsentry start --framework claude-code\n ```\n\n 2. **Auth Token 不匹配**：确保 `.env.clawsentry` 中的 `CS_AUTH_TOKEN` 与 Gateway 使用的一致\n ```bash\n clawsentry doctor\n ```\n\n 3. **harness 降级模式**：harness 默认在无法连接 Gateway 时降级为 `ALLOW`（不退出非零码）。若仍失败，检查 Python 环境\n\n??? question \"DEFER 超时后 Agent 操作被意外放行\"\n\n **症状**：DEFER 决策超时未审批，但 Agent 操作仍被执行（未被拒绝）\n\n **诊断**：\n ```bash\n echo $CS_DEFER_TIMEOUT_ACTION\n ```\n\n **解决方案**：\n\n 将 `CS_DEFER_TIMEOUT_ACTION` 设置为 `block`（默认值即为 `block`）：\n ```bash\n export CS_DEFER_TIMEOUT_ACTION=block\n ```\n 若设为 `allow`，超时后会自动放行——仅在本地测试场景下使用此设置。\n\n---\n\n## Codex Session Watcher\n\n??? question \"Codex 操作未被监控\"\n\n **症状**：Codex Agent 执行命令时 Gateway 无事件，`clawsentry watch` 无输出\n\n **诊断**：\n ```bash\n # 检查 Codex session 目录\n ls ~/.codex/sessions/\n echo $CS_CODEX_SESSION_DIR\n echo $CS_CODEX_WATCH_ENABLED\n ```\n\n **解决方案**：\n\n 1. **重新初始化 Codex 集成**：\n ```bash\n clawsentry init codex\n ```\n 自动检测 Codex 安装路径并配置 `CS_CODEX_SESSION_DIR`。\n\n 2. **手动指定 session 目录**：\n ```bash\n export CS_CODEX_SESSION_DIR=~/.codex/sessions\n clawsentry start\n ```\n\n 3. **Watcher 被禁用**：确认 `CS_CODEX_WATCH_ENABLED` 未设置为 `false`\n\n??? question \"Codex Session Watcher 日志显示 'session dir does not exist'\"\n\n **症状**：Gateway 启动时日志警告 `CS_CODEX_SESSION_DIR=... does not exist`\n\n **解决方案**：\n\n 1. 确认 Codex 已安装且已运行过至少一次（首次运行才会创建 sessions 目录）\n 2. 手动创建目录并重启：\n ```bash\n mkdir -p ~/.codex/sessions\n clawsentry start\n ```\n\n---\n\n## Latch Hub 与 DEFER Bridge\n\n??? question \"Latch Hub 无法连接\"\n\n **症状**：`clawsentry doctor` 的 `LATCH_HUB_HEALTH` 检查失败，或 `clawsentry latch status` 显示 Hub 已停止\n\n **诊断**：\n ```bash\n curl http://127.0.0.1:3006/health\n clawsentry latch status\n cat ~/.clawsentry/run/latch-hub.log\n ```\n\n **解决方案**：\n\n 1. **Hub 未启动**：\n ```bash\n clawsentry latch start\n ```\n\n 2. **端口冲突**：\n ```bash\n lsof -i :3006\n export CS_LATCH_HUB_PORT=3007\n clawsentry latch start\n ```\n\n 3. **Latch 二进制未安装**：\n ```bash\n clawsentry latch install\n ```\n\n??? question \"DEFER Bridge 已启用但 Hub 未收到推送\"\n\n **症状**：`CS_DEFER_BRIDGE_ENABLED=true` 且 Hub 运行正常，但手机/Web PWA 未收到 DEFER 推送通知\n\n **诊断**：\n ```bash\n clawsentry doctor # 检查 LATCH_TOKEN_SYNC\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://127.0.0.1:8080/events # 确认 SSE 流正常\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：Hub 的 `CLI_API_TOKEN` 必须与 Gateway 的 `CS_AUTH_TOKEN` 一致。运行 `clawsentry doctor` 查看 `LATCH_TOKEN_SYNC` 检查结果\n\n 2. **HubBridge 未启用**：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n # 重启 Gateway\n clawsentry stop && clawsentry start --with-latch\n ```\n\n 3. **Hub URL 配置错误**：确认 `CS_LATCH_HUB_URL=http://127.0.0.1:3006`（默认）或自定义端口\n\n 4. **Bridge 在 `auto` 模式下未自动启用**：\n 如果 Hub 启动后才检测到，Bridge 可能在 Gateway 启动时未自动连接，尝试：\n ```bash\n export CS_HUB_BRIDGE_ENABLED=true\n ```\n 而非 `auto`。\n\n??? question \"clawsentry doctor 的 LATCH_TOKEN_SYNC 失败\"\n\n **症状**：doctor 输出 `LATCH_TOKEN_SYNC: FAIL — CS_AUTH_TOKEN does not match Hub CLI_API_TOKEN`\n\n **解决方案**：\n\n 重新同步 Token（ClawSentry 安装时会自动完成此步骤，但手动修改 Token 后需要重新同步）：\n\n ```bash\n # 更新 .clawsentry/run/latch-hub.env 或重新安装\n clawsentry latch uninstall --keep-data\n clawsentry latch install\n ```\n\n 或手动在 Latch Hub 配置文件中将 `CLI_API_TOKEN` 设置为与 `CS_AUTH_TOKEN` 相同的值。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $AHP_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export AHP_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n| `Codex watcher started` | INFO | Codex Session Watcher 已启动，开始轮询 |\n| `CS_CODEX_SESSION_DIR=... does not exist` | WARNING | Codex sessions 目录不存在，Watcher 未启动 |\n| `LatchHubBridge: hub not reachable` | WARNING | Hub URL 不可达，Bridge 未自动启用 |\n| `LatchHubBridge: token mismatch` | ERROR | CS_AUTH_TOKEN 与 Hub CLI_API_TOKEN 不一致 |\n| `DEFER timed out, applying timeout action` | INFO | DEFER 超时，按 CS_DEFER_TIMEOUT_ACTION 处理 |\n| `LLM budget exceeded` | WARNING | LLM 日费用超出 CS_LLM_DAILY_BUDGET_USD 限额，降级 L1 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}, "9b1ede09f837b1c7bcf8fee273b6e7cb15dc4871": {"t": 1785765332.7852361, "n": 13411, "h": "1f9d795c6b1ca995", "c": "---\ntitle: 故障排查\ndescription: ClawSentry 常见问题诊断与解决方案\n---\n\n# 故障排查\n\n本页列出 ClawSentry 运行中常见的问题、诊断步骤和解决方案。每个问题以可折叠卡片呈现，点击展开查看详情。\n\n---\n\n## 启动与连接\n\n??? question \"Gateway 无法启动：端口冲突\"\n\n **症状**：启动时报错 `Address already in use` 或 `OSError: [Errno 98]`\n\n **诊断**：\n ```bash\n # 检查端口占用\n lsof -i :8080\n # 或\n ss -tlnp | grep 8080\n ```\n\n **解决方案**：\n\n 1. **停止占用端口的进程**：\n ```bash\n kill <PID>\n ```\n\n 2. **更换端口**：\n ```bash\n export CS_HTTP_PORT=9090\n clawsentry gateway\n ```\n\n 3. **如果是残留的 ClawSentry 进程**：\n ```bash\n pkill -f \"clawsentry gateway\"\n ```\n\n??? question \"Gateway 无法启动：UDS 路径问题\"\n\n **症状**：启动时报错 `Address already in use` 但端口未被占用，或 `PermissionError`\n\n **诊断**：\n ```bash\n # 检查 UDS 文件是否存在\n ls -la /tmp/clawsentry.sock\n\n # 检查文件权限\n stat /tmp/clawsentry.sock\n ```\n\n **解决方案**：\n\n 1. **删除残留的 UDS 文件**（上次 Gateway 非正常退出时可能残留）：\n ```bash\n rm -f /tmp/clawsentry.sock\n ```\n\n 2. **更换 UDS 路径**：\n ```bash\n export CS_UDS_PATH=/tmp/my-clawsentry.sock\n clawsentry gateway\n ```\n\n 3. **检查目录权限**（如果使用自定义路径）：\n ```bash\n # 确保目录存在且可写\n mkdir -p /run/clawsentry\n chmod 755 /run/clawsentry\n ```\n\n??? question \"Gateway 无法启动：缺少依赖\"\n\n **症状**：`ModuleNotFoundError: No module named 'fastapi'` 或类似错误\n\n **诊断**：\n ```bash\n pip show clawsentry\n pip show fastapi uvicorn\n ```\n\n **解决方案**：\n\n ```bash\n # 重新安装（含所有依赖）\n pip install \"clawsentry[llm,dev]\"\n\n # 或仅安装核心依赖\n pip install clawsentry\n ```\n\n 如果使用虚拟环境，确保已激活：\n ```bash\n # conda 环境\n conda activate a3s_code\n\n # venv 环境\n source /path/to/venv/bin/activate\n ```\n\n---\n\n## 认证问题\n\n??? question \"认证失败：401 Unauthorized\"\n\n **症状**：API 请求返回 `401 Unauthorized`，Web 仪表板登录失败\n\n **诊断**：\n ```bash\n # 检查 CS_AUTH_TOKEN 是否设置\n echo $CS_AUTH_TOKEN\n\n # 测试认证\n curl -v -H \"Authorization: Bearer $CS_AUTH_TOKEN\" http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **Token 不匹配**：确保客户端使用的 Token 与 Gateway 环境变量中的完全一致（注意空格和换行符）\n ```bash\n # 检查是否有隐藏字符\n echo -n \"$CS_AUTH_TOKEN\" | xxd | head\n ```\n\n 2. **Token 未设置**：如果 `CS_AUTH_TOKEN` 为空，Gateway 不进行认证检查。一旦设置了非空值，所有请求必须携带 Token\n\n 3. **Header 格式错误**：必须是 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格\n\n 4. **Web 仪表板登录失败**：\n - 清除浏览器的 `sessionStorage`\n - 确认在登录表单中输入的是完整的 Token 值\n\n??? question \"SSE 连接认证失败\"\n\n **症状**：SSE 连接返回 401 或立即断开\n\n **诊断**：\n ```bash\n # 测试 SSE 端点\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n SSE 使用 URL Query 参数传递 Token（因为浏览器 `EventSource` API 不支持自定义 Header）：\n\n ```\n /report/stream?token=<your-token>\n ```\n\n Web 仪表板会自动从 `sessionStorage` 读取 Token 并附加到 SSE URL。如果 Token 已过期或被清除，需要重新登录。\n\n---\n\n## OpenClaw 连接\n\n??? question \"OpenClaw WebSocket 连接失败\"\n\n **症状**：日志显示 `WebSocket connection failed` 或 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 OpenClaw Gateway 是否运行\n docker ps | grep openclaw\n\n # 检查端口是否可达\n curl http://127.0.0.1:18789\n\n # 检查 WebSocket URL 配置\n echo $OPENCLAW_WS_URL\n ```\n\n **解决方案**：\n\n 1. **URL 格式**：确保使用 `ws://` 或 `wss://` 前缀\n ```bash\n export OPENCLAW_WS_URL=ws://127.0.0.1:18789\n ```\n\n 2. **Docker 网络**：如果 OpenClaw 在 Docker 中运行，确保使用 `--network host` 或正确的端口映射\n ```bash\n docker run --network host openclaw:local ...\n ```\n\n 3. **防火墙**：检查端口是否被防火墙阻拦\n ```bash\n sudo ufw status\n sudo iptables -L | grep 18789\n ```\n\n??? question \"OpenClaw 连接后事件无法接收：scope 问题\"\n\n **症状**：WebSocket 连接成功，但收不到 `exec.approval.requested` 事件\n\n **诊断**：检查 WebSocket 连接参数。\n\n **解决方案**：\n\n 这是一个已知的 OpenClaw 行为。ClawSentry 连接 OpenClaw Gateway 时必须使用特定参数：\n\n | 参数 | 必需值 | 说明 |\n |------|--------|------|\n | `client.id` | `openclaw-control-ui` | 保留完整 scope，否则非 device 连接 scope 会被清空 |\n | `client.mode` | `backend` | 后端模式 |\n | `role` | `operator` | 运维角色 |\n | `Origin` header | 已配置的 origin | 必须匹配 `gateway.controlUi.allowedOrigins` 配置 |\n\n 在 OpenClaw 配置中：\n ```json title=\"openclaw.json\"\n {\n \"gateway\": {\n \"controlUi\": {\n \"allowedOrigins\": [\"http://localhost:8080\"],\n \"dangerouslyDisableDeviceAuth\": true\n }\n }\n }\n ```\n\n??? question \"OpenClaw sandbox 模式跳过审批\"\n\n **症状**：Agent 执行命令时完全不触发审批流程，日志中无 `exec.approval.requested`\n\n **诊断**：检查 OpenClaw 的 `tools.exec.host` 配置。\n\n **解决方案**：\n\n **必须**将 `tools.exec.host` 设为 `\"gateway\"`。默认的 `\"sandbox\"` 模式会跳过所有审批检查：\n\n ```json title=\"openclaw.json\"\n {\n \"tools\": {\n \"exec\": {\n \"host\": \"gateway\"\n }\n }\n }\n ```\n\n 可以使用 `clawsentry gateway --setup` 自动配置：\n ```bash\n clawsentry gateway --setup --dry-run # 预览变更\n clawsentry gateway --setup # 应用配置\n ```\n\n---\n\n## LLM 问题\n\n??? question \"LLM 调用失败：API Key 缺失\"\n\n **症状**：日志显示 `CS_LLM_PROVIDER=openai but OPENAI_API_KEY is empty; falling back to rule-based`\n\n **诊断**：\n ```bash\n echo $CS_LLM_PROVIDER\n echo $OPENAI_API_KEY # 或 $ANTHROPIC_API_KEY\n ```\n\n **解决方案**：\n\n 根据选择的提供商设置对应的 API Key：\n\n === \"OpenAI / 兼容 API\"\n ```bash\n export CS_LLM_PROVIDER=openai\n export OPENAI_API_KEY=sk-your-key-here\n # 如果使用兼容 API（如 Kimi、DeepSeek）\n export CS_LLM_BASE_URL=https://api.deepseek.com/v1\n export CS_LLM_MODEL=deepseek-chat\n ```\n\n === \"Anthropic\"\n ```bash\n export CS_LLM_PROVIDER=anthropic\n export ANTHROPIC_API_KEY=sk-ant-your-key-here\n ```\n\n !!! info \"仅 L1 模式\"\n 如果不设置 `CS_LLM_PROVIDER`，ClawSentry 将只使用 L1 规则引擎和内置的 L2 RuleBasedAnalyzer。这对于大多数场景已经足够。\n\n??? question \"LLM 调用超时\"\n\n **症状**：日志显示 `LLM analysis failed; falling back to L1` 且延迟接近 3000ms\n\n **诊断**：\n ```bash\n # 测试 LLM API 可达性\n curl -w \"\\n%{time_total}s\" \"$OPENAI_BASE_URL/models\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n ```\n\n **解决方案**：\n\n 1. **网络问题**：检查 DNS 解析和网络连接\n 2. **代理配置**：如果使用代理，设置 `HTTP_PROXY` / `HTTPS_PROXY`\n 3. **提供商限流**：检查 LLM 提供商的速率限制配额\n 4. **降级正常**：LLM 超时时 ClawSentry 会自动降级到 L1 等级，这是预期行为（fail-safe）\n\n??? question \"LLM 返回解析失败\"\n\n **症状**：日志显示 `LLM response parse failed; falling back to L1`\n\n **解决方案**：\n\n 这通常发生在：\n\n 1. **模型不遵循 JSON 输出格式** -- 尝试更换模型（推荐 GPT-4 或 Claude 3）\n 2. **temperature 设置过高** -- ClawSentry 默认使用 `temperature=0.0`，确保未被覆盖\n 3. **max_tokens 不足** -- 默认 256 tokens，如果响应被截断可能导致 JSON 不完整\n\n 降级行为是安全的：L2 LLM 分析失败时，决策回退到 L1 规则引擎的结果。\n\n---\n\n## SSE 与实时推送\n\n??? question \"SSE 连接频繁断开\"\n\n **症状**：Web 仪表板数据更新不及时，控制台显示 `EventSource` 连接错误\n\n **诊断**：\n ```bash\n # 直接测试 SSE 连接\n curl -N \"http://localhost:8080/report/stream?token=$CS_AUTH_TOKEN\"\n ```\n\n **解决方案**：\n\n 1. **网络不稳定**：SSE 基于 HTTP 长连接，网络抖动会导致断开。浏览器的 `EventSource` API 有自动重连机制\n\n 2. **反向代理超时**：如果通过 Nginx 等反向代理，配置超长超时：\n ```nginx\n proxy_read_timeout 3600s;\n proxy_send_timeout 3600s;\n proxy_buffering off;\n ```\n\n 3. **认证 Token 过期**：重新登录 Web 仪表板获取新 Token\n\n 4. **浏览器限制**：浏览器对同一域名的 SSE 连接数有限制（通常 6 个）。避免打开过多标签页\n\n??? question \"clawsentry watch 无法连接\"\n\n **症状**：`clawsentry watch` 命令无输出或报错 `Connection refused`\n\n **诊断**：\n ```bash\n # 检查 Gateway 端口\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 1. **端口不匹配**：`clawsentry watch` 默认连接 `localhost:8080`。如果 Gateway 使用了自定义端口：\n ```bash\n clawsentry watch --port 9090\n ```\n\n 2. **Gateway 未启动**：先启动 Gateway\n ```bash\n clawsentry gateway &\n clawsentry watch\n ```\n\n 3. **认证问题**：如果 Gateway 启用了认证，watch 需要通过环境变量获取 Token：\n ```bash\n export CS_AUTH_TOKEN=your-token\n clawsentry watch\n ```\n\n---\n\n## DEFER 与审批\n\n??? question \"DEFER 决策超时无人处理\"\n\n **症状**：DEFER 决策在倒计时结束后自动过期，Agent 操作被拒绝\n\n **诊断**：确认是否有运维人员在监控 DEFER 决策。\n\n **解决方案**：\n\n 1. **启动交互式 watch**：\n ```bash\n clawsentry watch --interactive\n ```\n 运维人员可以实时看到 DEFER 决策并按 `[A]llow / [D]eny / [S]kip` 响应\n\n 2. **使用 Web 仪表板**：\n 打开 `http://localhost:8080/ui` 的 DEFER Panel 页面\n\n 3. **调整策略减少 DEFER**：\n 如果 DEFER 过多，考虑调整 L1 规则阈值或 L2 策略，将确定性高的事件直接 ALLOW 或 BLOCK\n\n 4. **配置会话执法策略**：\n 通过 `AHP_SESSION_ENFORCEMENT_*` 环境变量，在累积多次高危事件后自动 BLOCK，减少对人工审批的依赖\n\n??? question \"DEFER Panel 显示 503 降级提示\"\n\n **症状**：Web 仪表板 DEFER Panel 显示 \"Resolve not available -- OpenClaw enforcement is not connected\"\n\n **诊断**：\n ```bash\n # 检查 OpenClaw 连接状态\n curl http://localhost:8080/health\n ```\n\n **解决方案**：\n\n 此提示表示 Gateway 无法将 allow/deny 决策回传给 OpenClaw Gateway。原因可能是：\n\n 1. **OpenClaw 未连接**：检查 `OPENCLAW_WS_URL` 和 `OPENCLAW_OPERATOR_TOKEN` 配置\n 2. **OpenClaw 已断开**：检查 OpenClaw Gateway 是否仍在运行\n 3. **仅使用 a3s-code**：a3s-code 的审批机制通过 stdio 传输，不需要 OpenClaw 连接。此提示可以忽略\n\n !!! info \"DEFER 仍然可以查看\"\n 即使无法 resolve，运维人员仍可以在 DEFER Panel 中查看决策详情，了解 Agent 的操作请求。\n\n---\n\n## 误报与策略调优\n\n??? question \"高误报率：安全操作被标记为高风险\"\n\n **症状**：正常的开发操作频繁触发 BLOCK 或 DEFER\n\n **解决方案**：\n\n 1. **查看决策原因**：通过 `clawsentry watch` 或 Web 仪表板查看每个决策的具体原因（D1-D5 评分和 short_circuit 规则）\n\n 2. **理解 D1-D5 评分**：\n\n | 维度 | 含义 | 调优方向 |\n |------|------|----------|\n | D1 | 工具危险性 | 如果特定工具被高估，检查 `DANGEROUS_TOOLS` 列表 |\n | D2 | 目标路径敏感度 | 工作目录中的 `.env` 等可能触发 |\n | D3 | 命令模式 | `rm`、`sudo` 等关键词触发 |\n | D4 | 会话累积风险 | 高危事件会累积，降低后续阈值 |\n | D5 | Agent 信任等级 | 默认为 untrusted |\n\n 3. **调整 Agent 信任等级**：通过 `DecisionContext.agent_trust_level` 提升受信 Agent 的信任等级\n\n 4. **参考[策略调优指南](../configuration/policy-tuning.md)**\n\n??? question \"低报率：危险操作未被拦截\"\n\n **症状**：已知的危险命令（如 `rm -rf /`）未被 BLOCK\n\n **诊断**：\n ```bash\n # 查看决策日志\n clawsentry watch --json\n ```\n\n **解决方案**：\n\n 1. **检查事件类型**：只有 `pre_action` 类型的事件会产生 BLOCK 决策。`post_action` 等观察型事件始终 ALLOW\n 2. **检查 risk_hints**：Adapter 是否正确提取了 risk_hints\n 3. **启用 L2 分析**：配置 `CS_LLM_PROVIDER` 启用 LLM 语义分析\n 4. **启用会话执法**：\n ```bash\n export AHP_SESSION_ENFORCEMENT_ENABLED=true\n export AHP_SESSION_ENFORCEMENT_THRESHOLD=3\n export AHP_SESSION_ENFORCEMENT_ACTION=block\n ```\n\n---\n\n## 性能问题\n\n??? question \"响应延迟高\"\n\n **症状**：决策延迟 > 100ms（L1）或 > 5s（L2/L3）\n\n **诊断**：\n ```bash\n # 查看决策延迟\n clawsentry watch --json | jq '.decision_latency_ms'\n ```\n\n **解决方案**：\n\n 1. **L1 延迟高 (> 10ms)**：\n - 检查 SQLite 写入性能（可能磁盘 I/O 瓶颈）\n - 将 `CS_TRAJECTORY_DB_PATH` 放在 SSD 上\n - 检查系统负载\n\n 2. **L2 LLM 延迟高 (> 3s)**：\n - LLM API 超时默认 3 秒，超时后降级到 L1\n - 考虑使用更快的 LLM 提供商或本地模型\n - 检查网络延迟\n\n 3. **L3 Agent 延迟高 (> 30s)**：\n - L3 涉及多轮 LLM 调用，延迟取决于工具调用次数\n - L3 永不降级，这是设计决策（安全优先于性能）\n\n??? question \"速率限制触发\"\n\n **症状**：API 返回 `RATE_LIMITED` 错误，Agent 操作被延迟\n\n **诊断**：\n ```bash\n # 查看当前速率限制配置\n echo $AHP_RATE_LIMIT_PER_MINUTE\n ```\n\n **解决方案**：\n\n 1. **提高限制**（如果硬件允许）：\n ```bash\n export AHP_RATE_LIMIT_PER_MINUTE=1000\n ```\n\n 2. **检查是否有异常流量**：大量事件可能表示 Agent 行为异常或配置错误\n\n 3. **批量操作优化**：如果 Agent 框架支持，考虑批量发送事件减少请求频率\n\n??? question \"SQLite 写入竞争\"\n\n **症状**：日志出现 `database is locked` 错误\n\n **解决方案**：\n\n ClawSentry 使用单进程架构，SQLite 写入竞争通常不会发生。如果出现：\n\n 1. **检查是否有多个 Gateway 实例**共用同一个数据库文件\n 2. **检查外部工具**是否在读取数据库（如备份脚本未使用 `.backup` 命令）\n 3. **升级 SQLite 版本**：确保系统 SQLite >= 3.35（WAL 模式支持）\n\n---\n\n## Web 仪表板\n\n??? question \"Web 仪表板无法访问\"\n\n **症状**：浏览器访问 `http://localhost:8080/ui` 返回 404 或空白页\n\n **诊断**：\n ```bash\n # 检查 UI 文件是否存在\n python -c \"from pathlib import Path; p = Path(__import__('clawsentry').__file__).parent / 'ui' / 'dist' / 'index.html'; print(f'{p}: exists={p.exists()}')\"\n ```\n\n **解决方案**：\n\n 1. **UI 文件缺失**：确保安装了包含 UI 的完整包\n ```bash\n pip install --force-reinstall clawsentry\n ```\n\n 2. **路径未挂载**：检查 Gateway 启动日志中是否有 `UI directory mounted` 相关信息\n\n 3. **SPA 路由问题**：直接访问 `/ui` 应该返回 `index.html`。如果通过反向代理，确保 SPA fallback 配置正确\n\n??? question \"仪表板图表不显示数据\"\n\n **症状**：仪表板页面加载正常，但图表显示 \"No data yet\"\n\n **诊断**：\n ```bash\n # 检查是否有决策数据\n curl -H \"Authorization: Bearer $CS_AUTH_TOKEN\" \\\n http://localhost:8080/report/summary\n ```\n\n **解决方案**：\n\n 1. **无事件数据**：Gateway 刚启动且没有 Agent 连接时，没有数据是正常的\n 2. **时间窗口**：Summary API 默认查询最近一段时间的数据。如果数据已过期，图表为空\n 3. **认证问题**：浏览器控制台检查 API 请求是否返回 401\n\n---\n\n## 日志分析\n\n### 关键日志消息\n\n以下是需要关注的关键日志消息及其含义：\n\n| 日志消息 | 级别 | 含义 |\n|----------|------|------|\n| `Gateway request failed` | ERROR | 事件无法送达 Gateway，正在降级 |\n| `Falling back to local decision` | WARNING | 使用本地降级决策 |\n| `LLM analysis failed; falling back to L1` | WARNING | L2 LLM 分析失败，回退到 L1 |\n| `LLM response parse failed` | WARNING | LLM 返回格式不正确 |\n| `Enforcement callback failed` | ERROR | 无法将决策回传到 Agent 框架 |\n| `WS approval event received` | INFO | 收到 OpenClaw 审批请求 |\n| `Custom skills loaded` | INFO | 自定义 Skills 加载成功 |\n| `L3 AgentAnalyzer enabled` | INFO | L3 审查 Agent 初始化成功 |\n| `Unknown hook type` | WARNING | 收到无法映射的事件类型 |\n| `duplicate skill name` | WARNING | 自定义 Skill 名称与内置冲突 |\n\n### 日志级别建议\n\n| 环境 | 建议级别 | 说明 |\n|------|----------|------|\n| 开发 | `DEBUG` | 查看所有事件处理细节 |\n| 测试 | `INFO` | 查看关键操作和配置信息 |\n| 生产 | `WARNING` | 只关注异常和降级事件 |\n\n### 增加日志详细度\n\n```bash\n# 临时增加日志详细度\nexport PYTHONPATH_LOG_LEVEL=DEBUG\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\" && clawsentry gateway\n```\n\n或在 Python 代码中：\n\n```python\nimport logging\nlogging.getLogger(\"clawsentry\").setLevel(logging.DEBUG)\nlogging.getLogger(\"a3s-adapter\").setLevel(logging.DEBUG)\nlogging.getLogger(\"openclaw-adapter\").setLevel(logging.DEBUG)\n```\n"}}}} |