LoongSuite Pilot 常见问题

1 支持哪些系统和 Agent

Pilot 提供 macOS、Linux 和 Windows 安装方式，但不同系统支持的 Agent 和采集字段并不完全一致。v1.11.0 的 Agent 集成包括 Claude Code、Codex、Cursor、Qoder 系列、OpenCode、OpenClaw、Qwen Code CLI、Hermes、DSH、Grok Build、Kiro CLI、MiMo Code、Pi Coding Agent、WorkBuddy、Wukong 等。

Windows 应按官方支持矩阵选择 Agent，不能把 Linux/macOS 的列表直接当成 Windows 承诺。例如部分 Windows 集成不提供 Token，某些桌面产品还限制 User 安装版本。部署前对照AI Coding Agent 接入文档核对准确的 Agent 名称、版本和操作系统；“能安装”不等于该组合已验证全部采集能力。

2 需要预装 Node.js 和 npm 吗

受支持平台通常不需要，安装器会优先下载固定的 Node.js 运行时及预编译依赖。

v1.11.0 在托管运行时不可用时需要系统 Node.js 18+ 与 npm，且实际运行时必须能加载该安装包的原生依赖。Linux musl（如 Alpine）和 Windows ARM64 需要特别确认运行时和依赖适配。不要直接复制其他 OS/架构的 node_modules，也不要只根据当前终端 node --version 判断后台服务使用的版本。

3 安装后提示找不到 loongsuite-pilot 命令

先重新打开终端，确认用户级命令目录已加入 PATH，默认入口位于用户目录下的 .local/bin，Windows 检查 %USERPROFILE%\.local\bin。

若新终端仍找不到，检查安装是否完成、安装用户是否与当前用户一致，以及该目录内的入口文件是否存在。不要先用管理员/root 身份重复安装，这可能产生另一个用户的数据目录或服务。

4 如何确认 Pilot 正在运行

人工查看可执行以下命令：

loongsuite-pilot status

collector 运行状态与 updater 状态需要分别检查：updater 运行不代表采集服务运行，collector 运行也不代表目标 Agent 已产生数据。

随后完成一轮新的 Agent 交互，检查本地事件和目标后端——本地产生新事件且后端能查到对应数据，才说明采集上报链路正常。需要严格只读诊断时，使用 SOP 的 PID、进程和日志交叉检查。loongsuite-pilot info 可能显示完整配置，不要直接将输出发给他人。

5 安装或修改配置后，需要重启什么

修改 Pilot 配置后通常需要重启 Pilot：

loongsuite-pilot restart

安装或更新 Hook 或插件后，目标 Agent 也可能需要新开进程或重启才能加载，OpenClaw Gateway 等长驻进程尤其需要确认插件是否已加载。先结束当前工作或安排维护窗口，再按对应 Agent 的方式重启；修复后以新会话验证，不只检查历史数据。

6 支持容器、多用户或自定义目录吗

可以按相应部署方式配置，但 Agent 与 Pilot 必须能访问同一份需要采集的数据，Hook 指向的脚本和 Node 路径也必须在执行环境可达。

排查时确认实际运行账号、HOME/USERPROFILE、Agent home、Pilot 数据目录和配置文件。宿主机安装 Pilot 不等于容器内完成接入，当前 shell 的环境变量也不一定传给后台服务。解决路径问题时，不要开放所有目录权限或让所有进程改用 root。

7 安装成功，为什么某个 Agent 仍然没有数据

按以下顺序检查：

1. 目标 Agent 是否已安装，并产生过一次新的活动。

2. config.json 的 Agent 开关、agent-control.json 的准入项是否关闭。

3. 对应 Hook/插件是否部署到 Agent 实际读取的配置目录，脚本是否存在并能执行。

4. Pilot 是否发现并启动对应 Input，以及源文件是否有本次会话数据。

   安装退出码只表示安装流程的结果，不能替代真实交互验证，检查方法见 SOP 步骤 2～4。

