常见问题
适用对象
本文适合所有 xAgent 文档读者。
这是什么
本文集中回答使用 xAgent 和阅读手册时的常见问题。
什么时候使用
当你无法判断从哪里开始、某个能力是否稳定、或不知道应该看哪个页面时，先查看本文。
基本用法
应该先读哪些页面？
先读 什么是 xAgent、功能导览与菜单入口，然后按需要进入 第一个任务 或 任务。
为什么有些页面标记为 experimental 或 planned？
因为这些能力仍可能变化。使用手册会说明可用边界，但不会把未稳定接口写成承诺。
普通用户需要理解 AI 技术吗？
不需要。普通用户只需要说明目标、提供材料、确认必要动作并查看结果。模型、协议、底层实现和扩展细节由管理员或维护者处理。
为什么有些页面会出现英文名称？
有些菜单本身使用英文名称，例如 Agent会话、Skill 管理、MCP 配置。使用手册会按页面用途解释，不要求普通用户理解技术含义。
文档站是否包含登录、评论或插件市场？
不包含。文档站是静态手册。
当前版本稳定吗？
当前版本是 v0.0.6.beta，仍属于测试版，适合部署体验、场景验证和社区反馈。界面、Connector 与部分实验能力仍可能调整。
应该如何安装或升级？
推荐运行官方安装脚本：
curl -fsSL https://downloads.xagent.xiagaogao.com/scripts/install.sh | bash
脚本会识别系统与架构、校验发布包，并支持版本固定、无人值守安装和 Connector 选择。Linux 激活失败时会尝试恢复上一版本。完整流程见开始安装。
ProcessSandbox 和工作区隔离是一回事吗？
不是。工作区隔离决定用户和 Session 可以看到、读写哪些文件；ProcessSandbox 负责外部命令实际挂载哪些文件、继承哪些环境，以及进程树和资源限制。
从其他页面整理的问题
以下问题原先分散在入门、使用、部署、架构、开发和参考页面，现统一收录于本页。
Connector 是否由 xAgent 保存目标系统 token？
不应这样描述。目标系统 token 属于 Connector 或目标系统边界。
Connector 是否必须提供 Skill？
可以提供，但不是唯一职责。
Connector 的协议是否已经完全稳定？
当前标记为实验性，接口可能变化。
长期记忆和会话历史、上下文压缩一样吗？
不一样。长期记忆用于跨会话延续明确保留的偏好、决策和边界；会话历史记录当前交互，上下文压缩用于让长会话继续执行。
xAgent 会自动把聊天内容写入长期记忆吗？
不会。只有当前用户消息明确要求记住、保存或长期保留某项信息时，xAgent 才会登记后台写入任务。完整用法见长期记忆。
旧记忆会覆盖当前要求吗？
不会。当前用户输入、工具结果、权限和系统规则优先于旧记忆；过期、冲突或低置信度记忆也不能直接当作已确认事实。
是否可以把所有能力都写成 Agent 的职责？
不可以。Agent 是执行主体，但不同事实有各自 owner。
架构文档是否等同于当前实现？
不一定。标记为 experimental 的内容可能包含目标架构或仍在收口的边界。
新增架构术语要做什么？
必须同步 术语表。
SubAgent 是否使用独立 Session？
当前实现通过独立子会话承载 SubAgent 的目标、状态、工具和结果，并由主会话按任务需要创建和收束。
SubAgent 是否可以直接绕过主 Agent？
不应这样描述。长任务拆分仍需受平台治理。
SubAgent 是否稳定？
当前仍按实验性能力处理。
Tool 是否可以绕过 Session 执行？
不应这样设计。Tool 调用应在明确上下文和治理边界内发生。
Tool 是否应保存业务事实？
通常不应。业务事实应归属于明确 owner。
Tool 错误应该在哪里查看？
先查看当前会话中的 Tool 结果和错误提示；部署维护者还可以结合服务日志定位。当前没有稳定的公共错误码表。
是否必须使用 Qwen3.6-27B？
不必须。它只是当前开发测试环境受资源条件限制后使用的模型之一，不是推荐配置。只要模型具备足够上下文、稳定工具调用和可靠推理能力，就可以接入测试。
小模型可以使用吗？
可以。目前测试过的较小模型包括 Gemma4-12B，也能正常执行长任务。但模型越小，对复杂推理、多工具规划、长上下文保持和 Skill 创建的稳定性要求越高，建议用真实任务测试后再交给普通用户使用。
64k 上下文够用吗？
可以作为最低建议，但并不适合所有任务。xAgent 初始上下文可能接近 20k，任务过程中还会加入文件摘要、工具结果、会话历史和用户补充信息。复杂任务更建议使用 100k 以上上下文。
如果模型服务支持提示词前缀缓存，固定提示词和默认工具说明的重复成本会明显降低。当前测试中缓存率通常在 90% 以上，但上下文窗口本身仍然决定了长任务能保留多少有效信息。
为什么需要工具调用能力？
xAgent 不是聊天的系统。它需要读取文件、写入工作区、调用 MCP、使用连接器、处理触发器和生成产物。没有稳定工具调用能力，很多任务无法可靠完成。
上下文压缩会影响结果吗？
可能会。上下文压缩用于让长任务继续执行，但压缩后的内容是摘要，不等同于完整原文。因此长上下文模型更适合复杂任务，可以减少过早压缩带来的信息损失。
xAgent 是否保存目标系统登录态？
不应这样设计。目标系统登录态属于 Connector 或目标系统。
Agent 是否能看到 connector_channel_id？
不应让 Agent 看到系统级和通道级内部 ID。
Connector 是否就是 Skill？
不是。Connector 可以提供 Skill，但 Connector 本身是外部系统协议桥。
是否可以参考其他项目的 manifest 字段？
可以参考，但不能直接写入 xAgent 官方文档，除非 xAgent 已实现。
Manifest 是否只用于 Skill？
不应提前限定。具体归属以实现为准。
新增字段是否需要更新术语表？
如果字段引入新术语，需要同步更新术语表。
RuntimeConnection 是否等同于 Connector？
不等同。Connector 连接外部系统，RuntimeConnection 更关注执行环境。
是否可以先写接入协议？
不可以。协议未稳定前只保留概念边界。
RuntimeConnection 是否一定暴露给 Agent？
不一定。Agent 通常看到 Tool，而不是底层执行环境。
Skill 是否等同于插件？
不等同。Skill 更偏向任务方法和工具使用规范。
Skill 是否能直接执行代码？
不应这样描述。执行能力应属于 Tool 或 RuntimeConnection。
Skill 是否可以来自 Connector？
可以作为 Connector 给 Agent 的运行时说明，但具体格式以实现为准。
是否需要为 Markdown 写单元测试？
当前不要求。构建和链接检查是最低要求。
搜索插件如何验证？
先确认 npm run build 通过，再在本地启动或预览页面中验证搜索框可用。
文档内容正确性如何验证？
涉及功能行为、命令、配置或 API 时，应回查 xAgent 主仓库代码或已有文档。
技能和工具有什么区别？
工具是可以被调用的具体动作。技能是完成某类任务的方法说明，可能会指导智能体组合多个工具。
会话和任务是一回事吗？
不是。会话是持续工作上下文，任务是要完成的目标。一个会话里可以推进多个任务。
记忆是否等同于聊天历史？
不是。聊天历史属于当前会话，记忆面向长期上下文和跨任务复用。
一定要先创建智能体才能开始吗？
不需要。大多数首次任务可以直接在默认会话中完成。
智能体和会话是什么关系？
智能体负责执行，会话承载上下文。一个智能体可以在会话中工作，但当前会话里的文件、历史、工具状态和用户补充仍属于会话上下文。
什么时候需要多个智能体？
当不同任务需要不同角色、工具组合、权限边界或输出习惯时，可以拆成多个智能体或专家会话。
任务是否一定会拆成很多步骤？
不一定。简单任务通常会直接完成。只有材料很多、步骤复杂或需要中途确认时，才可能分阶段推进。
任务是否等同于一次用户消息？
不等同。一次用户消息可以创建新任务，也可以只是补充材料、修正要求或确认某个步骤。
一个好任务应该包含什么？
至少包含目标、材料、约束和交付格式。越需要工具或文件处理，越应该写清楚输入来源和结果形式。
xAgent 是一个聊天机器人吗？
不是。聊天只是入口之一，xAgent 更关注把任务做完：读取材料、生成文件、等待确认、接入外部系统、归档结果。它可以聊天，但产品目标不是陪聊，而是完成工作。
xAgent 需要安装在每台电脑上吗？
不需要。xAgent 部署在服务器端，用户通过 Web 或扩展的连接器访问。任务执行过程中不要求用户电脑一直开机，用户也可以通过微信等 IM 入口远程提交任务。
任务文件保存在哪里？
任务文件和产物集中保存在服务端工作区，并按用户做隔离。用户只能看到自己的工作区和授权范围内的文件。
数据可以完全私有化吗？
如果使用本地模型或自有模型服务，可以让任务数据留在团队自己的环境中。是否能做到完全私有化，还取决于模型、外部连接、部署方式和管理员配置。
密钥会被发送给模型提供商吗？
正常不会。xAgent 的工具配置使用密钥占位符，实际密钥只在内部调用工具时替换。模型提供商不需要看到密钥实际值。用户也不要把密钥、token 或密码明文写进任务消息。
xAgent 有记忆能力吗？
有。xAgent 具备基础记忆能力，记忆在用户范围内共享，用于保存偏好、长期背景和反复使用的信息。用户也可以通过 MCP 扩展自己的记忆系统。后续也会考虑开放记忆接口，让第三方记忆系统可以和 xAgent 直通。
xAgent 有内置知识库吗？
目前没有内置知识库。知识类能力可以通过 Skill + MCP 扩展：Skill 负责描述如何使用知识和组织回答，MCP 负责连接外部知识库、检索服务或团队已有资料系统。
会话事件从哪里来？
会话事件可以来自外部接口、触发器、连接器，也可以来自其他会话。xAgent 会通过内置事件队列把事件投递到对应的智能体会话中。
连接器是什么？
Connector 负责把微信、Telegram、飞书、浏览器、企业系统或第三方服务接入 xAgent。它可以双向传递消息与文件引用、提供外部工具、管理授权状态，并把外部事件投递到智能体会话中。普通用户主要完成授权和使用，管理员负责准备 Connector 和安全策略。
会话之间可以互相通信吗？
可以，但仅限同一用户下的会话。xAgent 通过会话事件实现会话间通讯，目前有通知和协助两类事件。通知只在界面显示，不进入模型上下文；协助会进入模型上下文，并激活协助任务。跨用户 session 通讯暂不支持，因为这会带来安全风险。
xAgent 是单一专用智能体吗？
不是。xAgent 可以承载多个专用智能体入口。管理员可以为不同工作场景准备不同的智能体、Skill、工具、外部连接和安全策略，普通用户进入对应入口后直接使用。
xAgent 能帮我做新的专用智能体吗？
可以。通常先明确任务场景，再准备专用智能体入口、Skill、工具、外部连接和审批策略。如果只是沉淀一套固定工作方法，可以先让 xAgent 辅助生成 Skill 草稿，再测试、优化和发布。
每个会话都要预先加载所有 Skill 和 Tool 吗？
不需要。xAgent 会话默认具备发现和加载 Skill、Tool 的核心能力。任务执行过程中如果发现当前能力不够，会尝试查找并加载合适的 Skill 或 Tool。这样既节省上下文，也让智能体能按任务需要扩展自身能力。
xAgent 会自动自我进化吗？
默认不会。xAgent 可以通过提示词或自进化 Skill 对特定技能进行持续优化，但这需要明确目标、测试样例、验收标准和发布流程。自进化很有价值，但也有风险，所以 xAgent 对这件事保持克制。
可以自己调整配置吗？
可以。模型、提示词、Skill、工具、外部连接和审批策略等配置可以在系统内维护。很多设置无需重启服务或重建会话；正在运行的执行轮保持当前配置，后续执行再使用新设置。
普通用户需要自己配置工具和技能吗？
通常不需要。管理员可以先配置通用场景、专用智能体、工具、技能和外部连接，普通用户直接在会话里使用。
免费二进制版本意味着什么？
免费二进制版本目前是 v0.0.6.beta 测试版，是了解和评估 xAgent 的入口。用户可以先部署标准版本，体验任务提交、文件工作区、工具、技能和外部连接等核心能力。
免费二进制发布不等同于源码开源。xAgent 未来会视产品成熟度、社区反馈、安全边界和商业可持续性，评估是否开放源码或开放更多生态协作方式。
如果需要企业内部系统接入、统一身份认证、复杂权限、审计合规、专属连接器或深度业务流程改造，通常应按实际需求进行定制集成。
商业版与免费版有什么区别？
商业版与免费版在产品功能上保持一致。目前差别主要体现在可使用的用户数限制上，不会把核心功能拆成免费版和商业版两套体验。
对于家庭部署、小型团队或早期场景验证，免费版已经可以完整体验 xAgent 的核心能力，部署和使用门槛很低。商业版更适合需要更多用户规模、配套支持或定制集成的团队与公司。
xAgent 会提供官方 SaaS 吗？
目前暂无 SaaS 发布计划。xAgent 不希望用户把自己的任务文件、业务数据和外部系统连接存储到官方平台。自行部署时，数据安全、备份、权限和保密责任由部署方负责。
xAgent 使用什么数据库？
当前版本默认使用内置 SQLite 数据库，目的是降低部署和维护难度。xAgent 具备升级到 PostgreSQL 等数据库的能力，适合在团队规模、并发、审计或运维要求提高后再按实际需要升级。
xAgent 适合大型企业平台吗？
xAgent 可以作为企业智能工作门户和业务智能化入口的基础能力，用来承接统一任务入口、文件工作区、工具调用、技能沉淀和外部系统连接等场景。
如果用于大型公司或复杂组织，通常需要结合企业现有系统做定制集成，例如统一身份认证、权限体系、内部业务系统连接、审计要求、数据边界、安全策略、模型网关和专用外部连接。这类场景不是简单安装后立即覆盖全部企业流程，而是以 xAgent 为基础，根据企业已有基础设施逐步接入和扩展。
xAgent 能替代所有业务系统吗？
不能。xAgent 负责组织任务入口和能力调用，外部系统的权限、登录态、业务数据和审计规则仍应由对应系统或外部连接管理。
这里会包含技术实现细节吗？
主线是使用手册。普通使用者优先阅读“开始使用”和“使用手册”；技术资料只作为维护和定制时的补充。
为什么这里只有少量命令？
使用手册只记录已核对、用户常用的入口。测试、评估、迁移类命令应放到更具体的维护文档中。
CLI 是否等同于 API？
不是。CLI 是命令行入口，API 是程序化调用接口。
为什么不列出 config.yml 的所有字段？
使用手册只列用户高频字段。完整字段应以当前代码和配置管理页面为准。
可以把真实密钥作为示例吗？
不可以。示例只能使用占位值。
可以先写常见错误文案吗？
可以写排查方向，但不能编造错误码。
错误码是否需要稳定格式？
需要。稳定后应在本文集中维护。
可以把 Connector 叫插件吗？
不建议。Connector 是外部系统协议桥，不等同于普通插件。
可以把 Memory 叫历史记录吗？
不可以。Memory 和 Session 历史是不同概念。
为什么有些术语保留英文？
Session、Task、Tool、Skill、Connector、Workspace、Memory 是产品和代码中都会出现的固定概念，文档中保留英文可以减少 UI、日志和代码之间的理解偏差。
智能体和 Skill 有什么区别？
智能体是工作入口，Skill 是完成某类任务的方法。一个智能体可以关联多个 Skill。
普通用户需要创建智能体吗？
通常不需要。管理员准备公共入口后，普通用户直接使用即可。如果用户已经熟悉自己的固定工作流程，也可以在个人范围内创建或调整智能体。
为什么我只能看到公共智能体？
可能当前账号没有个人智能体，或权限只允许查看公共入口。以页面显示为准。
为什么看到了工具调用？
这表示 xAgent 正在执行具体动作，例如读文件、查网页、生成文件或调用外部系统。普通用户重点看最终结果和是否需要确认。
为什么任务没有继续？
常见原因是缺少材料、等待审批、等待你补充信息、工具不可用、外部系统未连接，或任务描述不够明确。先看会话里的提示，再补充信息。
可以中途换要求吗？
可以。建议直接说明新的要求，例如“前面的结果保留，但输出格式改成表格”。
什么时候开新会话？
当目标已经变成另一件事，或不希望延续当前上下文时，再新建会话。只是在同一个目标内调整格式、补充材料、换模型或换 Skill，不需要新开会话。
高级设置改错了怎么办？
先回到会话里说明问题，或重新打开高级设置恢复原来的提示词、模型、Skill、Tool 和密钥选择。系统级配置仍由管理员维护。
智能体是否直接保存长期记忆？
不直接保存。记忆是独立能力，智能体只在上下文中使用被投影出来的内容。
智能体是否直接管理外部系统登录态？
不管理。外部系统登录态属于外部连接或目标系统。
智能体是否总是自动执行所有工具？
不会。工具调用需要遵守当前会话、能力选择、权限和审批规则。
子 Agent 是否需要用户手动管理？
通常不需要。用户只需要描述任务目标和验收要求。是否拆分子任务，以及如何汇总子任务结果，由主 Agent 和系统执行过程处理。
审批会阻止所有危险操作吗？
审批能降低风险，但不能替代账号权限、外部系统权限和管理员管理。敏感连接仍应按最小权限配置。
为什么同一个动作有时需要审批、有时不需要？
可能命中了不同资源范围、会话类型或个人策略。应以当前工具参数和个人、系统策略共同计算出的有效判定为准。
审批会阻止整个任务开始吗？
不会。任务可以先执行，只有命中策略的具体工具操作会暂停并等待审批。
可以从微信或 Telegram 处理审批吗？
可以。自 v0.0.4.beta 起，会话进入审批等待状态时，xAgent 会尝试向当前用户全部可用的 IM 消息通道发送审批通知。连接器需要在线、用户已完成认证，并提供可用的消息发送工具。按通知中的 @{approval:id} 和明确的同意或不同意格式回复即可。
普通用户能改系统审批策略吗？
通常不能。普通用户可能只能配置个人审批策略，系统级策略由管理员维护。
我的连接和 Connector 管理有什么区别？
我的连接用于绑定当前用户自己的外部账号；Connector 管理由管理员维护系统级 Connector 服务。
Connector 工具会自动对所有用户可用吗？
不会。可用性取决于 Connector 是否在线、用户是否完成认证、连接状态、工具治理和审批策略。
为什么能收到消息但不能回复？
先检查 Connector health、用户认证和平台权限。微信还需要有效的收件人上下文；context_token 过期后，发送会被阻止，直到上下文重新建立。
长任务会自动拆分吗？
不一定。你可以明确要求“先列计划，确认后再继续”，这样更容易控制过程。
长任务状态在哪里看？
优先在原来的 Agent会话 中查看。生成的文件通常在工作区文件中查看。
中途可以改方向吗？
可以，但要说明哪些结果保留、哪些废弃。例如“保留主题分类，报告结构改成管理层汇报版”。
中途切换模型会立即影响正在执行的一轮吗？
不会立即改写当前正在运行的同一轮模型与工具循环。本轮会固定已经选定的模型，新配置会在后续执行轮生效。切换模型不需要创建新会话，已有历史和文件会保留。
为什么不写命令示例？
因为普通用户主要通过网页提交长任务。底层接口和内部组织方式不作为使用手册主线。
记忆是否自动保存所有消息？
不会。长期记忆需要有价值、可追溯，并且适合未来复用。
记忆是否替代会话历史？
不替代。会话历史用于当前会话上下文，记忆用于长期复用。
记忆规则是否已经完全稳定？
还没有完全稳定。使用时应把它视为辅助上下文，而不是唯一事实来源。
为什么我的菜单比其他用户少？
先确认管理员是否为你的账号启用了高级功能。简洁模式会隐藏会话列表、触发器、智能体、Skill、Tool、MCP 和个人审批策略；管理员专用菜单还需要管理员角色。
第一次使用应该打开哪个菜单？
先进入 Agent会话，写清楚目标、材料、约束和交付要求。需要查看文件时进入工作区文件，需要绑定消息渠道时进入我的连接。
主题和显示密度在哪里？
打开账号管理，在界面相关设置中切换亮色、暗色或跟随系统，并调整显示密度。它们不再是独立侧边栏菜单。
普通用户需要自己配置模型吗？
通常不需要。管理员配置好后，普通用户直接在会话中使用。
后续统一模型管理和任务路由完善后，普通用户会更少感知具体模型选择，只需要说明任务目标。
测试连接成功就代表所有任务都能完成吗？
不一定。测试连接只说明模型服务可用。任务能否完成还取决于能力开关、工具、Skill、外部连接和审批策略。
为什么会话里要切换模型？
不同模型适合不同任务。比如有的适合快速总结，有的适合复杂推理，有的适合工具协作。切换模型不代表要重新开始整个会话。
截图能不能保留 Base URL 和 API Key？
不建议。公开文档或公开渠道中的截图应遮盖内部地址、密钥和账号信息。
会话是否只是聊天记录？
不是。聊天记录只是入口。会话还包含任务上下文、能力选择、文件产物和执行状态。
会话是否保存所有长期事实？
不应该。需要跨会话复用的偏好、决策或背景应进入记忆或其他明确位置。
会话是否可以被子任务执行单元复用？
长任务或拆分任务可能创建独立执行单元。普通用户只需要关注主会话中的状态和回传结果。
技能是否等同于工具？
不是。工具执行动作，技能沉淀方法。技能可以指导 xAgent 使用工具，但不替代工具权限。
技能越多越好吗？
不是。技能太多会让用户难以选择。应优先沉淀高频、稳定、有明确价值的流程。
普通用户必须选择技能吗？
不必须。管理员可以把技能关联到智能体，普通用户直接提交任务即可。
技能修改后是否立即生效？
草稿修改只影响当前草稿测试。发布到私人库后，后续任务可以使用新的个人 Skill。公共库 Skill 需要经过管理员审批和维护流程，已经运行中的任务是否采用新内容，以当前页面和会话行为为准。
任务是否必须一次完成？
不必须。复杂任务可以分阶段推进。你可以要求 xAgent 先列计划，确认后再执行。
任务是否等同于工具调用？
不是。工具只是完成任务的手段。普通用户不需要指定工具名，只要说明想完成的动作。
什么时候需要拆分任务？
当材料很多、步骤复杂、需要等待外部结果或需要多次确认时，建议拆分。
可以让 xAgent 自动保存结果吗？
可以。在任务里明确写“保存为 Markdown / CSV / HTML 报告”等格式。
工具和 Skill 有什么区别？
工具负责执行动作，Skill 负责记录方法。比如“读取 Excel”是工具动作，“如何分析销售数据”更像 Skill。
工具可以直接访问我的本机文件吗？
不可以。工具通常只能访问工作区和授权范围内的文件。
工具调用失败怎么办？
先看失败原因。常见处理方式是补充文件、完成授权、启用连接、调整任务范围，或联系管理员开启工具。
为什么有些工具我看不到？
工具会受账号权限、管理员配置、连接状态、个人 MCP 配置、连接器授权状态和个人开关影响。
触发器会一直等待任务完成吗？
不会。触发器负责启动任务，任务执行过程和结果仍在会话中查看。
为什么触发器没有运行？
可能原因包括：触发器未启用、时间还没到、外部连接不可用、任务被审批策略拦截、配置保存失败。
定时任务能不能直接发送消息？
能否发送取决于工具、连接和审批策略。建议默认先生成草稿，确认后再发送。
什么时候应该删除触发器？
确认不再需要且不会复用时再删除。只是暂停任务时，优先禁用。
工作区是否等同于本机任意目录？
不是。工作区有明确可见性和权限边界。用户只能看到授权范围内的文件。
上传后的文件会自动被处理吗？
不一定。上传只是提供材料。你还需要在任务里说明“请阅读这个文件”或“请分析这个表格”。
为什么找不到生成的文件？
可能任务只在会话里回复了结果，没有保存文件。可以继续要求“请把结果保存为 Markdown 文件”。
可以把工作区文件发给外部系统吗？
可以，但通常需要工具、连接和审批。发送前应检查内容是否适合外发。