1. 概述：omicOS 是什么
一句话理解
omicOS 把「大语言模型多智能体」和「单细胞 / 空间组学分析」结合成一个工作台。你用自然语言描述分析意图。omicOS 的智能体会调用 OmicVerse、scanpy 等工具，在共享的 IPython kernel 里跑出真实代码、图表和结果。
本部分（第一部分）介绍内核 omicos-core。它是用 Rust 写的本地程序，命令名就叫 omicos。
omicos 的双重身份
同一个二进制既是本地守护进程，也是终端聊天客户端：
- 作为守护进程，它监听本机
http://127.0.0.1:5055，对外提供 HTTP + SSE 接口（/api/*）。网页端 app.omicos.cn 连上来操作它。 - 作为终端客户端（
omicos cli），它直接在命令行里开一个聊天窗口，适合没有浏览器的 SSH / HPC 环境。
两种身份共用同一个 IPython kernel。所以 adata 对象、notebook 变量、图表、文件状态在网页端和终端之间互通。
"共用一个 kernel"具体意味着什么
你在网页端载入的
adata，切到 omicos cli 里可以直接接着用；在内置终端 pip install 的包，智能体下一轮就能 import。不需要重新载入数据，也不存在两份状态。反过来说也要留意：在一边把变量删了或覆盖了，另一边看到的就是改过之后的样子。
命令一览
| 命令 | 作用 |
|---|---|
omicos serve |
启动 HTTP 守护进程，并（默认）打开浏览器进入网页端。这是无子命令时的默认行为——直接敲 omicos 等于 omicos serve。 |
omicos cli |
启动内嵌守护进程 + 终端聊天界面，无需浏览器。 |
omicos login |
邮箱 / 密码登录 omicOS 云账户。 |
omicos env |
管理本地 Python 分析环境（setup / doctor / list）。 |
omicos hpc |
服务器 / HPC 的交互式向导：选一个 Python 环境，然后启动。 |
omicos a2a |
管理 Agent2Agent 对外端点与 API key（0.3.29 之后的版本提供）。 |
omicos recover-conversations |
把隔离期之前的旧会话归属到当前账户（运维用，平时用不到）。 |
查看版本：
omicos --version
预期输出：
omicos 0.3.29+a1b2c3d
版本串的格式是
<semver>+<git 短哈希>；开发版会再带一个(debug)后缀，正式发布版没有。
完整参数见第 9 章：命令与参数速查。
它如何连接云端
登录后，omicos 会主动建立一条向外的 WebSocket，连到 omicOS 云端（wss://auth.omicos.cn/ws/process）。用途：
- 进程注册与心跳：让云端知道这台机器上有一个 omicOS 进程在线。
- 会话与轨迹同步：把对话和分析轨迹备份到云端，本地进程退出后记录仍在。
- 跨机器接入：让你在笔记本浏览器里操作另一台机器上运行的 omicOS（见远程部署配方）。
没登录时这条连接不会建立，启动横幅会打印 [omicos] offline: run \omicos login` to connect auth.omicos.cn`，本地分析照常可用。
本地优先：哪些东西留在你机器上
kernel、数据、notebook 都在你自己的机器上运行。云端负责账户、同步和接入，不搬走你的原始数据。
这条边界在几个功能上都能验证：证据模式的"数据锚点"指向的是你本机内核里的变量，只把结论传上去；图床关闭时生成的图只留本地路径；MCP 服务器全部在本机进程里跑，服务器列表也只存本机。
默认监听
127.0.0.1
默认端口
5055
未登录时
分析照常可用
服务域名
| 用途 | 域名 |
|---|---|
| 认证 / 服务端 | auth.omicos.cn |
| 网页端 | app.omicos.cn |
本部分覆盖什么
第一部分是一份完整的「把 omicOS 跑起来」指南：
- 前置条件 → 安装 → Python 环境
- 登录 → 启动（serve / cli）
- 远程 / SSH / HPC 部署
- 参考资料：命令参数、环境变量、目录结构
- 进阶：Provider / 模型、Agents / Skills / Memory
- 故障排查
本文档基线版本为 omicos-core 0.3.29。