Observal/Observal · 上手攻略

仓库：Observal/Observal
链接：https://github.com/Observal/Observal · 文档 https://docs.observal.io · PyPI https://pypi.org/project/observal-cli/
分类：AI / Coding Agent 控制平面 / 自托管注册中心
作者：spark
更新：2026-09-06

1. 是什么

Observal 是一个自托管的「内部 AI 组件注册中心 + 使用洞察平台」，目标受众是中型以上技术组织：你和团队已经在 Claude Code / Cursor / Kiro / Pi / Copilot / Codex / OpenCode / Antigravity CLI / Goose 等多个 coding harness 里攒了一堆 Skill、MCP server、Hook、Prompt 和沙箱，但发现用得起来的远少于造得出来的，组件散落在各自的 GitHub 仓库里，互相重复造轮子。

Observal 提供两层：

集中注册 + 治理：把 MCP/Skill/Hook/Prompt/Sandbox 打包成可版本化的「Agent」，注册到私有 registry，admin 审核发布、对比版本差异、给开发者一个统一安装入口；同一份 Agent 自动生成对各 harness 的配置文件（不必为每个 harness 维护一份 README）。
使用洞察 + 反馈回路：通过 session telemetry hook 抓 coding agent 的会话轨迹（用户 prompt、工具调用、thinking block、assistant 输出），落到 ClickHouse，再用 LiteLLM 兼容的 LLM 跑出「什么好用、什么卡壳、有什么 quick win」的分析报告。

组件技术栈是 Vite 6 + React 19 + TanStack Router + Tailwind 4 + shadcn/ui（前端），Python 3.11+ + FastAPI + Strawberry GraphQL（后端），PostgreSQL 16（注册数据）+ ClickHouse（遥测），Redis + arq（任务队列），部署走 Docker Compose（10 个服务）或 Helm。许可证 Apache-2.0。

2. 解决什么问题

「内部 AI 组件没人发现」：没有发现层，团队里 5 个人造了 5 个差不多的安全审计 MCP，每次新人又造一次。
「组件上线后没人知道用得怎么样」：MCP / Skill / Agent 失败不像传统服务有 stacktrace——LLM 会静默地幻觉或给微妙错误答案，事后无迹可寻。
「每个 harness 各写一份接入文档」：Claude Code / Cursor / Kiro / Pi / Copilot / Codex / OpenCode 的接入路径不一样，组件作者被迫维护 N 份说明。
「agent 出问题无法回放」：没有 trace，重跑成本高，debug、复盘、审计都做不了。
「缺乏合规治理」：组织想让 agent 走审批流程、看版本 diff、控制谁可以装什么，但纯 Slack/文档流做不到。

Observal 用一个 Docker stack 全部覆盖：装好后，团队把内部 Agent push 到 registry、装到任意 harness，所有 session 自动被采集、聚合后形成可执行的洞察报告。

3. 快速安装

最小要求：Docker Engine ≥ 24.0 且 Compose v2、Python 3.11+（仅在源码装 CLI 时）、4 GB RAM（ClickHouse 比较吃，建议 6 GB）、5 GB 磁盘。

3.1 一行脚本（推荐，开发者本地）

curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install-server.sh | bash

下载 Docker Compose 包、生成操作员拥有的密钥文件（限定容器组权限）、把对外端口默认绑到 loopback、从 GHCR 拉镜像、启动整栈。有 TTY 时走引导式设置；无 TTY（CI / agent）走安全默认。

3.2 源码启动（贡献者）

git clone https://github.com/Observal/Observal.git && cd Observal
cp .env.example .env       # 本地开发可直接用默认值
make up                    # 等价 docker compose -f docker/docker-compose.yml up --build -d

首次启动会拉镜像、编译 Vite 前端，3-5 分钟；之后启动 < 30 秒。整栈 10 个服务全部起来后：

curl http://localhost/health   # {"status":"ok","initialized":true}
open http://localhost          # Web UI

服务端口速览：

服务	端口	用途
observal-lb (nginx)	80	反向代理
observal-web	3000	Web UI
observal-api	内网	FastAPI 后端
observal-worker	内网	arq 后台任务
observal-db	5432	PostgreSQL 16
observal-clickhouse	8123	遥测存储
observal-redis	6379	队列
observal-prometheus	9090	指标
observal-grafana	3001	仪表盘

3.3 装 CLI

CLI 是装在开发者本地的工具，跟 server 通信。

# Python（PyPI）
uv tool install observal-cli
# 或
pipx install observal-cli

# macOS / Linux（Homebrew）
brew install Observal/observal/observal-cli

