本地纳管 Agent 使用指南

控制台条件

接入前确认以下条件：

1. 工作空间已开启 Team 协作。本地纳管 Agent 只能作为 Team Worker 使用，不支持设置为 Leader，且每个纳管 Agent 仅可加入一个 Team。

2. 已创建目标 Team。

3. 当前账号具备 Agent 创建和 Team 管理权限。

4. 已在控制台准备需要分配的模型连接、Skill 和 MCP。

未开启 Team 协作时，控制台不允许创建纳管 Agent。

本地环境条件

运行机器需满足以下要求：

无需预先安装 LoongSuite Pilot。控制台生成的完整启动命令会自动完成 Pilot 的安装或升级。

本地运行时验证

选择本地模型前，先在目标机器终端验证运行时能够正常启动并调用模型。运行时命令不在默认 PATH 中时，记录其绝对路径，供后续接入时配置。

版本要求

版本检查命令：

loongsuite-pilot info
claude --version
codex --version
openclaw --version
qodercli --version

仅需检查实际使用的运行时。本地版本低于最低要求时，先升级运行时，再执行控制台最新生成的完整启动命令。

本地 Skill/MCP 继承功能要求使用控制台当前启动命令安装或升级的 LoongSuite Pilot 和运行时组件。该能力不能仅根据 Pilot 的版本号判断；已有安装未执行过当前启动命令时，重新执行完整的 Pilot 安装配置步骤。核对或提交排障信息时，使用以下命令获取实际版本：

loongsuite-pilot info

版本要求可能随产品升级调整。重新接入时，以本文档和控制台生成的启动命令为准。

创建步骤

1. 在左侧导航栏单击 Team 协作，确认功能已开启。

2. 进入 Agent 页面。

3. 单击右上角的 纳管 Agent。

4. 配置 Agent 名称、描述和系统提示词。

5. 选择模型来源和模型配置。

6. 选择所属 Team。

7. 根据需要分配 Skill 和 MCP。

8. 保存配置，等待 Agent 状态变为运行中。

模型来源

本地模型表示模型配置由本地运行时管理，不表示模型服务部署在本机。控制台无法检查本地账号登录状态、模型额度和本地凭据是否有效。

运行时与模型支持

系统提示词、Skill 和 MCP

以下配置项已在创建步骤（第 2.1 节）完成初始设置；创建完成后，在 Agent 详情页查看和调整：

• 通过 系统提示词 配置 Agent 的职责、工作范围和输出要求。

• 通过 管理 Skills 分配平台 Skill。

• 通过 管理 MCP 分配平台 MCP。

• 通过 Team 配置确认 Agent 的协作关系。

配置更新后需等待系统生效。运行中的 Agent 未获取最新配置时，先确认连接和心跳状态，再重新连接。

进入启动命令页面

Agent 状态变为运行中后，进入 Agent 详情页，在启动命令区域生成命令。需要重新接入、迁移机器或轮换凭据时，单击重新生成启动命令。每次生成的令牌明文仅在当前页面展示，关闭页面后无法再次查看，需要重新签发。

选择访问网络

第一步选择运行机器访问 AgentCore 的网络：

页面会标识当前可用的访问方式，无法确认 VPC 关系时，由环境管理员确认网络条件。网络选项不仅影响 Agent 连接，也影响运行数据上报；连接状态正常但运行数据缺失时，同时检查网络选择和目标地址连通性。

选择操作系统和运行时

第二步选择操作系统和运行时：

• 操作系统：Linux/macOS 或 Windows。

• 运行时：Claude Code、OpenClaw、Qoder CLI 或 Codex。

操作系统必须与实际执行启动命令的机器一致，运行时必须与本机已安装的命令一致。页面同时展示以下信息：

• 本地 Agent 由 LoongSuite Pilot 管理。

• Trace 将上报至当前账号下的云监控 2.0 工作空间，用于运行数据分析。

• 启动命令包含连接凭据和云监控配置。

• 令牌明文仅在当前页面展示。

执行完整命令

生成的启动命令包括两个连续步骤：

1. 安装并配置 LoongSuite Pilot。

2. 连接并纳管 Agent。

单击复制全部，在目标机器上按顺序执行全部命令。不得跳过第 1 步，也不得仅复制第 2 步。

执行要求：

