AI 应用接入:AI Coding Agent

更新时间:
复制 MD 格式

通过 LoongSuite Pilot 将开发者本机或容器中的 AI Coding Agent 运行数据接入 AgentLoop,实现会话、模型调用、工具调用、Token 用量和 Trace 数据的统一观测与分析。

LoongSuite Pilot 简介

LoongSuite Pilot 是轻量级采集器,支持部署在开发者本机、业务容器和 Kubernetes Pod 中,自动发现已安装的 AI Coding Agent,并部署所需的 Hook 或插件。对于需要在运行时生成配置的容器,可以在配置生成后、Agent 进程启动前执行注入命令,完成采集配置。LoongSuite Pilot 将不同 Agent 的原始活动数据归一化为统一事件格式,上报到 AgentLoop 使用的日志或 Trace 后端。

适用场景

当团队使用 Claude Code、Codex、Cursor、Qoder 等 AI Coding Agent 进行日常研发时,可通过 LoongSuite Pilot 采集本机或容器中的 Agent 活动数据,用于以下场景:

  • 查看团队使用了哪些 AI Coding Agent。

  • 分析会话、模型调用、工具调用和错误事件。

  • 按 Agent 维度统计 Token 用量。

  • 通过日志检索、Trace 链路或自定义接口分析 Agent 运行过程。

  • 在业务镜像构建或 Kubernetes 工作负载启动时,为容器中的 Agent 注入采集能力。

  • 同一 Agent 使用多个配置目录(多身份)时,分别为每个身份完成注入。

  • 在数据上报前过滤 Prompt、Completion、工具参数中可能出现的凭证或个人敏感数据,配置方式请参见“配置数据脱敏”。

    本机接入请参见“安装 LoongSuite Pilot”,容器与 Kubernetes 接入请参见“容器与 Kubernetes 部署”。

支持的 AI Coding Agent

macOS / Linux 支持情况

下表列出 LoongSuite Pilot 在 macOS / Linux 上支持的 Agent 及数据采集能力。

AI Coding Agent

集成方式

Trace 上报

日志上报

Token 采集

对话和 Tool Call 采集

Claude Code

Hook

支持

支持

支持

支持

Codex

Hook

支持

支持

支持

支持

Cursor

Hook

支持

支持

支持

支持

Cursor CLI

复用 Cursor Hook

支持

支持

支持

支持

豆包工作台(Doubao Work,仅 macOS,实验性)

只读本地客户端日志

客户端轮次与本地工具

仅元数据

不支持

不支持

GitHub Copilot CLI

原生插件 / 会话与原生 OTel 采集

支持

支持

支持

支持

DeepSeek Harness

YAML 补丁插件 / 本地 JSONL 轮询

支持

支持

支持

支持

Grok Build

Hook / 本地会话日志

支持

支持

支持

支持

Hermes Agent

原生目录插件

支持

支持

支持

支持

Kiro CLI

Hook / 会话轮询

支持

支持

不支持

支持

MiMo Code

插件注入

支持

支持

支持

支持

OpenClaw

插件注入

支持

支持

支持

支持

OpenCode

插件注入

支持

支持

支持

支持

Pi Coding Agent

扩展注入

支持

支持

支持

支持

Qoder

Hook

支持

支持

支持

支持

Qoder CN

Hook

支持

支持

支持

支持

Qoder for JetBrains

仅检测,复用 Qoder 采集链路

支持

支持

支持

支持

Qoder CLI

Hook / 会话轮询

支持

支持

支持

支持

Qoder Work

Hook / 本地数据轮询

支持

支持

支持

支持

Qoder Work CN

Hook / 本地数据轮询

支持

支持

支持

支持

Qwen Code CLI

Hook

支持

支持

支持

支持

Qwen Work CN

Hook / 本地数据轮询

支持

支持

支持

支持

Wukong

CLI API 轮询

支持

支持

支持

支持

WorkBuddy

Hook 唤醒 / 本地会话监听与轮询兜底

支持

支持

支持

支持

  • OpenClaw 集成需要 OpenClaw 2026.3.8 或更高版本:2026.5.12 及以上为完整支持;2026.3.8 至 2026.5.11 使用兼容模式,模型调用时间为推定值。

  • Token 用量以源 Agent 实际提供的数据为准;Kiro CLI 当前数据源不提供 Token 用量;GitHub Copilot CLI 的准确单次调用 Token 用量依赖原生 OTel 遥测数据。

  • 豆包工作台采用实验性被动观测,仅支持 macOS 和 Windows 正式版客户端,不安装 Hook,也不修改客户端。当前根据本地客户端日志和本次新会话的原生文件重建客户端轮次与本地工具链路;模型、Token、完整云端生命周期和精确模型耗时可能缺失,推定时间不适合用于精确的模型性能或调用量统计。

