多智能体兼容的 3X-UI 自动化部署 Skill

一个可复用的 AI Agent 工作流项目，支持 Codex、Claude、Cursor、Windsurf 等十余种智能体，实现 3X-UI 面板的自动安装与 VLESS Reality 节点管理

• 原作者/维护者：betzaydarobie-source
• 来源平台：github
• 原始标题：setup-3xui-skill
• 原始链接：https://github.com/betzaydarobie-source/setup-3xui-skill
• 来源发布时间/更新时间：2026-05-29T14:17:44Z

|--------|----------|----------| | Codex | ~/.codex/skills/ 目录 + SKILL.md | 提供标准 Skill 结构 | | Cursor | .cursor/rules/*.mdc + .cursorrules | 双路径兼容 | | Windsurf | .windsurf/rules/*.md + .windsurfrules | 双路径兼容 | | Cline | .clinerules/*.md | 专用规则文件 | | Roo Code | .roo/rules/*.md | 专用规则文件 | | GitHub Copilot | .github/copilot-instructions.md | 仓库级说明 | | Aider | .aider.conf.yml + CONVENTIONS.md | 配置文件 + 约定文档 | | Claude/Hermes/OpenCloud/OpenClaw/Gemini | 独立 .md 入口 | 指向 AGENTS.md | \n这种适配策略的核心洞见是：智能体工具正在分化出各自的配置约定，而项目通过提供多入口，确保了最大兼容性，同时通过统一的 AGENTS.md 维护核心逻辑的一致性。\n\n## 故障排查与日志\n\n项目提供了完善的日志机制帮助诊断问题：\n\n- install-3xui.log —— 安装过程详细日志\n- verify.log —— 安装后验证日志\n\n常见问题及排查方向：\n\n- SSH 密码错误：确认密码、用户名、端口是否正确\n- SSH 端口不通：检查 VPS 安全组、防火墙、运营商面板放行规则\n- 官方安装器变更：可能需要更新安装交互解析逻辑\n- 面板登录失败：确认凭证 JSON 中的信息是否仍有效\n- 订阅链接缺失：部分面板配置未暴露订阅 URL，可改用 VLESS 链接\n\n## 实践意义与启示\n\n这个项目代表了 AI 辅助工具向专业化、标准化方向发展的重要趋势：\n\n1. 任务边界清晰：明确限定在 3X-UI 管理场景，避免智能体在不相关任务上误用\n\n2. 多智能体兼容：通过多入口设计，适配主流 AI 编程助手生态\n\n3. 安全优先：从凭证管理、版本控制到操作授权，多层安全设计\n\n4. 自动化与人工监督平衡：自动化执行核心流程，但关键决策（如重装确认）保留人工判断\n\n5. 产物标准化：输出 JSON、Word、二维码等标准化格式，便于后续处理\n\n对于希望构建自己的 AI 工作流的开发者，这个项目提供了一个优秀的参考模板：如何设计智能体友好的接口、如何管理敏感信息、如何适配多平台生态，以及如何在自动化与可控性之间取得平衡。

原作者与来源

• 原作者/维护者：betzaydarobie-source
• 来源平台：github
• 原始标题：setup-3xui-skill
• 原始链接：https://github.com/betzaydarobie-source/setup-3xui-skill
• 来源发布时间/更新时间：2026-05-29T14:17:44Z 原作者与来源\n\n- 原作者/维护者: betzaydarobie-source\n- 来源平台: GitHub\n- 原始标题: setup-3xui-skill\n- 原始链接: https://github.com/betzaydarobie-source/setup-3xui-skill\n- 发布时间: 2026-05-29\n\n项目概述\n\n这是一个专为 AI 智能体设计的可复用工作流项目，用于在 VPS 上自动化安装和管理 3X-UI 面板。项目的核心价值在于其广泛的智能体兼容性——它不仅支持 OpenAI Codex，还适配了 Claude Code、Hermes、OpenCloud、OpenClaw、Cursor、Windsurf、Cline、Roo Code、Gemini CLI、GitHub Copilot 和 Aider 等十余种主流 AI 编程助手。\n\n该项目既可以作为 Codex/OpenAI Skill 使用，也可以为其他能读取项目说明文件的智能体提供标准化的执行流程。这种多智能体兼容的设计理念，代表了 AI 辅助工具向标准化、可移植方向发展的重要趋势。\n\n核心功能与适用场景\n\n项目专注于以下明确的代理任务场景：\n\n- 安装 3X-UI 或 X-UI 面板 —— 自动化执行官方安装脚本\n- 创建后台管理资料 —— 生成面板地址、用户名、密码和 API Token\n- 配置默认 VLESS Reality 入站 —— 自动设置 443 端口入站规则\n- 添加客户端账号 —— 为客户创建独立的节点账号\n- 生成连接信息 —— 输出 VLESS 链接、订阅链接和二维码\n- 导出管理文档 —— 将后台资料生成 Word 文档便于存档\n\n项目明确划定了适用范围：适合 3X-UI 面板管理和客户节点分配，不建议用于泛泛的服务器运维、网站部署或数据库安装等其他场景。这种边界清晰的定位，使得智能体能够更准确地判断何时调用该工作流。\n\n技术架构与文件组织\n\n项目采用模块化的文件结构设计，为不同智能体提供专门的入口文件：\n\n\nsetup-3xui/\n├── SKILL.md Codex/OpenAI Skill 主入口\n├── AGENTS.md 通用智能体执行说明\n├── CLAUDE.md / HERMES.md Claude / Hermes 专用入口\n├── OPENCLOUD.md / OPENCLAW.md OpenCloud / OpenClaw 入口\n├── GEMINI.md Gemini CLI 入口\n├── CONVENTIONS.md Aider 只读约定文件\n├── .cursorrules / .windsurfrules 旧版兼容入口\n├── .cursor/rules/setup-3xui.mdc Cursor Project Rule\n├── .windsurf/rules/setup-3xui.md Windsurf Workspace Rule\n├── .clinerules/setup-3xui.md Cline Rule\n├── .roo/rules/setup-3xui.md Roo Code Rule\n├── .github/copilot-instructions.md GitHub Copilot 说明\n├── docs/OTHER_AGENTS_CN.md 其他智能体中文使用说明\n└── scripts/ 核心执行脚本\n ├── setup_3xui.py 安装面板并生成后台资料\n ├── add_3xui_client.py 添加客户并导出链接/二维码\n ├── make_3xui_doc.py 重新生成 Word 文档\n └── common_3xui.py 通用工具函数\n\n\n这种设计体现了对智能体生态的深刻理解：不同智能体有不同的配置习惯和读取路径，项目通过提供多入口文件，确保每个智能体都能找到适合自己的使用方式。\n\n安装流程详解\n\n安装 3X-UI 面板的过程被封装为一条命令，建议使用环境变量 VPS_PASSWORD 传递密码，避免敏感信息进入命令历史：\n\nbash\nVPS_PASSWORD='你的SSH密码' python3 scripts/setup_3xui.py \\\n --host 192.0.2.10 \\\n --user root \\\n --ssh-port 22 \\\n --system 'Ubuntu-22.04-x64' \\\n --server-name '美国住宅1号' \\\n --owner '客户/项目名称' \\\n --output-dir "$(pwd)/outputs/3xui-192.0.2.10-$(date +%Y%m%d-%H%M%S)"\n\n\n脚本执行以下自动化步骤：\n\n1. SSH 连接验证 —— 使用 expect 处理交互式登录\n2. 执行官方安装器 —— 下载并运行 3X-UI 官方安装脚本\n3. 面板配置 —— 设置或生成面板端口\n4. 凭证保存 —— 记录后台地址、用户名、密码和 API Token\n5. 默认入站创建 —— 自动配置 VLESS Reality 443 入站（可通过 --no-default-inbound 跳过）\n6. 产物输出 —— 生成 JSON 凭证文件、安装日志、验证日志和 Word 管理文档\n\n客户节点管理\n\n添加客户节点的流程同样简洁：\n\nbash\npython3 scripts/add_3xui_client.py \\\n --panel-info '/path/to/3xui-panel-info.json' \\\n --client-name 'customer-a' \\\n --duration '30天' \\\n --inbound-port 443\n\n\n脚本支持丰富的客户端配置选项：\n\n- 到期时间设置：支持 --days 7、--duration '1个月' 或 --expires-at 2026-06-30 等多种格式\n- 流量限制：通过 --traffic-gb 50 设置，传 0 或不传表示不限流量\n- 备注与分组：--comment '试用' 和 --group 'TikTok' 用于客户管理\n- 入站指定：--inbound-id N 可指定特定入站，否则优先使用 VLESS 443\n\n输出产物包括：\n\n- vless-link.txt —— VLESS 连接链接\n- vless-qr.png —— VLESS 二维码\n- subscription-links.txt —— 订阅链接（如面板支持）\n- subscription-qr.png —— 订阅二维码（如面板支持）\n- client-summary.json —— 客户端配置摘要\n- client-node.docx —— 客户端节点文档\n\n安全设计原则\n\n项目在多个层面体现了安全意识：\n\n凭证管理：\n- 建议通过环境变量 VPS_PASSWORD 传递密码，避免写入命令历史\n- 后台地址、用户名、密码仅限管理员保存，不发送给客户\n- 客户仅接收自己的订阅二维码/链接或 VLESS 二维码/链接\n\n版本控制保护：\n- .gitignore 默认排除敏感文件：.env、outputs/、clients/、凭证 JSON、Word 文档、链接、二维码、配置、日志、私钥和证书\n- 提交前需检查 git status，确认无意外文件被加入\n\n操作授权：\n- 不在用户未明确授权的情况下连接或修改任何服务器\n- 安装前确认是否允许重装（避免覆盖已有服务）\n\n多智能体兼容的实现策略\n\n项目最令人印象深刻的是其对多智能体生态的适配策略。不同智能体有不同的配置习惯：\n\n| 智能体 | 配置方式 | 项目适配 |