6. 启动 omicOS：serve 模式（浏览器）

最常用的启动方式：起一个本地守护进程，用浏览器进入网页端操作。直接敲 omicos 等同于 omicos serve（serve 是默认子命令）。

6.1 最小用法

cd ~/my-analysis     # 进入你想放数据 / notebook 的目录
omicos serve

预期输出：终端切换成一个全屏运行面板，大致长这样：

  OmicOS  0.3.29                     uptime 00:00:12    theme dark
 ── Runtime ─────────────────────────────────────────────────────
  Local     http://127.0.0.1:5055  (kernel HTTP / WS)
  Browser   https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true
  Region    CN
  Cloud     ● online
  Process   local-9f2c…1a94
 ── Logs ────────────────────────────────────────────────────────
  …
  q / Ctrl-C quit   urls …

同时会自动打开浏览器进入网页端，直接连到面板里 Local 那一行的端口，即可开始聊天分析。浏览器没自动弹出时，复制 Browser 那行的 URL 手动打开。

按 q 或 Ctrl-C 退出，终端恢复原样。

两种输出形态。 stdin 和 stdout 都是交互终端时才画这个面板。被 nohup、systemd、桌面版包起来跑，或输出被重定向 / 管道接走时，omicos 改打印一组文本行，日志走 stderr。本章后面的「预期输出」都用这种文本形态，方便逐行核对：

[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055
[omicos] opening: https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true

没登录时第一行会换成 [omicos] offline: run \omicos login` to connect auth.omicos.cn`，本地分析照常可用。

6.2 核心参数

完整参数表见第 9 章：命令与参数速查。

6.3 端口被占用时会自动顺延

5055 被占用时，omicos 不直接失败，而从 5056 开始向后依次尝试（最多 100 个端口）。都不行才退回让系统随机分配：

omicos serve --no-browser > omicos.log 2>&1 &

预期输出（omicos.log 的内容）：

[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] port 5055 was busy; using 5056 instead
[omicos] listening: http://127.0.0.1:5056

后面所有操作都用实际绑定的端口（这里是 5056），包括健康检查和 SSH 端口转发。全屏面板里，这个值就是 Local 那行显示的端口。

写脚本时用 --report-port 拿这个值最稳：

omicos serve --no-browser --report-port > omicos.log 2>&1 &

预期输出（omicos.log 的内容）：

[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055
OMICOS_LISTENING_PORT=5055

6.4 服务器 / 无界面场景：--no-browser

没有图形界面、或不希望弹浏览器时：

omicos serve --no-browser

预期输出：与 6.1 相同（面板或文本行），只是没有 opening: 那行，也不尝试唤起浏览器。

守护进程照常启动监听，之后从别的机器的浏览器接入（见远程部署）。

6.5 工作区锁：一个目录只跑一个

omicos 在 <工作区>/.omicos/serve.pid 放一把锁，保证同一工作区目录只有一个守护进程。同一目录重复 omicos serve 时，它不报错，而是复用已在运行的那个实例：

omicos serve --no-browser 2>&1 | cat

预期输出：

[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

然后（除非加了 --no-browser）打开浏览器指向那个已有实例，并以成功状态退出。所以「第二次敲 omicos」的体感就是「它把已经开着的那个打开」。

想真正起第二个实例，换一个工作区目录，或用 --data-dir 指向不同的数据目录。

omicos serve 和 omicos cli 共享同一把工作区锁。工作区里已经有 serve 在跑时，omicos cli 会直接连上它（见第 7 章），而不是报错。

6.6 健康检查

确认守护进程正常：

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"}}

看进程身份和工作区：

curl -sS http://127.0.0.1:5055/api/process/info | python3 -m json.tool

预期输出（节选）：

{
    "core_workspace_root": "/Users/you/my-analysis",
    "hostname": "your-macbook",
    "id": "local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94",
    "kernel": "native-python-worker",
    "launched_by": "terminal",
    "name": "my-analysis",
    "pid": 41287,
    "port": 5055,
    "process_id": "local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94",
    "process_name": "my-analysis",
    "runtime": "rust",
    "version": "0.3.29",
    "workspace": "/Users/you/my-analysis",
    "ws_port": 5055
}

几点说明：

• 响应里没有 status 字段（那是 /health 才有的）。
• 未登录时 id / process_id 仍有值，回退成 local-<workspace_id>；process_name 回退成 OmicOS Core。看到这两个字段有值不代表已登录。判断登录状态看 online / offline 那行，或跑 omicos login --status。
• launched_by 是 terminal（终端启动）或 desktop（桌面版启动）。
• hostname 是这台机器的主机名，排查远程连接时很有用。

6.7 首次启动不会等 Python 环境

omicos serve 不为环境准备而推迟启动。端口立刻绑好，聊天和文件操作马上可用，Python 环境在后台准备。此时跑分析会看到：

The Python environment is still being prepared — chat works now; retry running Python in a moment.

建议提前 omicos env setup 配好环境（见第 4 章）。避免第一次分析撞上正在安装的环境。

下一步

• 想用纯终端而不是浏览器？→ 第 7 章：cli 模式
• 想从远程服务器跑、本地浏览器看？→ 第 8 章：远程部署