14. 故障排查与常见陷阱

本章汇总最常见的问题、原因和解法，以及一些"行为正确但容易吓人"的设计陷阱。

14.1 故障速查表

现象 原因 / 排查
kernel 报 scanpy not found Python 环境没配好。OMICOS_ENV_DIR 没设或指向无效目录。运行 omicos env setup、omicos env doctor，导出变量后重启 omicos。
omicos cli 报 no user_token 没登录。用 omicos login（邮箱/密码）或 omicos cli login（设备码）登录。
[omicos] offline cloud_login.json 没有 process_token。重新 omicos login。
omicos serve already running on this workspace 同一目录已有守护进程。Ctrl+C 掉它，或 pkill -f 'omicos serve'，或换 --data-dir。
网页端一直 "Connecting..." 本机守护进程没起 / 端口被占。pgrep -fl 'omicos serve' 看进程。
网页端显示 "暂无历史" 选错进程了。进程选择器里 (cli) 后缀的和无后缀的是两个独立命名空间。
远程访问 connection refused SSH 端口转发的窗口断了。保持 SSH 窗口，或改用云端中继（服务器上 omicos login 后直接 omicos serve --no-browser 即自动中继，无需 --upstream-base-url）。
no model provider configured 没有可用的 provider / API key。设 OMICOS_LLM_PROVIDER 或配好对应 *_API_KEY。
付费功能突然不可用 plan token 续期失败、降级到 community。重新 omicos login。

14.2 容易踩的设计陷阱

下面这些不是 bug，是设计如此，但第一次遇到容易困惑：

serve 与 cli 会话不互通

二者默认 data-dir 不同（.omicos vs .omicos/cli），会话历史互相隔离。同一工作区也不能同时跑（共享同一把锁 serve.pid）。

--upstream-base-url 不决定 kernel 在哪，也不开启云端中继

它只配置本地一个 HTTP 代理回退（把未匹配的 /api/* 转发给后端，即云同步的 escape hatch），不决定 kernel 跑在哪，也不是云端中继的开关——中继由守护进程是否持有 process_token（来自 omicos login 或 OMICOS_PROCESS_TOKEN）决定。kernel 默认在本机 5055，由 --kernel-base-url 单独控制。只设 --kernel-base-url 不设 --upstream-base-url 会有告警但不报错。

scanpy not found 是延迟错误

Python 环境没配好时，守护进程能正常启动，直到你真正运行分析代码才报错。所以请务必先 omicos env setup。

账户切换会"自愈重启"

在一个工作区切换登录账户时，云端发 WebSocket 关闭码 4403，omicos 会旋转 workspace_id 并自动重启自己——看起来像崩溃，实为预期恢复。代价是会话同步高水位被清空，新账户下会话列表可能显示为空（本地旧会话文件仍在）。

Ctrl+C 太快可能丢未同步消息

会话同步是异步的。如果你刚发完消息就立刻 Ctrl+C / kill，内存里还没同步出去的消息可能丢失。关键工作结束后，等几秒让它同步完再退出。

cli 模式看不了 --debug

cli 的 stdout 被 TUI 占满，--debug / --log-filter 都不可用，只能 RUST_LOG=... omicos cli。而且 RUST_LOG / OMICOS_LOG_FILTER 的无效过滤表达式会被静默忽略回退默认，你可能不知道 filter 没生效。

设备码登录需要"另一台已登录设备"

omicos cli login（设备码方式）需要另一台已登录 omicOS 账号的设备来确认配对码。如果手头只有一台从未登录过的全新机器，直接用 omicos login 邮箱/密码登录即可——它纯终端完成，无需任何其他设备。

一些会被静默处理的取值

  • OMICOS_CATALOG_SYNC_SECS < 30 不会被钳制到 30，而是被丢弃并回退到 600 秒默认值。
  • OMICOS_CLOUD_BASE 等 URL 变量结尾不能带斜杠（会被 trim 掉）。
  • 布尔开关只认 1/true/yes/on，其他值当作"关"。
  • 空 / 纯空白的环境变量一律当作未设置。

凭证文件未加密

cloud_login.json、auth.json、plan_token.jwt 都是明文，仅靠 0600 权限保护。切勿提交到 git、粘贴、或拷给别人。Windows 上权限模型不同，注意 umask。

14.3 收集诊断信息

报问题前，先收集这些：

omicos env doctor                          # Python / kernel 诊断
omicos login --status                      # 登录状态（未登录会打印 "not logged in"）
curl -sS http://127.0.0.1:5055/api/version # 版本 + git revision（omicos 无 --version flag）
curl -sS http://127.0.0.1:5055/health      # 服务健康（返回 JSON）
RUST_LOG=omicos_core=debug omicos serve    # 带调试日志复现（或 omicos serve --debug true）

14.4 离线模式的注意点

开了 OMICOS_*_OFFLINE 系列开关后，agent / skill / memory / model 可能是陈旧缓存，不会反映云端最新内容。排查"为什么看不到新 agent"时，先确认不是离线模式。

results matching ""

    No results matching ""