文档中心

火山引擎 Agent Toolkit

常见问题

以下问题覆盖火山引擎 Agent Toolkit 的能力组成、安装发现、身份执行和数据反馈。遇到具体错误时，请根据问题类型进入对应的安装、Skill 或故障诊断文档。

产品与能力

Agent Toolkit 是一个独立的 AI Agent 吗？

不是。它为你正在使用的 Agent 补充火山引擎知识、流程和执行工具，不替代 Agent 的模型与运行环境。

当前 Code Agent 和托管 Agent 有什么区别？

Code Agent 是接收任务并调用 Toolkit 的开发工具。托管 Agent 是通过 Ark 创建和管理的云上资源，具有自己的模型、配置和会话。安装 Toolkit 不会自动创建托管 Agent。

Agent Toolkit、Plugin、Skills、CLI 和 MCP 有什么区别？

Agent Toolkit 是整体工具包；Plugin 用于安装和管理一组 Skills；Skills 提供任务知识、参考资料和流程；CLI 通过命令执行操作；MCP 提供 Agent 工具连接。它们按用途协作，不要求全部配置后才能使用。

详细说明：核心能力与使用方式

每个云产品都有独立 Skill 吗？

不是。文档检索、云资源操作、故障诊断和 Skill 发现属于通用核心能力；只有已经进入公开 Catalog 的产品或专业工作流，才提供对应的专用 Skill。需要某项能力时，可以让 Agent 使用 volcengine-find-skills 查询。

查看已发布能力：Skills 目录

安装与发现

应该选择哪种安装方式？

希望快速完成基础配置时使用一键安装；希望使用 Agent 自带的 Plugin 管理能力时选择原生 Plugin；需要指定 Agent 或精确选择 Skill 时使用通用 Skills CLI。三种方式都可以获得核心 Skills。

安装时报错 fs/promises 不提供 glob 怎么办？

该错误可能表现为 The requested module 'node:fs/promises' does not provide an export named 'glob'。先运行 node --version，确认执行安装命令的终端使用哪个 Node.js 版本。

当前通用 Skills CLI 需要 Node.js 22.20.0 或更高版本。一键安装器本身支持 Node.js 20，但较早版本 ve 的兼容安装流程也会调用通用 Skills CLI。升级 Node.js 后，在同一终端重新检查版本，再执行原安装命令，无需为此配置云账号凭据。

如果版本已满足要求，保留实际安装命令和脱敏报错，按支持与版本反馈，不要反复修改云账号配置。

一键安装会安装哪些内容？

skills-setup 检测并按需准备 ve 和 CLI 管理的核心 Skills，具体内容随版本变化。专业 Skills 与产品工具按任务补充。它不保证所有产品 CLI 已安装或 MCP 已连接。

安装 Skills 后，是否已经安装所有云产品 CLI？

没有。产品 CLI 按对应 Skill 的任务需要检查和准备；使用 ve tosutil、ve arkcli、ve volclog 或独立产品工具时，仍需核对工具版本、参数和认证。

查询公开文档时提示 operation not permitted 怎么办？

先看报错路径。如果指向 ~/.volcengine/config.json 或 ~/.volcengine/.client_id-*，通常是本地文件权限或 Agent 沙箱限制：CLI 需要在该目录保存配置和文档查询使用的客户端标识，即使查询本身不需要云账号认证。确认目录归当前用户所有，并仅为所需命令或目录授权后重试。不要为此填写 AK/SK、修改云账号权限或关闭整个沙箱。若报错指向其他路径或网络请求，按实际报错继续排查，不要一律归因于云账号认证。

安装时需要填写 AK/SK 吗？

不需要。安装过程不收集云账号凭据。查询公开文档也不需要登录；只有访问或修改云资源时，才需要按照对应 Skill 的提示完成登录或授权。

支持哪些 Agent？

当前文档提供 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 和 OpenClaw 的安装说明。其他兼容 Skills 的 Agent 可以使用通用 Skills CLI 安装，但具体加载方式以对应 Agent 的能力为准。

安装方式和兼容性：安装与配置

安装后 Agent 找不到 Skill 怎么办？

重启 Agent、重新加载 Plugin，或新建任务。

查看 Agent 的 Skills 或 Plugin 列表，确认核心 Skills 已安装。

调用 volcengine-find-skills，确认能够读取 Skills Catalog。

仍无法发现时，按照对应 Agent 的安装方式重新验证安装范围和路径。

Finder 显示安装成功，为什么当前任务仍不能使用新 Skill？

部分 Agent 不能在当前任务中动态加载新 Skill。Finder 确认安装成功后，如果新能力仍不可用，请新建任务，并携带原任务目标和已经完成的上下文继续。

可选能力应该按 Skill 名还是 Plugin 名安装？

按具体 Skill 名安装。Plugin 用于能力分类和发布，不是 Finder 的按需安装目标。让 Agent 先查询 Catalog，再选择最小必要的 Skill 集合。

方舟 Skills 也由 Finder 安装吗？

当前 arkcli-* Skills 从 Ark 官方仓库获取，不在 Volcengine Finder 本地 Catalog 中。按任务获取相应 Skill 与依赖，不推定已随核心 Plugin 安装。

安装 Toolkit 会自动配置 MCP 吗？

不能据此判断。ve mcp 随 CLI 提供，Agent 是否能连接还需检查服务启动和客户端配置；工具可见与云 API 授权成功分别验证。

MCP 提示 missing tool, toolName=search_docs，或只有四项工具怎么办？

先检查 Agent 实际启动的 ve 路径和版本，而不是只检查另一个终端中的版本。旧版 ve 即使能启动 MCP，也可能缺少 search_docs、fetch_docs 或 call_api 的 yes 参数。

