5分钟上手Observal：从本地部署到看到第一条AI会话追踪的完整快速入门教程

5分钟上手Observal：从本地部署到看到第一条AI会话追踪的完整快速入门教程

【免费下载链接】ObservalObserval is self-hosted registry for your coding agent extensions with a built in insight engine. Setup Observal, define the scope and share your Skills, MCPs and Agents with your peers.项目地址: https://gitcode.com/gh_mirrors/ob/Observal

Observal 是一款自托管的 AI 编码代理（Agent）组件注册中心，内置 AI 洞察引擎与 AI 会话追踪能力：它可以统一管理你的 Skills、MCP 服务器和 Agents，并把 Claude Code、Cursor、Copilot 等工具中每一次 AI 编程会话完整记录成可回放、可分析的数据。本教程带你完成 Observal 本地部署，约 5 分钟即可在网页中看到第一条 AI 会话追踪记录。

开始前的准备工作：3 个环境要求

💡 用docker version和docker compose version快速确认版本。CLI 安装若走 Python 方式，需要 Python 3.11+。

第一步：安装 Observal CLI（1分钟完成）

Observal 分为两部分：自托管的服务端（API + 网页界面 + 数据库）和安装在开发者机器上的CLI 命令行。CLI 用于登录、安装会话追踪钩子、拉取 Agent。

最推荐用uv安装（也支持pipx/pip）：

uv tool install observal-cli observal --version

更多安装细节见官方文档 docs/getting-started/installation.md。

第二步：一键启动 Observal 服务端（最快配置方法）

在终端中执行以下命令，从源码启动完整的服务端堆栈：

git clone https://gitcode.com/gh_mirrors/ob/Observal cd Observal cp .env.example .env docker compose -f docker/docker-compose.yml up --build -d

.env.example自带可运行的默认配置，本地开发无需修改。首次启动会拉取镜像并编译前端，预计 3～5 分钟；之后启动只需 30 秒内。

核心服务说明（完整版见 SETUP.md）：

等待 15～30 秒让 API 通过健康检查，然后验证：

curl http://localhost/health # → {"status": "ok"}

🎉 返回ok即表示 Observal 服务端已就绪。生产部署建议参阅 docs/self-hosting/production-deploy.md 与 docs/self-hosting/docker-compose.md。

第三步：用演示账号登录 Observal

observal auth login

按提示操作：Server URL 直接回车（默认http://localhost），登录方式选Email，然后输入演示账号：

推荐用超级管理员体验最少限制的功能。验证登录成功：

observal auth whoami # → super@demo.example (super_admin)

凭据保存在~/.observal/config.json（权限0600）。

第四步：扫描环境并安装 AI 会话追踪钩子

先看看你的编码工具里已有哪些 MCP 服务器、Skills 和 Agents（scan只读，不修改任何配置）：

observal scan

接着为所有受支持的编码工具安装会话追踪钩子：

observal doctor patch --all-harnesses

该命令会安装受支持的会话钩子与扩展（不会改动 MCP 配置）。重启你的编码工具（如 Claude Code、Cursor、Copilot 等）使钩子生效，然后随便开一个 AI 编程会话，比如让它帮你写个函数或跑条命令，等会话完成即可。

第五步：在 Dashboard 看到第一条 AI 会话追踪 🚀

打开浏览器访问http://localhost/traces，刷新后即可看到刚刚被索引的会话列表，包括用户、平台、Token 消耗、工具调用次数、时长等：

点击任意一条会话，进入详情页查看 Token 输入/输出、缓存读写、API 调用次数、使用的模型和工具，以及逐轮对话时间线：

展开某一轮（Turn），可以看到完整的用户 Prompt、每一次工具调用、AI 的思考过程（Thinking）以及助手回复——AI 会话追踪的每个细节都可回放：

也可以直接用 CLI 查看最近 5 条追踪记录：

observal ops traces --limit 5

至此，Observal 会话追踪链路已经跑通：你的编码工具 → 本地会话钩子 → 摄入 API → ClickHouse 存储 → 网页仪表盘。完整原理可阅读 docs/core-concepts/session-tracking.md。

加餐：把 AI Agent 变成团队共享的"组件包"

Observal 的注册中心（Registry）是它的另一半核心价值：把 MCP 服务器、Skills、Hooks、Prompts、Sandboxes 五种组件打包成一个可安装、可版本化的 Agent，一条命令装进任意受支持的编码工具：

observal agent list # 浏览可用的 Agent observal agent pull security-auditor --harness pi

管理员侧还有审核队列、版本 Diff 对比、下载排行榜和 AI 洞察报告（Insights），帮助团队了解哪些 Agent 真正好用——详见 docs/use-cases/README.md。

快速回顾：5 步完成 Observal 快速入门

1. ✅uv tool install observal-cli安装 CLI
2. ✅ Docker Compose 启动服务端
3. ✅observal auth login演示账号登录
4. ✅observal doctor patch --all-harnesses安装追踪钩子
5. ✅ 打开http://localhost/traces查看 AI 会话追踪

Observal 快速入门就到这里——你的 AI 编码会话从此有据可查、可回放、可优化。🚀

【免费下载链接】ObservalObserval is self-hosted registry for your coding agent extensions with a built in insight engine. Setup Observal, define the scope and share your Skills, MCPs and Agents with your peers.项目地址: https://gitcode.com/gh_mirrors/ob/Observal