8 本地有 JSONL，为什么 ARMS 没有 Trace

本地 JSONL 是标准事件，Trace 还需要轮次聚合、事件转换和远端导出。

确认 collectTrace 已开启，并配置当前接入任务的 cms 或正确的 otlpTrace 目标；再检查轮次是否结束、是否有转换/导出错误，以及查询的工作空间、服务名和时间范围是否正确。collectLog=true 只控制 SLS 日志上报，不会自动开启正确的 Trace 目标。

9 logs/output 没有文件，是否说明没有采集

不一定。JSONL 默认开启，配置摘要为 {} 只表示未显式配置，不代表关闭。先确认 jsonl.enabled、jsonl.outputDir，以及 Pilot 服务环境中的 JSONL_ENABLED、JSONL_OUTPUT_DIR 覆盖，输出可能写到自定义目录。没有新交互、尚未完成的轮次、权限问题和 Input 未启动也可能造成无新文件。全部输出通道未启用时，Pilot 还可能回退到本地 JSONL，不能仅凭关闭一个开关就认定绝不会写本地文件。

如果 JSONL 被有意关闭，可以使用已经启用的输出通道判断。临时开启 JSONL 会增加磁盘写入，且可能保存消息内容，应只在必要时开启。

10 服务名为什么带有 codex 等后缀

Trace 服务名基值的优先级为：顶层 serviceName → 旧式 otlpTrace.serviceName → serviceNamePrefix（默认 loongsuite-pilot）。若需要固定服务名，设置顶层 serviceName，此时不再添加 Agent 后缀；使用后两者时仍添加后缀，例如 <serviceNamePrefix>-codex。SLS 事件命名应单独核对，不套用 Trace 的 otlpTrace.serviceName 配置。

改名不会重命名历史数据，查询时使用当前实际服务名；多个 Agent 共用一个服务名时，再按 Agent 类型、会话或 Trace ID 区分。

11 按 Trace ID 查不到，但稍后或扩大时间范围又能查到

Trace 的模型调用时间、本地聚合完成时间和后端日志时间可能不同，查询窗口过窄可能排除已经上报的记录。

先核对目标和字段，再扩大到覆盖整轮交互及发送之后的时间范围；也可先按服务名查看近期数据、确认记录已上报，再用 Trace ID 精确查询。不要将单次空查询直接解释为丢失数据，也不要承诺固定几秒内必定可见。SOP 中提供了服务端查询方法。

12 有 SLS 日志，为什么没有 Trace；有 Trace，为什么没有 SLS 日志

它们是独立输出：

分别检查目标、开关和鉴权，同一个后端的成功不能证明另一个后端成功。v1.11.0 可以同时配置 cms 与 otlpTrace；如同时启用，它们可分别收到数据。

13 SLS 三种认证方式应该如何选择

使用接入任务或目标 Logstore 指定的方式：WebTracking、AK/SK 或 API Key。不要把 API Key 当作 WebTracking 参数，也不要为同一个目标同时设置 API Key 和 AK/SK。

遇到 401/403 时，核对认证模式、凭据所属目标及写权限；遇到 404 时，核对目标地址和资源是否存在。提交工单时不要粘贴真实凭据。

14 发送失败后会自动恢复所有历史数据吗

不能作此保证。Pilot 有发送重试和失败诊断机制，但这些机制不等于无限期、可靠的离线消息队列。

v1.11.0 的 logs/sls-failed-logs/ 只保存错误与批次元信息，不能用于重放完整事件；logs/otlp-failed/ 可保存失败 Span，但存在保留与容量限制，文件存在也不代表会自动重放。修复后先验证新数据；历史数据处理需评估可用原始资料及重复风险。

15 为什么 Token 缺失或为零

先判断源 Agent 或模型 Provider 是否返回了用量，再检查解析与展示。Kiro CLI 的当前源数据不提供 Token；失败、取消和部分流式调用也可能没有完整用量。