按安装与配置升级 ve，重启 MCP 连接后重新列出工具。六项工具已在 ve 1.2.2 上验证；只重装 Skills 或 Plugin 不会升级已运行的 MCP 进程。工具齐全后，再按通过 MCP 接入 Agent 中的步骤完成公开文档搜索与读取，不需要为这项验证提供 AK/SK。

CLI 和 MCP 是否必须同时使用？

不需要。终端、脚本或能够执行命令的 Agent 可直接使用 CLI；需要协议工具连接时配置 MCP。两者是调用方式不同，不是“人用”与“Agent 用”的区别。

身份与执行

ve 命令不存在怎么办？

运行 command -v ve 检查可执行文件。若未找到，按 CLI 的实际安装来源检查程序位置与 PATH，再按安装说明修复。找到文件后还需运行 ve version 核对版本。

ve 已安装，但云账号身份不可用怎么办？

运行 ve sts GetCallerIdentity，同时检查业务返回中是否包含 ResponseMetadata.Error。身份无效时，根据实际环境重新完成 Console Login、AK/SK、STS 或 SSO 配置，并确认 Profile 和 Region 一致。

ve 登录成功后，其他产品和 MCP 都能使用吗？

不能一概判断。ve mcp 的云 API 调用可以使用其运行环境中的 Profile 或默认凭证链，仍需核对账号、地域和权限。HTTP MCP 的访问认证不替代云凭证；Ark、TOS、TLS 等产品工具按各自配置验证。

Agent 执行云资源变更前会要求确认吗？

取决于使用的工具和策略。volcengine-cli 首次调用 ve 原生 API 前会运行 ve configure safety-policy show：策略已启用且规则非空时，按 CLI 的 allow、confirm、deny 判定执行，不额外叠加内置确认；confirm 需要展示目标、参数和影响，取得用户确认后仅对原命令单次追加 --yes 重试，deny 则停止。策略关闭、规则为空或版本不支持时，使用 Skill 内置确认：经核实无副作用的只读操作可直接执行，写操作先确认，破坏性操作说明不可逆影响。策略读取失败或格式错误时停止，不静默回退。ve tosutil、ve arkcli、ve volclog 等产品代理，以及其他专业 Skill 和辅助脚本，按各自规则确认，不套用原生 API 策略。

上述要求是 Skill 的操作指引，不等于工具已经对所有写操作实施强制确认。实际控制还取决于宿主授权、CLI 策略和云侧 IAM。

使用如何计费？

安装工具不代表任务执行免费。云资源创建、模型请求与运行环境等可能产生费用，以所用云产品、模型和 MCP 服务的计费说明为准。

凭据、确认和数据处理说明：安全与数据

数据与反馈

Telemetry 会收集哪些信息？

核心 Plugin 的 Telemetry 用于记录 Skill 加载事件，包括 Agent、Skill、工具和包版本等低敏信息；不会采集文件内容、命令参数值、AK/SK、Token、会话记录或当前工作目录。Telemetry 不能判断任务是否完成或结果是否正确。

遥测覆盖取决于宿主、Hook 和安装方式；纯 Skills 安装不保证相同采集。关闭加载遥测不等于关闭云服务审计或第三方 MCP 数据处理。

如需关闭，请设置环境变量并重新启动 Agent：

反馈问题时需要提供哪些信息？

请提供脱敏后的 Agent 与版本、安装方式、Skill 名称、退出码、ErrorCode、RequestId、Action 和 Region。安全漏洞、凭据泄露或隐私问题不要提交到公开 Issue，请使用仓库 SECURITY.md 中的安全渠道。

可以先描述任务目标和观察结果，不必提交完整日志。volcengine-feedback 可先整理脱敏草稿，经审阅和授权后再公开提交；反馈不阻塞原任务。

反馈入口：支持与版本

方舟模型、Managed Agents 与费用

为什么安装核心 Plugin 后，还不能管理方舟智能体？

核心 Plugin 不默认包含全部 Ark Skills。按安装与配置准备 Ark CLI、任务 Skill 及共享依赖，确认当前对话已加载。然后核对 Ark 登录、目标项目和 Managed Agent 权限。文件安装、工具可执行、账号授权与任务成功分别检查。

创建 Agent 时，业务 Skills 可以稍后提供吗？

可以先明确哪些配置本次完成、哪些待补充；不在没有实际来源和 ID 时挂载 Skill。后续提供业务 Skill 后再核对版本与权限，并测试实际触发效果。仅创建成功不能证明业务任务已经可用。

本地 Skills 安装和云端 Skill 挂载是同一件事吗？

不是。arkcli +connect 向本地 Agent 安装 Ark Skills，指导它操作方舟；Managed Agent 的业务 Skills 是云端配置的一部分，需要针对目标 Agent 单独关联和验证。

Agent Plan 或 Coding Plan 能直接用来管理 Managed Agents 吗？

不能据此判断。套餐的模型调用额度不等于 Managed Agent 控制面权限。管理操作需核对平台登录、项目和授权；显式 API Key 的数据面调用按对应产品规则处理，不与控制面登录混淆。

查不到账单，是否说明没有费用？

不是。先区分请求失败、权限不足、查询范围不匹配、未出账与真实空结果。方舟用量统计和结算账单有不同延迟，单价乘 Token 只能在明确估算条件下使用，不能代替实际账单。参见方舟用量与费用分析。

MCP 已连接，是否能执行全部 Ark CLI 命令？

不一定。以所连接 MCP Server 实际提供的工具为准。ve mcp、Ark 的 MCP 接入与 Managed Agent 挂载的外部 MCP 不是同一连接。CLI 路径可独立使用，不必先配置 MCP。

最近更新时间：2026.10.29 15:14:41

这个页面对您有帮助吗？

有用

无用