Windows 支持情况

AI Coding Agent

集成方式

Trace 上报

日志上报

Token 采集

对话和 Tool Call 采集

适用条件

Claude Code

Hook

支持

支持

支持

支持

-

Codex

Hook

支持

支持

支持

支持

-

Cursor

Hook

支持

支持

支持

支持

-

豆包工作台(Doubao Work,实验性)

只读本地客户端日志

客户端轮次与本地工具

仅元数据

不支持

不支持

仅正式版客户端

Qoder Work

Hook / 本地数据源

支持

支持

不支持

支持

User 版本

Qoder CLI

Hook

支持

支持

不支持

支持

-

Qoder IDE

Hook / 本地数据源

支持

支持

支持

支持

Qoder 1.10.0 或更高版本,User 版本

Qwen Work CN

Hook / 本地数据源

支持

支持

支持

支持

-

OpenCode

插件注入

支持

支持

支持

支持

-

WorkBuddy

Hook 唤醒 / 本地会话采集

支持

支持

支持

支持

WorkBuddy Desktop 5.3.5.0;Windows 11 已完成安装包端到端验证

表中未列出的 Agent 没有明确的 Windows 支持声明,可能在 Windows 上无法运行;如需使用,请自行验证。

前提条件

开始接入前,请确认满足以下条件:

  • 目标 AI Coding Agent 已安装。本机接入时,建议至少使用过一次,使其生成默认配置目录;容器接入时,应在注入前准备好 Agent 的配置目录,或通过 --home 指定受支持 Agent 的写入目录。

  • 已在 AgentLoop 中完成 AI Coding Agent 接入资源初始化,并获取控制台自动生成的安装命令。

macOS / Linux 环境要求

  • 通常无需预装 Node.js 和 npm:安装器会优先下载并固定使用托管的 Node.js 运行时和预编译依赖。

  • 已安装 curl 或 wget。

  • 能够访问安装命令中的 OSS 下载地址。

Windows 环境要求

  • Windows 10 或更高版本。

  • PowerShell 5.1 或更高版本。

  • 通常无需预装 Node.js 和 npm,并能够访问安装命令中的 OSS 下载地址。

Node.js 运行时与平台边界

以下要求跨平台生效,与操作系统无关。

托管运行时回退:如果托管的 Node.js 运行时因平台不支持或下载失败而不可用,安装器会回退使用系统 Node.js;此时要求使用可直接加载 node:sqlite 的 Node.js(22.13+、23.4+ 或更高版本)及 npm。

已知平台边界:使用 musl 的 Linux(例如 Alpine)当前没有对应的托管 Node.js 产物,需要提前准备可直接加载 node:sqlite 的 Node.js(22.13+、23.4+ 或更高版本)及 npm。Windows ARM64 已支持使用 Pilot 托管的 Node.js 运行时。

容器与 Kubernetes 的运行环境、启动顺序和版本要求,请参见下文“容器与 Kubernetes 部署”。

安装 LoongSuite Pilot

本节介绍开发者本机的安装与服务启动方式。容器与 Kubernetes 请参见“容器与 Kubernetes 部署”,避免在镜像构建期间启动后台服务。

对于 AgentLoop 用户,建议直接复制 AgentLoop 控制台自动生成的安装命令执行安装。命令中除 true、false 外的资源名称和接入参数,通常由 AgentLoop 在初始化接入资源时自动生成。

如需自行拼装安装命令,请通过 AgentLoop 控制台获取对应的 CMS、SLS 参数,并在安装命令中替换为实际值。

macOS / Linux 安装步骤

# 执行安装命令,下面所有参数需要替换为上面获取到的参数
curl -fsSL https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.sh -o /tmp/loongsuite-pilot-installer.sh && bash /tmp/loongsuite-pilot-installer.sh install \
  --collect-log "true" \
  --collect-trace "true" \
  --sls-project "您的SLS Project名" \
  --sls-logstore "您的SLS Logstore名" \
  --sls-endpoint "您的SLS Endpoint" \
  --cms-license-key "您的Trace License Key" \
  --cms-endpoint "您的Trace Endpoint" \
  --cms-workspace "您的Trace Workspace" \
  --service-name-prefix "您的服务名前缀"