某些集成从 SQLite 或其他晚到数据补充 Token，因此会话刚结束时未必立即完整。缺失不应自动补为 0，源端真实 0 也不能由采集器推算成实际消耗，应以具体 OS、Agent、Provider 和调用结果判断。

16 Token 看起来翻倍，如何统计

Trace 中 LLM Span 记录单次调用用量，AGENT Span 可以记录该轮的汇总。统计时统一选择一个层级，不能将 AGENT 汇总和它下面的 LLM 用量再次相加。

比较缓存 Token 时还要确认 Provider 对 input、cached input 和 cache creation 的定义。不要在未确认口径时把所有 Token 字段简单相加，也不要直接将采集用量当作账单金额。

17 为什么 Prompt、回复或工具参数看不到

检查 Agent 的 captureMessageContent、Trace 的 otlpTrace.captureMessageContent 以及 mask 脱敏设置。内容关闭或被脱敏时，仍可保留可获得的模型、Token、时间和关联字段，这是预期行为。

源端未提供的内容无法恢复。关闭规范化输出中的内容，也不代表 Agent 自身 transcript 或所有插件源文件都被清空，原始数据仍按其自身权限和保留规则管理。

18 工具报错或 Trace 标红，是否表示 Pilot 上报失败

不一定。工具执行失败、模型返回错误或用户取消，都可能被正常采集为错误 Span。

如果服务端已经查到该错误 Span，且与本地 Span ID、状态和关键字段一致，说明这条错误记录已上报。Pilot 导出失败应检查 exporter 错误、目标后端和失败记录，不能仅根据业务 Span 的错误状态判断。

19 历史会话、子 Agent 和重复数据如何判断

Pilot 使用游标、快照和各 Agent 的生命周期信号增量采集，不提供对所有 Agent 统一的“安装后自动回填全部历史”保证。子 Agent 的关联能力也取决于源端记录和对应集成，不保证所有后台子任务都能自动拼成完整调用树。

判断重复时，先固定目标后端、服务名、Trace ID 和 Span ID。请求/响应事件、父子 Span、重试尝试以及不同后端输出不能直接视为重复。不要删除 checkpoint 试图解决重复或补历史，应按 SOP 定位具体 Input。

20 升级后无数据，怎么处理

先确认实际运行版本、Node 路径、collector 状态及本次升级后的错误。目标 Agent 的 Hook/插件和信任配置可能需要重新加载，不要只看更新器显示成功。

21 磁盘占用增加，怎么处理

磁盘排查区分标准事件、原始日志、Trace debug 与失败文件。debug 会增加写入量，完成诊断后恢复原设置。日志受保留和容量策略控制，不应依赖本地文件作为无限期备份；也不要为腾空间直接删除 checkpoint、Agent 数据库或全部失败证据。需要回滚或清理时先明确影响范围。

22 Claude Agent SDK 使用独立配置目录时怎么接入

v1.11.0 支持在 Linux/macOS 上于 SDK 子进程启动前执行以下命令：

loongsuite-pilot inject --agents=claude-code --config-dir=/实际会话配置目录 --json

先完成客户配置写入，再注入；SDK 使用相同 CLAUDE_CONFIG_DIR 并允许加载用户级 command Hook。注入后不要再用模板覆盖目录。

23 图片、本地拦截和模型网关联链属于默认采集吗

这些是 v1.11.0 的专项能力，需要分别配置并核对适用 Agent，不能作为普通文本采集的必备条件。

首轮排查先确认基础采集与上报，再按具体版本处理专项问题。

24 无法解决时需要提供哪些信息

提供 OS、Pilot/Agent 版本、部署方式、问题时间和时区、预期服务名、已完成步骤、脱敏错误摘要，以及一个可用于查询的 Trace ID。必要时附仅含字段摘要的本地与服务端对账结果。

不要提供完整 config.json、License Key、AK/SK、API Key、带凭据的安装命令或完整对话。诊断步骤与材料模板见LoongSuite Pilot 接入无数据排查。