15. 故障排查与常见陷阱
汇总最常见的问题、原因和解法，以及一些「行为正确但第一次遇到容易吓人」的设计。
大多数问题在这三条命令的输出里就能定位，比逐条对照现象快：
```bash omicos --version # 版本对不对 omicos env doctor # 解析到哪个 Python、omicverse 在不在 curl -sS http://127.0.0.1:5055/health # 守护进程活着吗（端口以日志实际打印的为准） ```网页端还有一个更全的入口：设置 · 诊断，能同时给出浏览器视角和 Core 视角的网络判定——两者不一致本身就是线索（典型是代理拦了回环）。
15.1 故障速查表
| 现象 | 原因 / 排查 |
|---|---|
跑分析时报 The Python environment is still being prepared… |
环境还在后台装。等一会儿再试；想加速就提前 omicos env setup。 |
跑分析时报 Python environment unavailable: … |
环境准备失败。跑 omicos env doctor 看解析到哪个解释器，再 omicos env setup 重来。 |
omicos env doctor 显示 omicverse : MISSING ✗ |
解析到的 Python 里没有 omicverse。多半是 .kernel_choice 或 OMICOS_KERNEL_PYTHON 指错了环境。 |
omicos cli 报 no user_token — run \omicos cli login` first` |
没登录。用 omicos login（邮箱/密码）或 omicos cli login（设备码）。 |
启动横幅是 [omicos] offline: … |
凭证里没有进程令牌。重新 omicos login。 |
敲 omicos serve 却直接打开了浏览器就退出了 |
这个工作区里已经有一个在跑，它复用了那个实例（见 15.2）。 |
| 网页端一直「连接中」 | 本机守护进程没起 / 端口不是你以为的那个 / 代理拦了回环。先 curl http://127.0.0.1:5055/health，再看 15.2 的代理条目。 |
| 网页端显示「暂无历史」 | 选错进程了。进程选择器里 (cli) 后缀的和无后缀的是两个独立命名空间。 |
远程访问 connection refused |
SSH 端口转发的窗口断了，或者服务器上实际绑定的端口不是 5055（被占时会顺延）。以启动时 listening: 那行为准。 |
no model provider configured |
没有可用的 provider / API key。设 OMICOS_LLM_PROVIDER 或配好对应的 *_API_KEY。 |
mock provider is disabled; configure a real model provider |
指定了 mock provider 或 mock/ 前缀的模型名，这个是被禁用的。 |
| 付费功能突然不可用 | 订阅令牌续期失败、降级到 community。重新 omicos login。 |
15.2 容易踩的设计陷阱
下面这些不是 bug，是设计如此：
serve 与 cli 的关系不是「互斥」而是「接管」
工作区里已经有 omicos serve 在跑时，omicos cli 会直接连上它，共享同一份会话历史。只有工作区里没有守护进程时，cli 才自己起一个——那时它用 .omicos/cli 作数据目录，与 serve 的历史互相隔离。
同样地，在已有实例的工作区里再敲 omicos serve，它不报错，而是复用那个实例、打开浏览器、以成功状态退出：
[omicos] already running in this workspace (pid 41287, port 5055); reusing it instead of starting a second instance.
[omicos] open: https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true
（只有桌面版启动的实例遇到冲突时才会以错误退出，那是留给桌面端自己处理的。）
端口未必是 5055
指定端口被占时，omicos 从下一个端口开始向后找，最多 100 个，都不行就让系统随机分配。永远以 listening: 那行（或运行面板 Local 那行）为准，别默认是 5055。脚本里用 --report-port 读实际端口。
.kernel_choice 压过 OMICOS_KERNEL_PYTHON
解释器解析里，持久化的选择（<当前目录>/.omicos/.kernel_choice 和 ~/.omicos/.kernel_choice）排在环境变量前面。导出了变量却发现没生效，先看 omicos env doctor 报的是哪个，再去清掉那个文件。
OMICOS_ENV_DIR 不改变环境的安装位置
它只参与解释器解析。omicos env setup 永远装到 ~/.omicos/env。要整体搬走，改 OMICOS_LOCAL_HOME。
--upstream-base-url 既不决定 kernel 在哪，也不开启云端接入
它只配置本地一个 HTTP 代理回退（把未匹配的 /api/* 转给后端）。kernel 永远由这个 omicos 进程自己提供，除非你用 --kernel-base-url 显式指向别处；云端接入由守护进程是否持有进程令牌（来自 omicos login）决定。只设 --kernel-base-url 不设 --upstream-base-url 会有一条告警但不影响运行。
环境问题是延迟暴露的
Python 环境没配好时，守护进程照常启动，聊天照常能用，直到真正运行分析代码才报错。先 omicos env setup。
切换账户会重新登记进程身份
在一个工作区里切换登录账户时，云端不允许新账户接管旧账户名下的进程标识。omicos 的处理是旋转 workspace_id、用新身份重新登记，在进程内完成，不重启、不退出。可能看到的现象是新账户下会话列表一开始为空——本地旧会话文件仍在，旧账户那边的记录仍属于旧账户。
Ctrl+C 太快可能丢未同步的消息
会话同步是异步的。刚发完消息就立刻 Ctrl+C / kill，还没同步出去的内容可能丢失。关键工作结束后等几秒再退。
代理会拦掉本机回环
配了 http_proxy / https_proxy / all_proxy 而 no_proxy 没放行回环时，kernel 的出站请求和浏览器到 localhost:5055 的连接都可能被代理吃掉，表现为「一直连不上」。omicos 启动时会打印一段中英双语提示。修法：
export no_proxy=localhost,127.0.0.1
预期输出：无输出；重启 omicos 后启动时不再出现那段代理告警。
cli 模式看不了 --debug
cli 的屏幕被聊天界面占满，--debug / --log-filter 都不可用，只能 RUST_LOG=... omicos cli。无效的过滤表达式会被静默回退到默认（只在 stderr 打一行 invalid log filter ...）。可能看不出 filter 没生效。
设备码登录需要「另一台已登录设备」
omicos cli login 需要另一台已登录 omicOS 账号的设备来确认。如果手头只有一台从未登录过的新机器，直接用 omicos login 邮箱/密码登录即可——纯终端完成，不需要任何其他设备。
一些会被静默处理的取值
OMICOS_CATALOG_SYNC_SECS < 30不会被钳到 30，而是被丢弃并回退到 600 秒；OMICOS_MEMORY_SYNC_SECS < 60同理回退 3600 秒。- URL 类变量结尾不要带斜杠。
- 布尔开关统一写
1最稳（多数也接受true/yes，部分还接受on，其余值一律当「关」）。 - 空 / 纯空白的环境变量一律当作未设置。
凭证文件未加密
cloud_login.json、auth.json、plan_token.jwt、a2a_keys.json 都是明文，仅靠 0600 权限保护。切勿提交到 git、粘贴、或拷给别人。 Windows 上权限模型不同，注意检查。
15.3 收集诊断信息
报问题前先收集这些：
omicos --version
预期输出：
omicos 0.3.29+a1b2c3d
omicos env doctor
预期输出：
kernel python : /Users/you/.omicos/env/.venv/bin/python3
omicverse : present ✓
managed env : /Users/you/.omicos/env
uv : /Users/you/.local/bin/uv
package index : pypi (https://pypi.org/simple)
omicos login --status
预期输出：
[omicos] logged in as you@example.com
[omicos] process: my-analysis
[omicos] config: /Users/you/.omicos/cloud_login.json
curl -sS http://127.0.0.1:5055/health
预期输出：
{"service":"omicos-core","status":"ok","version":{"build_profile":"release","display":"0.3.29+a1b2c3d","git_rev":"a1b2c3d","semver":"0.3.29","target_triple":"aarch64-apple-darwin"}}
带调试日志复现：
RUST_LOG=omicos_core=debug omicos serve --no-browser > omicos-debug.log 2>&1
预期输出：终端无输出（都进了 omicos-debug.log），文件开头是启动横幅，随后是逐条 debug 日志。等价写法是 omicos serve --debug true。
15.4 离线模式的注意点
开了 OMICOS_*_OFFLINE 系列开关后，agent / skill / model / memory 可能是陈旧缓存，不反映云端最新内容。排查「为什么看不到新 agent」时，先确认不是离线模式在起作用。