b26ce18c创建于 19 天前历史提交

title	description
5 分钟上手	登录看板、注册模型、创建 Agent、完成接入，并在 UI 中看到第一条链路。

5 分钟上手

本指南带你用最短路径跑通 Agent Insight 的第一条完整闭环：完成基础配置、接入一个 Agent，并在平台里看到真实链路。

完成后你会得到：

一个已登记的 Agent
一份可用的模型配置
一条真实上报并可查看详情的 Trace

Note 本页更贴近当前项目的真实使用流程，默认你已经部署好了 Agent Insight 服务端，并可以访问看板地址，例如 http://localhost:3000 或你的自托管域名。

前置条件

你可以访问 Agent Insight 看板
你拥有一个可用的模型 API Key，例如 OpenAI、DeepSeek 或其他兼容供应商
你有一个准备接入的 Agent 运行环境
如果要走代码集成路径，准备好 Python 3.9+ 或 Node.js 18+

可选：用 Docker 部署服务端

如果你还没有部署看板，可以直接拉取已发布的 Docker 镜像。karaggagent/agent-insight 已发布多架构镜像，x86_64 服务器会自动拉取 linux/amd64，aarch64 服务器会自动拉取 linux/arm64。

用法一：在线拉取 Docker Hub 镜像

docker pull karaggagent/agent-insight:latest

mkdir -p ~/.agent-insight/data
chmod -R 777 ~/.agent-insight

docker stop agent-insight 2>/dev/null || true
docker rm agent-insight 2>/dev/null || true

docker run -d \
  --name agent-insight \
  --restart unless-stopped \
  -p 3000:3000 \
  -v ~/.agent-insight:/data/agent-insight \
  karaggagent/agent-insight:latest

curl -i http://localhost:3000/

这条命令会把容器内的 /data/agent-insight 挂到服务器宿主机当前用户的 ~/.agent-insight。SQLite 数据库、Skill 附件、评测运行时文件都会写入该目录下的 data/，容器重启、删除、重拉镜像后仍可复用。默认数据库路径是：

~/.agent-insight/data/witty_insight.db

用法二：离线导入 `.tar` 镜像

如果服务器无法访问 Docker Hub，可以先拿到离线镜像包，例如 agent-insight-0.5.0-image.tar，再导入运行：

docker load -i agent-insight-0.5.0-image.tar
docker images | grep agent-insight

mkdir -p ~/.agent-insight/data
chmod -R 777 ~/.agent-insight

docker stop agent-insight 2>/dev/null || true
docker rm agent-insight 2>/dev/null || true

docker run -d \
  --name agent-insight \
  --restart unless-stopped \
  -p 3000:3000 \
  -v ~/.agent-insight:/data/agent-insight \
  karaggagent/agent-insight:0.5.0

curl -i http://localhost:3000/

如果 docker load 输出的镜像 tag 不是 karaggagent/agent-insight:0.5.0，请以 docker images | grep agent-insight 看到的实际镜像名为准。

如果你不想直接挂宿主机目录，也可以使用 Docker volume：

docker run -d \
  --name agent-insight \
  --restart unless-stopped \
  -p 3000:3000 \
  -v agent-insight-data:/data/agent-insight \
  karaggagent/agent-insight:latest

如果生产环境需要锁定版本号，可以把 latest 换成固定版本，例如 0.5.0：

docker pull karaggagent/agent-insight:0.5.0
docker stop agent-insight
docker rm agent-insight
docker run -d \
  --name agent-insight \
  --restart unless-stopped \
  -p 3000:3000 \
  -v ~/.agent-insight:/data/agent-insight \
  karaggagent/agent-insight:0.5.0

服务器上用哪个用户运行 Docker，就会挂载哪个用户的 home 目录。升级到新版本时，保留同一个挂载目录即可，容器数据不会随镜像更新丢失。

如果容器启动后访问不到 3000，先看容器状态和日志：

docker ps -a --filter name=agent-insight
docker logs --tail=200 agent-insight
curl -i http://127.0.0.1:3000/

常见的 unable to open database file 通常是宿主机挂载目录不存在或权限不足。确认目录已创建，并且容器内的 node 用户可以写入 /data/agent-insight/data。

如果你需要自己构建镜像，可以直接用仓库根目录的 Dockerfile。镜像默认从 npm 拉取 agent-insight@latest，不会把源码复制进镜像：