# 源码可编辑安装
uv tool install --editable .

# 验证
observal --version

3.4 登录 + 注入 harness hook

observal auth login
# 走引导：Server URL 默认 http://localhost，登录方式选 [E]mail，用 demo 账号登录

observal doctor --patch   # 检测已装的 harness、装 telemetry hook
observal auth status      # 验证状态：Server OK / Auth OK / Buffer 0 pending

demo 账号（首次启动自动 seed）：

角色	邮箱	密码
Super Admin	super@demo.example	super-changeme
Admin	admin@demo.example	admin-changeme
Reviewer	reviewer@demo.example	reviewer-changeme
User	user@demo.example	user-changeme

⚠️ demo 账号仅供本地开发，上线前必须改 SECRET_KEY / POSTGRES_PASSWORD / CLICKHOUSE_PASSWORD，并取消所有 DEMO_* 变量（详见 docs/self-hosting/configuration.md）。

4. 核心用法

4.1 在 harness 内用 `/observal`

登录后，在支持的 harness 里直接输入：

/observal pull security-auditor
/observal scan
/observal doctor

pull 从 registry 装 agent；scan 只读扫描当前 harness 装了什么；doctor 自检 telemetry hook 完整性。也可以用自然语言让 agent 自己挑命令。

4.2 CLI 安装指定 agent 到指定 harness

observal pull security-auditor --harness pi

会按 pi harness 的目录结构和配置格式落盘；同一份 agent 注册后，可以装到 Claude Code / Cursor / Kiro / Pi / Copilot / Codex / OpenCode / Antigravity CLI / Goose 任一个里，registry 会自动生成对应配置。

4.3 一个 Agent 包含 5 类组件

打包一次，自动适配多 harness：

MCP servers：模型上下文协议服务；
Skills：技能包（通常是一组 prompt + 工具约定）；
Hooks：session telemetry / 拦截 / 增强；
Prompts：可复用提示词；
Sandboxes：执行沙箱。

在 registry 里写一次，Observal 帮你生成各 harness 的 config 文件，避免「5 个 harness × 5 个组件 = 25 份 README」。

4.4 版本 diff + 审批

Admin UI 提供：

提交队列（带完整 prompt 检视 + approve / reject）
版本之间并排 diff（提交前看改了什么）
Leaderboard（按下载量排前组件）
审计日志、SAML SSO、SCIM 配置
执行仪表盘（高管视角）

4.5 洞察报告（Insight Engine）

CLI 接入 LLM 后跑 usage pattern 分析：

# 配置 insight LLM provider（LiteLLM 兼容：Anthropic / OpenAI / Bedrock / Gemini / Azure / Ollama）
# 见 docs/insights-setup.md

报告话题：「什么 agent / tool / prompt / workflow 在帮团队」「什么在拖后腿」「有什么 quick win」。

4.6 会话回放

抓到的 trace 进入 ClickHouse 后，UI 可看完整 token 计数 / 模型 / 工具 / 时间线视图，点进任一 span 看具体 tool 输入输出，用于 debug、review、审计。

4.7 支持的 harness 列表（README 实测）

Claude Code · Kiro · Cursor · Pi · Copilot（CLI & VS Code 扩展）· Codex · OpenCode · Antigravity CLI · Goose — 共 9 个，按需扩展。

4.8 常用运维 Make 目标

make up          # 启动
make down        # 停
make rebuild     # 重 build + 重启
make logs        # tail 所有服务日志
make test        # 跑测试（mock 外部，无需 docker）
make test-v      # verbose 测试
make lint        # ruff check
make format      # ruff format + fix
make check       # pre-commit 全量
make hooks       # 装 pre-commit

5. 典型适用场景

平台 / DevEx 团队：统一管理公司内部 Skill / MCP / Agent，避免重复造轮子，强制走审批。
AI 安全 / 合规：所有 agent 行为进入 ClickHouse，可审计、可回放、SAML SSO + SCIM 对接 IdP。
多 harness 组织：开发者各有所好（Claude Code / Cursor / Kiro / Copilot），统一装一套安全 / 审计 / 测试 agent。
Agent 失败归因：发现某类 prompt 在某模型下系统性翻车，从 session trace 倒推。
Leaderboard + 推广：让「被高频使用的内部 agent」自然浮现，团队决策有数据支撑。

不太适合：

个人开发者：单机 + 单 harness 用不到 registry / 审批；
极小团队（< 5 人）：10 服务 Docker Compose + ClickHouse 重，对 5 人团队 ROI 太低；
不想让 session 上报任何第三方基础设施：Observal 默认自托管，可解；但如果连自托管 ClickHouse 都不想跑就别用了。