• 以页面生成的命令为准，不手工修改连接凭据和云监控参数。

• Linux/macOS 与 Windows 的命令不可混用。

• 页面关闭后需要重新执行时，重新生成启动命令。

• 启动命令疑似泄露时，立即重新生成，旧命令停止使用。

设置工作目录

工作目录决定 Agent 默认访问和修改的本地文件范围：

• 启动命令包含 --work-dir 时，使用该参数指定的目录。

• 未指定 --work-dir 时，使用执行连接命令时所在的当前目录。

• 建议使用绝对路径，避免 Pilot 服务启动位置变化导致目录不一致。

• 目录应仅授予完成任务所需的权限。

以下示例适用于本地实例已存在、通过重新连接修改工作目录的场景（见第 8.3 节）：

loongsuite-pilot worker connect INSTANCE_ID \
  --work-dir /absolute/path/to/project

命令中的 INSTANCE_ID 为本地实例 ID，可通过 loongsuite-pilot worker list 获取。

验证 Pilot

# 查看服务状态
loongsuite-pilot status

# 查看版本和配置信息
loongsuite-pilot info

status 应显示服务正在运行，版本信息以 info 输出为准。

验证本地实例

# 查看全部实例
loongsuite-pilot worker list

# 查看指定实例
loongsuite-pilot worker status INSTANCE_ID

worker list 应包含新接入的实例；worker status 应能查看运行时、状态、工作目录、Agent、Team、心跳和日志位置。

验证控制台状态

返回 Agent 详情页，确认：

• 部署方式显示为本地纳管。

• 连接状态显示已连接。

• 所属 Team、模型、Skill 和 MCP 与预期一致。

• 最近纳管时间和配置状态正常。

验证 Team 协作

在目标 Team @ 该 Agent，执行只读验证任务：

1. 返回当前工作目录。

2. 列出项目顶层文件。

3. 说明当前可用的 Skill 和 MCP。

4. 不修改文件。

工作目录、Team 或资源配置不符合预期时，先修正接入配置，再执行实际任务。

发起任务

任务描述应明确目标、允许修改的目录、交付物和验收标准。涉及写操作时，先确认工作目录正确。

会话控制

通过 Team 群聊或任务会话发送控制命令时，同时 @ 目标 Agent。控制命令单独发送，不与普通任务内容合并。

任务并发

默认并发数为 2，支持设置为 1～8：

loongsuite-pilot worker connect INSTANCE_ID -- \
  --max-concurrent-tasks 3

并发数用于控制不同会话的同时执行数量，同一会话内的消息仍按顺序处理。并发数会影响 CPU、内存和模型额度消耗，应根据运行机器资源配置。--max-concurrent-tasks 等运行时参数应写在 -- 分隔符之后。

默认资源范围

默认情况下，纳管 Agent 可使用：

• 控制台分配的平台 Skill 和 MCP。

• 项目目录中随项目提供的 Skill。

本地个人目录中的 Skill 和本地 MCP 默认不继承，以避免未经确认的个人资源被 Team 任务调用。

继承本地资源

版本前置条件：

1. 执行 loongsuite-pilot info 查看当前 Pilot 版本和安装信息。

2. 确认本机已执行控制台当前生成的完整启动命令。

3. 旧安装、来源不明的安装或无法识别继承参数时，重新执行 安装并配置 LoongSuite Pilot 步骤，并重新连接 Agent。

启用前确认：

• Skill 和 MCP 来源可信。

• 本地命令及依赖在目标机器可用。

• MCP 权限符合 Team 任务范围。

• Skill、启动参数和项目文件中不包含个人密钥。

确认本地资源可信且符合 Team 使用要求后，启用本地资源继承：

loongsuite-pilot worker connect INSTANCE_ID -- \
  --inherit-local-resources true

启用后，Agent 按所选运行时的标准配置读取本地个人 Skill 和 MCP。平台 MCP 与本地 MCP 同名时，平台配置优先。停用本地资源继承：

loongsuite-pilot worker connect INSTANCE_ID -- \
  --inherit-local-resources false

状态说明

查看日志

worker status INSTANCE_ID 输出中包含日志路径。执行以下命令时，将 LOG_PATH 替换为实际日志路径。

Linux/macOS：

# 查看最近 200 行
tail -n 200 LOG_PATH