docker build --pull --no-cache -t agent-insight:npm-latest .
docker run -d --name agent-insight -p 3000:3000 -v agent-insight-data:/data/agent-insight agent-insight:npm-latest
curl -i http://localhost:3000/

需要固定某个 npm 版本时：

docker build --pull --build-arg AGENT_INSIGHT_VERSION=0.5.0 -t agent-insight:0.5.0 .

如果你只是想在服务器上快速验证本地改动，不想每次都先发布 npm 包，可以改走“npm pack + 上传 .tgz + Docker 缓存构建”的测试流程，见 Docker 测试构建。

容器只负责运行 Agent Insight 服务端。OpenCode、Claude Code、OpenClaw、LangChain 等框架的接入命令仍应在对应 Agent 实际运行的机器或容器里执行。当前仓库里的这份 Dockerfile 走 SQLite 优先 路线，不内置 OpenGauss 运行时依赖。

如果你要使用 opencode-live 触发分析、轨迹评测等会由服务端本机拉起 opencode 的能力，请确保当前 Dockerfile 构建出的镜像完整保留 npm 依赖，并让容器能够访问模型提供商网络；这些评测不会复用外部宿主机上另开的 opencode 进程。

步骤一：登录并确认 Workspace

打开你的 Agent Insight 看板地址。
完成登录，进入默认 Workspace。
确认左侧导航中可以看到以下模块：
- Agent 管理
- 运行观测
- 评测中心
- Skills 能力
- 配置

Tip 如果你同时维护开发、预发和生产环境，建议为不同环境分别创建独立 Agent，后续看 Trace 和做评测时会更清晰。

步骤二：注册第一个模型

进入侧边栏 配置 → 模型注册，完成一个可用模型的配置：

点击 注册首个模型 或新增模型
选择模型供应商
填入 API Key 与必要的 Endpoint
点击 测试连接并保存

完成后，你的 Workspace 就具备了后续执行生成、诊断、评测等能力所需的模型依赖。

Warning 如果模型连接失败，先不要继续后续步骤。很多分析、评测和 Skill 流程都依赖模型可用。

步骤三：注册 Agent

进入侧边栏 Agent Workspace → Agent 管理：

点击注册 Agent
输入 Agent 名称
根据页面提示填写信息
保存后进入 Agent 详情页

注册agent是把客户端实际使用的 Agent 注册到平台。只有注册后的 Agent，平台才会展示它的执行数据。 Agent 名称要和客户端中的实际名称一致，例如 opencode 默认的agent是 plan 和 build。

步骤四：按安装指导完成接入

进入 配置 → 安装指导，按页面提示完成接入。

通常你会完成这些动作：

选择当前环境对应的安装方式，例如 Linux / macOS 或 Windows (PowerShell)
复制页面生成的安装命令
在 Agent 所在机器上执行该命令
使用右侧显示的 API Key 和接入信息完成配置

下面以 opencode 作为客户端为例：

安装命令会自动写入当前平台地址和 API Key，比手动配置更直接。

步骤五：验证生成的 Trace

完成安装或配置后，按下面两步验证是否已生成 Trace。

在 opencode 中发送一次真实请求，例如执行一个简单任务，让 Agent 实际运行起来。

下面以 opencode 为例：
回到平台，进入 运行观测 → 链路追踪，确认是否出现新的 Trace。

验证时优先确认这些信息：

列表里出现新的 Trace 记录
能看到执行状态、耗时、Token 等基本指标
点进详情后，可以看到 Trace 树和各个 Span
如果流程中使用了工具或子 Agent，也能看到对应节点

第一次验证时，不需要追求数据很完整，先确认“有数据、能展开、能看懂主要步骤”即可。

确认生成 Trace 后，你就已经完成了平台配置、Agent 注册和接入验证。

Warning 如果 30 秒后仍然看不到数据，按下面顺序排查：

先查看客户端日志文件 ~/.agent-insight/logs/opencode_uploader.log

确认客户端到服务端的网络是否通顺

是否选中了正确的 Workspace

Agent 使用的 API Key / 配置是否来自当前 Agent

仍无法解决时，可继续参考常见问题。

继续阅读

想先看产品整体结构 → Agent Insight
想补齐基础配置 → 模型注册 / 安装指导
想理解平台核心名词 → 核心概念
想继续排查和分析线上执行 → 运行观测
想建立第一套离线评测 → 评测中心
想沉淀可复用能力 → Skills 能力