6. 坑与注意

demo 账号密码写死在 demo：上线前必改 SECRET_KEY / POSTGRES_PASSWORD / CLICKHOUSE_PASSWORD 并清空所有 DEMO_* 变量——README 与 SETUP 都强调，但默认 .env.example 是合法可工作的，容易漏改。
端口冲突：80 / 3000 / 3001 / 5432 / 6379 / 8123 / 9090 都是常见占用端口；每个都可用环境变量覆盖：API_HOST_PORT=8001 WEB_HOST_PORT=3001 docker compose -f docker/docker-compose.yml up --build -d。
首次启动慢：3-5 分钟拉镜像 + 编译前端，不要以为挂掉。observal-init 跑完迁移会主动退出，其他服务应 healthy / running，API 等 PG / ClickHouse / Redis 全 ready 才启动，留 15-30 秒。
observal doctor patch vs scan：scan 只读不动；patch 才会装 / 改 harness 的 telemetry hook。跑 doctor --patch --all-harnesses 前先看 --help，别在生产 harness 上手抖。
ClickHouse 吃内存：默认配置下 6 GB 比较舒服；4 GB 也能跑但 Insight 报告可能 OOM。
make down -v 会删数据：演示完想清场别 down -v 除非你接受全量丢；备份恢复走 docs/self-hosting/backup-and-restore.md。
升级要走 docs/self-hosting/upgrades.md：跳版本可能撞 schema migration，按文档备份 → 升级 → 验证，不要直接 docker compose pull。
release verification：生产环境装新版本前必看 docs/security/release-verification.md，核对 checksum、provenance、签名 tag，避免供应链被劫。
Insight LLM 走 LiteLLM：要配置 API key，没有 LLM 也能跑（仅失能 insight 报告），其他功能正常。
CLI 与 server 版本要对齐：大版本升级后 client/server 可能协议不兼容，升级前看 release notes。
observal doctor support bundle 生成的诊断包要 review 再分享——README 强调「Produces a redacted diagnostic archive. Review before sharing」。
本地开发与生产部署是两套路径：make up（源码开发） vs install-server.sh（生产包）——后者会自动把 secret 文件落到 secrets/ 并最小权限，不要拿 make up 直接上线。

7. 与同类对比

工具	定位	与 Observal 的差异
Claude Code / Cursor / Kiro 各自的扩展市场	厂商官方市场	厂商市场是 SaaS + 公开组件；Observal 是自托管 + 内部组件 + 治理审批
MCP Registry（modelcontextprotocol/registry）	公开 MCP 注册中心	那个面向社区公开 MCP；Observal 面向企业内部组件 + 加 harness 适配 + 加遥测
Smithery / MCP.so	公开 MCP 目录	同上，公开为主，无治理 / 审批 / 内部 trace
Langfuse / Helicone / Phoenix	LLM 可观测性	它们关注 LLM call 本身（token / latency / cost）；Observal 关注 harness session 全轨迹 + 治理 + 注册中心
OpenLLMetry / Arize Phoenix / LangSmith	LLM tracing	同上
Internal plugin 文档 + Slack	土法治理	没有版本 diff / 审批 / 审计 / 洞察
Backstage / Port	内部开发者门户	它们覆盖工程资源（服务 / 资源 / 团队）；Observal 专攻 AI 组件 + harness 适配 + session 反馈
n8n / Temporal	通用工作流	不解决 Agent 组件打包 / harness 适配 / session 回放
私有 PyPI / Harbor	私有软件 registry	是更宽泛的 registry；Observal 是 AI 组件专用，且带 harness 适配层 + 遥测层

一句话：Observal = 「内部 AI 组件的私有 PyPI + 内部 Langfuse + 多 harness 适配」三合一。

8. 一句话推荐结论

如果你的组织已经用 2+ 个 coding harness、有 ≥ 5 个内部 Skill / MCP / Agent、且对审计 + 审批 + session 回放有合规诉求——直接装 Observal；如果只是个人玩 Claude Code，没必要上 10 个服务。

不确定 / 已显式标注

文档 URL docs.observal.io / observal.gitbook.io 均来自 README，未独立 fetch 验证当前内容是否一致。
harness 支持列表（9 个）是 README 当前版本；harness 生态变化快，使用前看 docs/ 最新版。
默认端口、demo 账号来自 SETUP.md，未在仓库最新代码中复核。
Insight Engine 用 LiteLLM 兼容 provider 的列表与计费情况，本次仅引用文档原文。