# 持续查看
tail -f LOG_PATH

Windows PowerShell：

# 查看最近 200 行
Get-Content -Path "LOG_PATH" -Tail 200

# 持续查看
Get-Content -Path "LOG_PATH" -Tail 200 -Wait

日志和排障反馈中不得包含 token 或完整启动命令。

断开实例连接

loongsuite-pilot worker disconnect INSTANCE_ID

执行后，实例停止运行，本机实例配置保留。通过 worker status 确认状态变为 disabled。

重新连接

loongsuite-pilot worker connect INSTANCE_ID

凭据失效或控制台已重新签发启动命令时，执行新命令更新连接。

修改工作目录

loongsuite-pilot worker connect INSTANCE_ID \
  --work-dir /new/absolute/path

修改后通过 worker status 核对 WorkDir，并在 Team 重新执行只读验证任务。重连时如需同时传入 -- 后的运行时参数，整体替换规则见第 5.3 节。

删除本地实例

loongsuite-pilot worker disconnect INSTANCE_ID
loongsuite-pilot worker delete INSTANCE_ID

删除前需等待实例停止。若提示进程仍在运行，再次查看状态，确认变为 disabled 后再删除。

删除本地实例不会删除控制台中的纳管 Agent。不再使用时，还需在控制台删除对应 Agent。

检查 Pilot 服务

loongsuite-pilot status
loongsuite-pilot info

• 服务未运行：执行 loongsuite-pilot start。

• 服务状态异常：确认没有正在执行的重要任务后，再执行 loongsuite-pilot restart。

• 版本或配置异常：重新执行控制台生成的 安装并配置 LoongSuite Pilot 命令。

重启 Pilot 会影响该机器上的全部本地纳管实例。

检查实例是否存在

loongsuite-pilot worker list

未显示目标实例时，重新生成并完整执行启动命令。

检查实例状态

loongsuite-pilot worker status INSTANCE_ID

重点检查：

• State：当前状态。

• Reason 和 Message：失败原因。

• WorkDir：工作目录。

• Worker 和 Team：Agent 与 Team。

• Heartbeat：最近心跳。

• Log：日志路径。

检查运行时

在目标机器终端直接执行所选运行时命令，确认：

• 命令可被找到。

• 账号登录有效。

• 本地模型配置可用。

• 当前账号能够访问工作目录。

运行时命令不在 PATH 中时，按第 9.7 节查找命令，并按第 9.8 节使用命令路径参数指定绝对路径。

检查网络

• 确认启动命令选择的内网或公网方式与运行机器网络一致。

• 确认运行机器可访问 AgentCore、模型和 MCP 服务。

• 控制台显示已连接但 Trace 缺失时，重新执行控制台最新生成的完整安装配置命令，并检查对应网络连通性。

检查 Team 使用方式

• 确认 Agent 已加入目标 Team。

• Team 群聊或任务会话中已 @ 目标 Agent。

• 使用 /stop 或 /clear 时，控制命令单独发送。

• 任务长时间无进展时，先发送 /stop，再根据需要重新发起任务。

查找运行时命令

Pilot 提示运行时命令不存在时，先在目标机器上查找命令路径。

Linux/macOS：

command -v claude
command -v codex
command -v openclaw
command -v qodercli

Windows PowerShell：

(Get-Command claude -ErrorAction SilentlyContinue).Source
(Get-Command codex -ErrorAction SilentlyContinue).Source
(Get-Command openclaw -ErrorAction SilentlyContinue).Source
(Get-Command qodercli -ErrorAction SilentlyContinue).Source

仅需执行实际使用的运行时命令。命令返回绝对路径表示已找到；无输出表示运行时未安装或未加入 PATH。

找到命令后，执行对应的版本命令确认其可正常启动：

claude --version
codex --version
openclaw --version
qodercli --version

若命令存在但 Pilot 仍无法识别，将查询结果中的绝对路径配置到第 9.8 节对应的 --*-command 参数中。

指定运行时命令路径

Pilot 无法找到运行时命令时，可通过运行时参数指定绝对路径：

运行时参数应写在 -- 分隔符之后。例如：

loongsuite-pilot worker connect INSTANCE_ID -- \
  --codex-command /absolute/path/to/codex

重连时，在 -- 后传入的运行时参数会整体替换原有参数，规则详见第 5.3 节。