Windows 安装步骤

# 下载安装脚本
Invoke-WebRequest `
    -Uri 'https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.ps1' `
    -OutFile installer.ps1

# 执行安装命令,下面所有参数需要替换为上面获取到的参数
.\installer.ps1 install `
    -CollectLog 'true' `
    -CollectTrace 'true' `
    -SlsProject "您的SLS Project名" `
    -SlsLogstore "您的SLS Logstore名" `
    -SlsEndpoint "您的SLS Endpoint" `
    -CmsLicenseKey "您的Trace License Key" `
    -CmsEndpoint "您的Trace Endpoint" `
    -CmsWorkspace "您的Trace Workspace" `
    -ServiceNamePrefix "您的服务名前缀"

安装结果与默认目录

通过上述本机安装方式,安装器会自动完成以下操作:

  • 检测本机支持的 AI Coding Agent。

  • 提示选择需要采集的 Agent。

  • 部署对应的 Hook 或插件。

  • 写入本地配置。

  • 启动 LoongSuite Pilot 后台服务。

    安装完成后,执行以下命令查看服务状态,macOS / Linux / Windows 通用:

loongsuite-pilot status
loongsuite-pilot info

默认情况下,LoongSuite Pilot 会把本地配置、运行状态和 JSONL 采集结果写入当前用户目录下的 .loongsuite-pilot 目录。默认路径如下,后续章节提到的配置文件、准入控制文件和本地输出目录均指这些路径:

用途

macOS / Linux

Windows

数据根目录

~/.loongsuite-pilot/

C:\Users\<用户名>\.loongsuite-pilot\

配置文件

~/.loongsuite-pilot/config.json

C:\Users\<用户名>\.loongsuite-pilot\config.json

本地 JSONL 输出目录

~/.loongsuite-pilot/logs/output/

C:\Users\<用户名>\.loongsuite-pilot\logs\output\

Agent 准入控制文件

~/.loongsuite-pilot/agent-control.json

C:\Users\<用户名>\.loongsuite-pilot\agent-control.json

确认服务状态正常后,按“验证接入结果”检查数据是否上报。

验证接入结果

本机安装或修改配置后,可以按以下步骤验证接入是否生效。容器与 Kubernetes 接入请参见下文“容器与 Kubernetes 部署 > 验证容器接入”,先检查 Hook 注册,再触发真实会话验证数据上报。注册成功不等于数据已到达 AgentLoop。

说明

如果重启 LoongSuite Pilot 后发现采集状态异常,请手动执行 loongsuite-pilot start 命令开启采集。

查看本地服务状态

loongsuite-pilot status
loongsuite-pilot info

查看本地采集输出

macOS / Linux:

ls ~/.loongsuite-pilot/logs/output
tail -f ~/.loongsuite-pilot/logs/output/*.jsonl

Windows:

Get-ChildItem "$env:USERPROFILE\.loongsuite-pilot\logs\output"

Get-ChildItem "$env:USERPROFILE\.loongsuite-pilot\logs\output\*.jsonl" |
  Sort-Object LastWriteTime |
  Select-Object -Last 1 |
  Get-Content -Wait

如果本地输出目录中可以看到新事件,说明 AI Coding Agent 采集链路已经生效。

查看 AgentLoop 控制台

触发一次新的 AI Coding Agent 活动后,回到 AgentLoop 控制台查看对应接入任务的数据状态。数据到达时间可能受本地批量发送和后端处理延迟影响。

验证 Agent 采集

如果预期 Agent 没有数据,请按以下步骤检查。agent-control.json 与 config.json 的默认路径请参见“安装结果与默认目录”。

  1. 确认目标 Agent 已安装,并至少使用过一次。

  2. 确认准入控制文件 agent-control.json 中没有将该 Agent 设置为 off。

  3. 确认配置文件 config.json 中没有将该 Agent 设置为 "enabled": false。

  4. 修改配置后,执行 loongsuite-pilot restart。

  5. 触发一次新的 Agent 活动,再查看本地输出或 AgentLoop 控制台。

容器与 Kubernetes 部署

在容器场景中,建议按以下顺序启动:

  1. 安装目标 Agent,并准备配置目录。

  2. 生成或挂载 Agent 配置。

  3. 完成 Hook 或插件注入。

  4. 启动 Agent 进程。

    部分 Agent 只在进程启动时读取配置。应在读取配置前完成注入;在 Agent 已经运行后补写配置,通常需要启动新的 Agent 进程才能生效。

loongsuite-pilot hook install 用于独立执行注入,执行时无需采集进程已经启动。镜像入口和 K8s start.sh 可以在启动业务命令前调用该能力;需要自行渲染配置时,也可以在渲染后显式调用。

容器接入提供以下三种方式,按集群条件和镜像是否可修改选择:

方式

适用条件

注入时机

方式一:集成到业务镜像

允许修改业务镜像

构建期间检查并部署指定 Agent 的采集配置;容器启动时再次检查并注入。需要运行时渲染配置时,可关闭入口自动注入,在渲染后调用 hook install。

方式二:使用 Kubernetes webhook

集群已部署并启用 LoongSuite Pilot webhook

默认注入方式在符合触发条件的 Node/Bun 或 CPython 进程启动前提前执行注入;也可通过 start.sh 自行确定注入时机。

方式三:手工配置 Kubernetes init container

集群没有 webhook,希望通过共享卷提供 Pilot 运行时

由业务容器执行 start.sh,在业务进程启动前完成完整注入。

部署前准备

  • 使用包含 hook install 的 LoongSuite Pilot 发行版及配套容器入口。K8s 场景下,init 镜像需要提供 Pilot 运行时;运行时复制到共享卷并挂载后,业务容器通过 /mnt/pilot/bin/loongsuite-pilot 调用。

  • 建议使用基于 glibc 的 Linux 镜像,例如 Debian 或 Ubuntu;K8s 共享运行时还要求业务镜像具有兼容的 C/C++ 运行库。Alpine 等 musl 环境需另行验证运行时及依赖兼容性。

  • start.sh 需要 Bash。镜像入口需要 POSIX Shell。

  • Pilot、注入命令和 Agent 应使用相同的运行用户、HOME 及 Agent 配置目录。Agent 配置目录和 Pilot 数据目录需要可写。

  • 从 AgentLoop 控制台获取日志与 Trace 接入参数,并确保容器能够访问对应上报地址。

    容器模式安装不注册主机服务,不在构建期间启动采集进程,并关闭自动更新。升级时重新构建业务镜像,或更新 K8s init 镜像版本。

准备上报配置

日志与 Trace 参数与本机接入一致。容器建议在运行时挂载配置文件,以下示例保存为 pilot-config.json,并将占位符替换为 AgentLoop 控制台提供的实际值。

重要

本例使用 WebTracking,目标 Logstore 需要已开启 WebTracking。使用其他鉴权方式时,按对应接入方式填写 sls 配置。

{
  "collectLog": true,
  "collectTrace": true,
  "autoUpdate": { "enabled": false },
  "sls": {
    "mode": "webtracking",
    "endpoint": "您的SLS Endpoint",
    "project": "您的SLS Project名",
    "logstore": "您的SLS Logstore名"
  },
  "cms": {
    "licenseKey": "您的Trace License Key",
    "endpoint": "您的Trace Endpoint",
    "workspace": "您的Trace Workspace"
  },
  "serviceNamePrefix": "您的服务名前缀"
}

只采集日志或只采集 Trace 时,将另一个 collect 开关设为 false。包含接入凭据的文件通过运行时挂载或 Kubernetes Secret 提供,不写入业务镜像。

方式一:集成到业务镜像

适用于允许修改业务镜像的场景。先安装 Agent,再安装 Pilot,并在安装命令中指定容器模式和需要采集的 Agent。

以下示例使用 Claude Code:

FROM node:22-bookworm-slim

ARG PILOT_VERSION
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl bash \
    && rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code \
    && useradd --create-home --shell /bin/bash agent

USER agent
ENV HOME=/home/agent
ENV PATH=/home/agent/.local/bin:$PATH
RUN mkdir -p /home/agent/.claude

RUN test -n "$PILOT_VERSION" \
    && curl -fsSL https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.sh \
       -o /tmp/loongsuite-pilot-installer.sh \
    && bash /tmp/loongsuite-pilot-installer.sh install \
       --mode container --agents claude-code --version "$PILOT_VERSION"

ENV AGENT_DATA_COLLECTION_CONFIG=/etc/loongsuite-pilot/config.json
ENTRYPOINT ["/home/agent/.loongsuite-pilot/entrypoint.sh"]
CMD ["claude", "-p", "hello"]
docker build --build-arg PILOT_VERSION='<Pilot版本>' -t my-agent:instrumented .
docker run --rm --init --stop-timeout 30 \
  --mount "type=bind,src=$(pwd)/pilot-config.json,dst=/etc/loongsuite-pilot/config.json,readonly" \
  my-agent:instrumented

pilot-config.json 应允许容器中的 agent 用户读取。Agent 访问模型服务所需的认证配置仍按其原有方式提供。构建时未通过 --build-arg 传入 PILOT_VERSION,RUN test -n "$PILOT_VERSION" 会使构建失败。

构建期间会检查并部署指定 Agent 的采集配置,失败则构建失败。容器启动时,入口读取运行时的 LOONGSUITE_PILOT_AGENTS;未设置时使用构建期间保存的 Agent 列表,在启动采集进程和业务进程前再次检查并注入。配置未变化时返回 up-to-date。

在启动后渲染 Agent 配置

如果业务命令需要先生成或覆盖配置,将入口的自动注入关闭,再在渲染完成后调用注入命令。将 Dockerfile 中的启动配置改为:

ENV LOONGSUITE_PILOT_AGENTS=none
CMD ["sh", "-c", "/app/render-settings.sh && { loongsuite-pilot hook install --agents claude-code || true; } && exec claude -p \"$TASK\""]

/app/render-settings.sh 为业务配置生成脚本,TASK 为运行时提供的任务内容。none 使入口跳过注入;显式的 --agents claude-code 优先于环境变量,因此渲染后的调用仍会执行。LOONGSUITE_PILOT_AGENTS 只有取精确值 none 时才表示跳过,未设置、空字符串和字面量 null 均按全量探测处理。

|| true 表示采集注入失败时仍启动业务。如果要求注入成功才能执行任务,移除 || true,由非零退出码阻止后续 Agent 启动。

方式二:使用 Kubernetes webhook

适用于集群已部署并启用 LoongSuite Pilot webhook 的场景。webhook 负责注入 init container、共享卷、解释器启动配置和停止钩子。agentLoopSpaceName 使用接入任务对应的标识。

只使用默认注入方式时,在工作负载的 Pod 模板上添加 label:

spec:
  template:
    metadata:
      labels:
        loongsuitePilotAutoEnable: "on"
        agentLoopSpaceName: "<接入空间标识>"
        agentLoopAgents: "claude-code"

agentLoopAgents 用于限定目标 Agent,多个 ID 用英文逗号分隔。默认注入方式在符合触发条件的 Node/Bun 或 CPython 进程启动时提前执行注入。

自行确定注入时机

如果需要先渲染配置,或使用 Hermes Agent、DeepSeek Harness,建议通过 start.sh 在业务进程启动前执行完整注入。以下为现有 Deployment 的配置片段;保留上述 label,并修改业务容器的启动命令:

spec:
  template:
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: agent
          image: my-agent:latest
          command: ["/bin/sh", "-ec"]
          args:
            - |
              /app/render-settings.sh
              exec /mnt/pilot/start.sh --agents=claude-code -- claude -p "$TASK"
          env:
            - name: TASK
              value: "review this PR"

配置已就位时,直接使用:

command: ["/mnt/pilot/start.sh"]
args: ["--agents=claude-code", "--", "claude", "-p", "hello"]

start.sh 指定 Agent 列表时调用完整注入能力。webhook 场景继续使用其注入的上报配置和采集进程启动方式,无需额外设置 PILOT_ENABLE_DAEMON。保留 webhook 注入的环境变量和 preStop。

方式三:手工配置 Kubernetes init container

适用于集群没有 webhook、希望通过共享卷提供 Pilot 运行时的场景。使用包含本次能力的 init 镜像,先将运行时复制到共享卷,再由业务容器执行 start.sh。

先将前面的上报配置保存为 Secret。Secret 与工作负载应位于同一 namespace:

kubectl create secret generic pilot-config \
  --from-file=config.json=pilot-config.json

以下为可用于一次性任务的 Job 模板:

apiVersion: batch/v1
kind: Job
metadata:
  name: pilot-agent-demo
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      terminationGracePeriodSeconds: 30
      volumes:
        - name: pilot-runtime
          emptyDir: {}
        - name: pilot-config
          secret:
            secretName: pilot-config
      initContainers:
        - name: pilot-init
          image: <PilotInit镜像地址>:<版本>
          volumeMounts:
            - name: pilot-runtime
              mountPath: /mnt/pilot
      containers:
        - name: agent
          image: my-agent:latest
          command: ["/mnt/pilot/start.sh"]
          args: ["--agents=claude-code", "--", "claude", "-p", "hello"]
          env:
            - name: PILOT_ENABLE_DAEMON
              value: "true"
            - name: LOONGSUITE_PILOT_DATA_DIR
              value: /mnt/pilot/data
            - name: AGENT_DATA_COLLECTION_CONFIG
              value: /etc/loongsuite-pilot/config.json
          volumeMounts:
            - name: pilot-runtime
              mountPath: /mnt/pilot
            - name: pilot-config
              mountPath: /etc/loongsuite-pilot
              readOnly: true
          lifecycle:
            preStop:
              exec:
                command: ["/mnt/pilot/prestop.sh"]

PILOT_ENABLE_DAEMON=true 用于在无 webhook 的情况下启动采集进程;preStop 为其提供停止前的发送时间。运行时和业务镜像的 CPU 架构及运行库需匹配。

业务配置需要运行时生成时,将容器启动命令改为前文“渲染后执行 start.sh”的形式。

指定配置目录及多身份场景

同一 Agent 使用多个配置目录时,在每个目录配置生成完成后、对应 Agent 进程启动前各执行一次:

loongsuite-pilot hook install \
  --agents claude-code --home claude-code=/workspace/claude-profile --json

--home 用于具有可重定位 Hook 或插件配置路径的 Agent,不应视为所有 Agent 均支持的通用选项。Claude Code 也支持使用 --config-dir <目录> 指定配置目录。Hermes Agent 和 DeepSeek Harness 应先按其要求设置 HERMES_HOME、DSH_HOME,再执行点名注入。

以 Grok Build 的分身份目录为例,在 K8s 共享运行时中执行:

/mnt/pilot/bin/loongsuite-pilot hook install \
  --agents grok-build \
  --home "grok-build=/workspace/.grok/u/<身份目录名>" \
  --json

每个身份分别执行。该命令将 Hook 注册配置写入对应目录的 hooks/loongsuite-pilot.json,并创建缺少的目录。注册文件由 Grok 读取,其中记录事件触发时执行的脚本;采集数据另行写入 Pilot 数据目录。多个身份的注册文件分别保存,后一次注入不会覆盖前一个身份的文件。

验证容器接入

镜像集成场景中 Pilot 已安装在业务镜像内,可直接使用 loongsuite-pilot 命令;K8s 共享运行时通过共享卷提供 Pilot,业务容器内使用绝对路径 /mnt/pilot/bin/loongsuite-pilot 调用。

  1. 在业务容器中检查注册状态。镜像集成使用:

    loongsuite-pilot hook status --agents claude-code --json
    kubectl exec '<Pod名称>' -c agent -- \
      /mnt/pilot/bin/loongsuite-pilot hook status --agents claude-code --json
  2. 查看目标 Agent 的结果。安装返回 ok 或 up-to-date 表示对应注入已完成;失败时根据 reason 和 hint 修正。skipped 表示跳过,不代表已注入。全量探测没有发现 Agent 时可能没有结果项,因此验收时应指定 Agent ID。

  3. 启动一次新的 Agent 会话,在 AgentLoop 控制台确认日志或 Trace 到达。hook status 只检查注册文件,不验证 Agent 是否实际加载该配置,也不验证上报目标是否可达。

  4. 如需排障,检查 Pilot 数据目录中的 last-hook-install.json 和 logs/。默认数据目录为运行用户的 ~/.loongsuite-pilot;手工 init container 示例中为 /mnt/pilot/data。

运行建议

  • 使用显式 Agent 列表进行验收和关键任务注入。hook install 不指定列表时会探测全部已安装 Agent。

  • 容器身份可识别时,点名安装成功后会限制采集部署范围:保留已成功注入和构建期已记录的 Agent。后续需要新增 Agent,应再次点名执行 hook install。

  • Docker 建议使用 --init --stop-timeout 30;K8s 保留停止钩子并设置合适的 terminationGracePeriodSeconds。停止宽限期应覆盖业务退出和采集进程发送缓冲数据所需时间,30 秒只是示例值。

  • 避免使用 K8s postStart 作为注入时机,它与业务入口并发执行,无法保证先完成注入。

  • 配置被模板覆盖后,应重新执行注入并启动新的 Agent 进程。后台修复不能保证已运行的进程重新读取配置。

管理 LoongSuite Pilot

常用命令

本机安装场景的常用命令如下。容器模式安装不注册主机服务,不使用以下服务命令。

命令

用途

loongsuite-pilot status、loongsuite-pilot info

查看服务状态。

loongsuite-pilot start

开启采集。重启 LoongSuite Pilot 后采集状态异常时手动执行。

loongsuite-pilot restart

重启 LoongSuite Pilot,使配置文件中的修改生效。

installer.sh uninstall、.\installer.ps1 uninstall

卸载 LoongSuite Pilot 并保留本地数据。

installer.sh uninstall --purge、.\installer.ps1 uninstall -Purge

卸载并同时移除安装文件和本地数据。

开启本地 Dashboard

本地 Dashboard 默认关闭。如需使用,请在配置文件中将 dashboard.enabled 设置为 true,并重启 LoongSuite Pilot:

{
  "dashboard": {
    "enabled": true
  }
}

Dashboard 会随采集服务一起启动和停止,无需单独执行 monitor 命令。启动后访问以下默认地址;如果配置了自定义端口,请将地址中的 8765 替换为实际端口:

http://127.0.0.1:8765/

卸载 LoongSuite Pilot

uninstall 保留本地数据;--purge(Windows 为 -Purge)会同时移除安装文件和默认数据目录 .loongsuite-pilot 下的本地配置、运行状态与 JSONL 采集结果。Windows 命令中的 .\installer.ps1 来自“Windows 安装步骤”中下载的安装脚本,请在该脚本所在目录执行。

如需卸载 LoongSuite Pilot 并保留本地数据,执行:

macOS / Linux:

curl -fsSL https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.sh -o /tmp/loongsuite-pilot-installer.sh && bash /tmp/loongsuite-pilot-installer.sh uninstall

Windows:

.\installer.ps1 uninstall

如需同时移除安装文件和本地数据,执行:

macOS / Linux:

curl -fsSL https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.sh -o /tmp/loongsuite-pilot-installer.sh && bash /tmp/loongsuite-pilot-installer.sh uninstall --purge

Windows:

.\installer.ps1 uninstall -Purge

配置 Agent 采集

安装完成后,可以通过本地配置文件中的 agents 配置控制是否采集某个 AI Coding Agent。配置文件默认为 ~/.loongsuite-pilot/config.json,Windows 为 C:\Users\<用户名>\.loongsuite-pilot\config.json,完整路径请参见“安装结果与默认目录”。

需要采集 Claude Code 和 Cursor、关闭 Qoder 时,可以使用以下配置:

{
  "agents": {
    "claude-code": {
      "enabled": true
    },
    "cursor": {
      "enabled": true
    },
    "qoder": {
      "enabled": false
    }
  }
}

配置项

说明

enabled: true

开启该 Agent 的采集。LoongSuite Pilot 仍会检测本机是否存在对应数据源。

enabled: false

关闭该 Agent 的采集。

如需开启 multica 采集,可以使用以下任一方式:

  • 安装 LoongSuite Pilot 前,设置环境变量 LOONGSUITE_PILOT_MULTICA_COLLECTION_MODE=on。

  • 在配置文件 ~/.loongsuite-pilot/config.json 中设置如下配置:

    {
      "pipeline": {
        "multica": {
          "mode": "on"
        }
      }
    }

修改后需要重启 LoongSuite Pilot:

loongsuite-pilot restart

重启后触发一次新的 Agent 活动,按“验证接入结果 > 查看本地采集输出”确认配置已生效。

配置数据脱敏

LoongSuite Pilot 可以在规范化事件发送到输出后端前,对常见密钥和个人敏感数据进行脱敏。脱敏适用于 Prompt、Completion、工具参数或工具结果中可能出现凭证或个人敏感数据的场景。

如需开启或调整脱敏策略,请修改本地配置文件 config.json,默认路径请参见“安装结果与默认目录”。

开启全部脱敏规则:

{
  "mask": {
    "mode": "all"
  }
}

仅开启指定脱敏规则:

{
  "mask": {
    "mode": "custom",
    "types": [
      "apiKey",
      "idCard",
      "phone",
      "email",
      "ipAddress",
      "bankCard"
    ]
  }
}

脱敏模式如下。

模式

说明

none

不进行脱敏。未配置 mask mode 时默认使用该模式。

all

开启所有内置敏感数据规则。

custom

只开启 mask.types 中列出的脱敏类型。

脱敏类型如下。

类型

覆盖内容

替换标记

cloudAccessKey

阿里云、AWS、腾讯云风格的 AccessKey ID。

[ACCESSKEY_MASKED]

apiKey

OpenAI-compatible 和常见平台风格 API Key。

[APIKEY_MASKED]

privateKey

PEM 或 OpenSSH 私钥块。

[PRIVATEKEY_MASKED]

databaseUrl

包含密码的数据库 URL。

[DATABASEURL_MASKED]

idCard

经过严格校验的中国内地 18 位身份证号。

[IDCARD_MASKED]

phone

中国内地手机号和固定电话。

[PHONE_MASKED]

email

常见 ASCII 邮箱地址。

[EMAIL_MASKED]

ipAddress

IPv4 地址,包括公网和私网地址。

[IPADDRESS_MASKED]

bankCard

通过发行方号段和 Luhn 校验的高置信度银行卡号。

[BANKCARD_MASKED]

在包含大量纯数字业务标识的日志中,手机号和银行卡号的格式检测可能命中相同形态的数据,建议使用 custom 模式并只开启所需类型。

LoongSuite Pilot 重点扫描可能包含用户或工具内容的字段,例如:

  • LLM 输入和输出消息。

  • 工具调用参数。

  • 工具调用结果。

  • 已知 Agent 内容字段。

    模型名、Token 数、耗时、Git 分支、Workspace 路径等稳定元数据不作为密钥内容字段扫描。

修改配置后,执行以下命令重启 LoongSuite Pilot:

loongsuite-pilot restart

重启后触发一次新的 Agent 活动,按“验证接入结果 > 查看本地采集输出”检查本地输出中对应字段是否已替换为上述替换标记。

常见问题

未发现预期 Agent 怎么办?

请确认目标 Agent 已安装、已使用过一次,并且没有在 agent-control.json 或 config.json 中被关闭。修改配置后,执行 loongsuite-pilot restart。完整检查步骤请参见“验证接入结果 > 验证 Agent 采集”。

本地没有新数据怎么办?

请确认 LoongSuite Pilot 处于运行状态,并在服务启动后触发一次新的 AI Coding Agent 活动,再按“验证接入结果 > 查看本地采集输出”检查本地 JSONL 输出目录。

AgentLoop 控制台暂时没有数据怎么办?

请先确认本地输出中是否已有新事件。如果本地已有事件但控制台暂未展示,请稍后刷新控制台,或检查安装命令是否来自当前 AgentLoop 接入任务。

如何开启数据脱敏?

修改本地配置文件中的 mask 配置,保存后执行 loongsuite-pilot restart。脱敏模式、脱敏类型和配置示例请参见“配置数据脱敏”。

容器中 Pilot 已启动,但首个会话没有数据怎么办?

检查注入是否发生在 Agent 读取配置之前。若业务启动脚本会生成或覆盖 Agent 配置,应在生成完成后执行 hook install,再启动 Agent。修正后以新会话验证,已经结束的会话不能仅靠补写 Hook 注册文件补采。

为什么只打 webhook label 后,Hermes 或 DeepSeek Harness 仍可能缺少启动阶段的数据?

webhook 默认的提前注入覆盖 Hook 和配置插件注入。Hermes 的目录插件和 DeepSeek Harness 的 YAML 配置补丁需要完整部署流程。使用 start.sh --agents=<Agent ID> -- <原业务命令>,可在 Agent 进程启动前完成相应部署。

hook install 返回成功,为什么 AgentLoop 仍然没有数据?

成功表示本次处理的注入配置已写入或无需更新。还需确认目标 Agent 实际读取了该目录、已产生新事件,且采集进程运行正常、上报配置完整、网络和鉴权有效。验收时通过 --agents 点名,并检查该 Agent 的结果项,避免把跳过或未发现目标视为接入成功。

容器中的 Agent 配置目录不是默认目录怎么办?

对支持配置路径重定位的 Agent,使用 hook install --agents <Agent ID> --home <Agent ID>=<目录>;多身份 Grok 在各身份目录分别执行一次。注入命令与 Agent 进程使用相同的用户身份和目录配置,并在 Agent 启动前完成注入。参数适用范围与示例请参见“容器与 Kubernetes 部署 > 指定配置目录及多身份场景”。