开始安装 xAgent
本页适合第一次部署 xAgent 的管理员。它从安装命令开始，带你完成首次打开 Web 控制台时自动进入的系统初始化流程。需要了解服务器准备和私有化部署边界时，请继续阅读私有化部署 AI Agent。
安装前确认
开始前确认：
操作系统建议：xAgent 当前支持 Linux（AMD64/ARM64）和 macOS。对于需要长期稳定运行、开机自启并尽量减少停机的服务端部署，建议优先选择 Debian Linux，并使用 systemd 管理服务。macOS 是 xAgent 的主要开发环境，因此开发、测试和个人部署支持也很好。Windows 暂不建议部署，主要因为当前对 xAgent 所需的沙箱能力支持不足，无法为受控脚本执行提供与 Linux/macOS 等价的安全、可控运行保障。
- Linux 使用 AMD64 或 ARM64，且当前账号具有
root或sudo权限；macOS 也可以使用用户级安装。 - 服务器能够访问
downloads.xagent.xiagaogao.com、模型 API，以及之后准备接入的外部系统。 - 有足够磁盘保存版本化二进制、运行数据、工作区文件和 Runtime Assets。
- 如果准备通过公网访问，先规划 HTTPS 反向代理、防火墙和访问控制。xAgent 本身不终止 TLS。
- 如果是升级已有环境，先备份配置、数据库、工作区、Memory、Skill、Tool 包和已安装 AgentPlugin 的配置与数据。
第一步：运行安装器
Linux 和 macOS 使用同一个安装命令：
curl -fsSL https://downloads.xagent.xiagaogao.com/scripts/install.sh | bash
安装器会自动检测操作系统和 CPU 架构，下载并校验对应的安装包，安装或升级 xAgent，并在 Linux 上创建、启用和启动 xagent-server systemd 服务。
图例来自早期版本。当前安装器先安装 xAgent，再按需安装 AgentPlugin（微信、Telegram、飞书、Database、SSH 和钉钉）；选中后会下载、校验并注册服务，打印接入地址和 API Key。API Key 不要发布到文档、截图或公共日志中。
如果暂时只使用 Web，可以在询问 AgentPlugin 时选择 N。无人值守安装可跳过插件；要安装指定插件则使用 --agent-plugins database,ssh（可选值：all、weixin、telegram、feishu、database、ssh、dingtalk）：
curl -fsSL https://downloads.xagent.xiagaogao.com/scripts/install.sh \
| bash -s -- --yes --no-agent-plugins
第二步：确认安装结果
安装命令结束后，先确认版本：
xagent version
当前目标版本应为 0.0.20.beta。安装命令保持不变，安装器会读取当前发布目录。Linux 还可以检查服务状态：
sudo systemctl status xagent-server
journalctl -u xagent-server -f
从旧 Connector 环境升级时，请运行完整安装器或公开 upgrade.sh，让安装器迁移官方插件的程序、服务、配置和数据目录；不要仅替换 Server 二进制。自定义旧 Connector 需要单独适配。使用企业授权时，请先确认授权的最高版本允许 0.0.20.beta。
安装器成功启动后，默认 Web 地址为：
http://服务器地址:18888/
不要把 18888 直接暴露到公网。生产环境应通过 Nginx、Caddy 或其他反向代理提供 HTTPS，并限制访问来源。
第三步：打开系统初始化
安装并启动成功后，第一次打开 Web 地址时，xAgent 会自动进入“系统初始化”页面，不需要额外寻找设置入口。页面会按顺序显示以下步骤，完成当前步骤后自动进入下一步：
- 配置数据目录。
- 初始化管理员。
- 设置默认模型。
- 准备 Runtime Assets。
- 检查基础运行组件。
- 完成设置并进入工作台。
第四步：配置数据目录
数据目录用于保存 xAgent 数据库、工作区和 Runtime Assets。Linux 生产环境默认使用：
/opt/xagent/data
请填写绝对路径，并确认运行 xAgent 的账号拥有读写权限。数据目录需要持久化保存，不要放在临时目录、容器临时层或会被自动清理的位置。
点击“保存并继续”后，系统会保存目录配置并进入管理员初始化。
第五步：初始化管理员
系统会要求创建第一个管理员登录名和密码。这个账号用于登录控制台、配置模型、管理用户、设置审批策略和维护 AgentPlugin Connector。
建议：
- 使用专用管理员邮箱或账号，不要复用普通用户密码。
- 使用足够长且唯一的密码，并通过密码管理器保存。
- 不要把管理员凭据写入会话、工作区文件或截图。
创建成功后，xAgent 会自动登录并进入模型配置步骤。
第六步：设置默认模型
填写默认模型的连接信息，并点击“测试并保存”。只有模型连接测试通过后，初始化流程才会进入下一步。
页面中的主要字段包括：
- 模型名：在 xAgent 中显示的名称，例如
Qwen3.6-27B。 - Provider 类型：选择模型服务协议，例如 OpenAI Chat Completions。
- 真实模型名：发送给模型服务的实际模型 ID，例如
qwen3.6-27b。 - Base URL：模型服务的兼容 API 地址，按服务要求填写
/v1等路径。 - API Key：模型服务的认证密钥，保存后不要写入文档、截图或公共日志。
- 模型能力：按模型实际能力选择聊天、生成图片、工具调用、视觉、音频和文件。生成图片当前只对支持该能力的 OpenAI-compatible 配置开放。
- 高级选项：需要时再配置超时和其他请求参数。
模型连接测试只说明服务可访问，后续仍建议执行一个真实任务验证工具调用、文件处理和输出保存。模型字段说明见模型配置。
第七步：准备 Runtime Assets
Runtime Assets 是 xAgent 管理的任务运行依赖，供文件处理、本地工具和其他受控执行使用。初始化页面会自动下载、校验并安装这些依赖组件，Python、Node.js 等无需管理员手工安装。
LibreOffice 是例外：发布包不包含其众多系统依赖。需要 Word、PowerPoint、Excel 转 PDF 或 Excel 重算时，管理员必须在宿主服务器上通过系统包管理器安装 LibreOffice，例如 Debian/Ubuntu 执行 sudo apt-get update && sudo apt-get install -y libreoffice；然后用 soffice --headless --version 验证。其他发行版使用对应包管理器。
当页面显示“Runtime Assets 尚未就绪”时，点击“下载并安装”。安装器会从下载站获取对应的运行依赖，完成校验和安装；按钮所在步骤显示“已完成”后，初始化流程才会继续。
等待该步骤变为已完成后再继续。下载或安装失败时，应先查看服务日志和下载连通性，不要绕过初始化流程。
第八步：检查基础运行组件
基础运行组件负责文档解析、命令隔离和其他本地执行能力。xAgent 会自动安装并测试这些组件；测试通过后，管理员还应进入“Agent 治理 > 执行环境”，确认 Runtime Assets 和 ProcessSandbox 均可用。
如果组件检查失败：
- 记录页面上的错误信息。
- 查看
xagent-server服务日志。 - 确认服务器可以访问下载站，且内核支持 Linux 所需的沙箱能力。
- 修复后重新执行检查，不要直接启用不受控的宿主执行。
第九步：完成初始化
确认数据目录、管理员、模型、Runtime Assets 和基础运行组件均已完成后，点击“完成设置”。系统会进入工作台，之后普通用户可以通过 Web 或已接入的 AgentPlugin 使用 xAgent。
最后一步会汇总前面已经完成的项目。确认每一项都显示“已完成”后，点击“完成并进入仪表板”，系统才会结束一次性初始化并正式进入工作台。
首次进入工作台后，建议立即完成一次最小验收：
请回复“安装检查通过”，并说明当前会话是否可以正常调用模型。
如果模型、会话和回复均正常，再上传一个非敏感的小文件，验证工作区文件读取和结果保存。
进入系统后的仪表板
完成初始化后，系统会进入 xAgent 仪表板。这里可以查看 Token 使用情况、模型和工具调用次数，以及当前会话状态；后续可以从仪表板进入 Agent 会话、工作区文件和治理配置。
AgentPlugin 是可选项
AgentPlugin 不影响 Web 控制台的基本使用。安装器已安装插件时，管理员打开“Agent 治理 > AgentPlugin Connector”，填写安装器输出的地址和 API Key；普通用户在“运行治理 > 插件连接”绑定自己的账号或资源。没有安装时，可稍后按照AgentPlugin 使用手册完成接入。Database 和 SSH 的配置见 Database AgentPlugin 和 SSH AgentPlugin。