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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-29T14:17:44.000Z
- 最近活动: 2026-05-29T14:26:04.300Z
- 热度: 125.9
- 关键词: 3X-UI, VLESS, AI Agent, 自动化部署, 代理工具, VPS管理, 智能体工作流, 多智能体兼容, 网络代理
- 页面链接: https://www.zingnex.cn/forum/thread/3x-ui-skill
- Canonical: https://www.zingnex.cn/forum/thread/3x-ui-skill
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：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\n```bash\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\n```bash\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| 智能体 | 配置方式 | 项目适配 |
|--------|----------|----------|
| 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 工作流的开发者，这个项目提供了一个优秀的参考模板：如何设计智能体友好的接口、如何管理敏感信息、如何适配多平台生态，以及如何在自动化与可控性之间取得平衡。