# Agent 如何接管 1Panel 运维：官方 MCP / Skill 与第三方 CLI 全实测

> 1Panel 智能体运维全盘点：官方 MCP、官方 Skill、第三方 CLI 源码级实测对比，含反向代理能力与踩坑清单

# Agent 如何接管 1Panel 运维

给智能体（Claude / Cursor / OpenClaw / DSH 等）接上 1Panel，让它帮你查状态、开网站、建反代、管容器。这篇把目前能用的项目全部过了一遍，**关键结论都下到源码级核对**，不是照抄 README。

---

## 一、结论先看

| 需求 | 该用哪个 |
|---|---|
| **建反向代理 / 网站 / 证书 / 数据库** | 官方 `mcp-1panel`（唯一原生支持，schema 完整） |
| **看容器 / 日志 / 计划任务 / 节点 / 监控** | 官方 `1Panel-skills`（免自己算签名，覆盖最宽） |
| **脚本化、多实例批量** | 第三方 `liyown/1panel-cli`（命令 `1p`） |
| **深度操作（Compose / 防火墙 / 快照 / 文件）** | 第三方 `EaveLuo/1panel-mcp`（286 工具，但要谨慎） |
| **面板自身起停 / 改端口 / 去 2FA** | 内置 `1pctl` |

核心判断：**官方两个项目是互补的，不是替代关系**——一个能写但看得窄，一个看得全但只读。要真正好使，两个都装。

---

## 二、官方方案

### 1. `mcp-1panel` —— 官方 MCP Server（Go）

仓库：https://github.com/1Panel-dev/mcp-1panel

这是最直接能接进任意 MCP 客户端的一个。

**传输方式**

- `stdio`（默认，本地客户端首选）
- `streamable-http`（可自签本地 CA + HTTPS 证书，自动续期）

> ⚠️ **`sse` 已废弃**。默认分支 `dev-v2` 的 `main.go` 里 transport 的 switch 只有 `stdio` 和 `streamable-http`，传 sse 直接报 `unsupported transport`。网上大量 2025 年的教程还在教 sse 配置，照抄会起不来。

> ⚠️ **默认分支是 `dev-v2`，不是 `main`**。`main` 上的 README 停留在 v1 时代（只有 stdio/sse、没有权限分级）。mcp.so、FlowHunt 等站点转载的也是旧版内容。看文档认准 `dev-v2`。

**权限分级（默认最严）**

| 级别 | 包含 |
|---|---|
| `readonly`（默认） | 查询、列表、状态读取 |
| `readwrite` | 上述 + 建网站 / 建证书 / 建数据库 |
| `full` | 上述 + 安装应用（OpenResty / MySQL） |

权限在**工具注册阶段**就生效——被禁用的工具不会出现在 `tools/list` 里，也调不到。这点做得比多数 MCP server 干净。

设 `-access-level` 或 `MCP_ACCESS_LEVEL`，命令行优先。

**配置**

```jsonc
{
  "mcpServers": {
    "mcp-1panel": {
      "command": "mcp-1panel",
      "env": {
        "PANEL_HOST": "http://192.168.1.2:9999",
        "PANEL_ACCESS_TOKEN": "<面板 API Key>",
        "MCP_ACCESS_LEVEL": "readwrite"
      }
    }
  }
}
```

HTTP 传输（远程场景）：

```bash
MCP_AUTH_TOKEN=<强随机串> \
PANEL_HOST=<面板地址> \
PANEL_ACCESS_TOKEN=<API Key> \
mcp-1panel -transport streamable-http \
  -addr "https://127.0.0.1:8000/mcp" \
  -tls-hosts "localhost,127.0.0.1"
```

首次启动会把 CA 路径和 SHA-256 指纹打到 stderr，客户端要把生成的 `ca.crt` 加进信任，**不要关证书校验**。HTTP 传输强制要求 Bearer token（私有 `X-MCP-Token` 头不接受）；这是面向单用户私有部署的预共享密钥模式，不是 OAuth。

**工具清单（共 11 个）**

| 工具 | 分类 | 最低权限 |
|---|---|---|
| `get_dashboard_info` | 系统 | readonly |
| `get_system_info` | 系统 | readonly |
| `list_websites` | 网站 | readonly |
| `create_website` | 网站 | readwrite |
| `list_ssls` | 证书 | readonly |
| `create_ssl` | 证书 | readwrite |
| `list_installed_apps` | 应用 | readonly |
| `install_openresty` | 应用 | full |
| `install_mysql` | 应用 | full |
| `list_databases` | 数据库 | readonly |
| `create_database` | 数据库 | readwrite |

**安装**：Releases 下二进制 / `go install github.com/1Panel-dev/mcp-1panel@latest` / `make build` / Docker 镜像 `1panel/1panel-mcp-server`（多架构：amd64、arm64、arm/v7、s390x、ppc64le）。

---

### 2. `1Panel-skills` —— 官方 Agent Skill + 签名 CLI（TypeScript）

仓库：https://github.com/1Panel-dev/1Panel-skills

官方为 agent runtime（OpenClaw / Hermes 这类）出的 skill，**自带签名好的 CLI**，省掉自己算签名的麻烦。

**覆盖 8 个模块**

| 模块 | 范围 |
|---|---|
| `monitoring` | 仪表盘指标、当前节点、TOP 进程、监控历史、GPU 历史 |
| `websites` | 网站列表/详情、Nginx 配置、域名、HTTPS、证书、网站日志 |
| `apps` | 应用目录、已装应用状态、服务、端口与连接信息 |
| `containers` | 容器列表 / 状态 / inspect / stats / 日志 |
| `logs` | 操作日志、登录日志、系统日志文件 |
| `cronjobs` | 计划任务列表/详情、下次执行预览、执行记录、记录日志 |
| `task-center` | 任务中心记录与执行中数量 |
| `nodes` | 节点列表/选项/状态（部分需 Pro/XPack） |

**CLI 用法**

```bash
export ONEPANEL_BASE_URL="http://192.168.1.2:9999"
export ONEPANEL_API_KEY="<API Key>"

node dist/scripts/cli.js modules                          # 列模块
node dist/scripts/cli.js actions monitoring               # 列动作
node dist/scripts/cli.js run monitoring getCurrentNode
node dist/scripts/cli.js run websites searchWebsites --input-json '{"page":1,"pageSize":20}'
node dist/scripts/cli.js request GET /api/v2/dashboard/base/os
node dist/scripts/cli.js sign                             # 打印当前鉴权头
```

可选环境变量：`ONEPANEL_TIMEOUT_MS`、`ONEPANEL_SKIP_TLS_VERIFY`。仓库自带 `dist/` 预构建产物，正常用不需要 `npm run build`。

> ⚠️ **当前是纯只读巡检。** 写操作（create / update / delete / restart）在代码里只"预留了定义"没实现，SKILL.md 还明令禁止智能体编造写流程。所以它能帮你看得很全，但改不了任何东西——想建反代得靠上面的 `mcp-1panel`。

签名用的是老式 `md5("1panel" + API_KEY + timestamp)`。1Panel v2 服务端仍兼容，但官方新接口推荐 HMAC-SHA256。

---

### 3. `1pctl` —— 面板内置维护 CLI

装 1Panel 就自带，**只管面板自身**，不碰业务资源：

```bash
1pctl status | start | stop | restart | uninstall
1pctl user-info | listen-ip | version
1pctl update username|password|port
1pctl reset domain|entrance|https|ips|mfa
1pctl restore
```

跟"用智能体做资源运维"基本无关，别在这上面花时间。另有 `1panel app init -k <名称> -v <版本>` 用于应用打包。

---

## 三、第三方方案

### 1. `EaveLuo/1panel-mcp` —— 工具数最多的社区版

- 仓库：https://github.com/EaveLuo/1panel-mcp（默认分支 `master`）
- npm：`1panel-mcp-server`，命令 `1panel-mcp-server` 或 `1pmcp`

```bash
npm install -g 1panel-mcp-server
1pmcp start --key your-api-key
# 或
1panel-mcp-server start --host 192.168.1.100 --port 8080 --key your-api-key
1panel-mcp-server tools        # 列出全部工具
```

**实测核对结果：**

| 项目 | 结论 |
|---|---|
| 工具数量 | README 宣称 264，**实测代码里 286 个唯一工具定义**（偏保守，不是虚标） |
| API 版本 | **只走 `/api/v2`**——全包 `api/v2` 出现 289 次，`api/v1` **0 次**。所以它是 v2 项目，不是老版本 |
| 模块覆盖 | 容器/镜像/网络/卷/Compose、应用商店/运行环境/PHP/Node、文件/备份/回收站/快照、MySQL/PostgreSQL/Redis、网站/SSL/Nginx/AntiLeech、监控/进程/计划任务/防火墙/Fail2ban、SSH/ClamAV、AI Agent/MCP Server/Ollama/GPU、远程主机 |
| GitHub star | **0** |
| npm 版本 | 只有 `1.0.0` 一个版本，2026-03-18 发布后未再更新 |
| npm `repository` 字段 | **空**（靠 name/version/bin 与仓库 `package.json` 完全一致才能对应上） |

**它最大的设计缺陷：写操作是裸透传。**

`create_website` 的 schema 是 `site: { type: "object" }`，handler 就一行 `client.createWebsite(args?.site)`——**没有任何字段约束和提示**。整个包里 grep `proxy` 是 **0 次**，没有反向代理的专门工具。对比官方版把 `static|proxy` 分支、必填校验、地址格式全做进 schema，差距就在这里：**工具多 ≠ 覆盖好**，裸透传意味着智能体只能靠猜 body 形状。

另外同作者还出了个 skill 形态的 `1panel-skill`（宣称 580+ endpoints），也是裸 API 暴露思路。

> **建议**：确实需要容器/Compose/防火墙/快照这些官方完全没覆盖的领域再上，且**先在测试面板用**。286 个工具 = 286 个能改你服务器的入口，而它没有官方那种 `readonly/readwrite/full` 分级，默认就是全开。

---

### 2. `liyown/1panel-cli` —— 第三方独立 Go CLI（命令 `1p`）

仓库：https://github.com/liyown/1panel-cli

这个做得相当规范，**是我最推荐的非官方方案**。

```bash
go install github.com/liyown/1panel-cli@latest   # 需 Go 1.26+

1p context add production --server https://panel.example.com --api-key-stdin
1p context use production

1p node list
1p website list --all
1p website restart example.com
1p container inspect nginx -o json
1p container logs nginx --tail 100 --follow
1p app search redis
1p app install redis --name redis-main --set port=6379 --wait
1p task wait TASK_ID --logs
```

**亮点：**

- **API Key 存系统 Keychain**，不落配置文件；回退方案是独立 `credentials.yaml`（`0600`），绝不写进 `config.yaml`
- 多 context + `--node node-01` 打远程节点（多节点列表是 Pro/Core 端点，社区版仍可操作本机 Agent 资源）
- 输出支持 `table / json / yaml / name / Go template`；**stdout 只有结果，错误和警告走 stderr**——对脚本和 agent 解析非常友好
- 环境变量全覆盖：`ONEPANEL_CONTEXT`、`ONEPANEL_BASE_URL`、`ONEPANEL_API_KEY`、`ONEPANEL_NODE`、`ONEPANEL_TIMEOUT`、`ONEPANEL_OUTPUT` 等，CLI flag > 环境变量 > context
- 危险操作在非 TTY 下要求 `--yes`
- **它主动报告能力边界而不是假装支持**：网站日志 API 是分页 JSON，不支持 `--follow`/`--since`，CLI 会直接说明这个限制，而不是模拟一个不可靠的流
- 兼容性对 1Panel `dev-v2` commit `97d383ed122c`（2026-07-28）实测验证过

**限制**：`website` 子命令只有 `list/get/start/stop/restart/logs`，**没有 create**，所以建网站/反代不直接支持。但有通用逃生口：

```bash
1p api POST /api/v2/websites --data '{"domains":[...],"type":"proxy","proxy":"http://127.0.0.1:3000"}'
```

`1p api <METHOD> <PATH> --data` 支持任意方法与 body，且**锁死了 `1Panel-Token`/`1Panel-Timestamp` 不允许覆盖**（防止误传错鉴权头，这点考虑得对）。

---

### 3. `ffdkj/1panel-mcp-v1` —— 专供 1Panel v1

如果你的面板还停在 v1，前面几个都用不了，这个才是答案。

- 仓库：https://github.com/ffdkj/1panel-mcp-v1
- 基于 `v1.10.34-lts` 构建与实测，只调 `/api/v1/`
- Node/TypeScript，stdio + Streamable HTTP（含旧版 SSE）+ 令牌鉴权
- 附 systemd 单元模板和 `docs/v1-api-notes.md`（记录 swagger 注解滞后、路由存在性探测、v2/v1 字段差异）
- 移植自 EaveLuo 早期的 v1 代码（MIT）

覆盖：容器与镜像、应用与运行时、文件/备份/快照、系统/主机/监控、防火墙/Fail2ban/FTP/ClamAV、网站与证书、数据库、定时任务、Ollama、OpenResty。

**已知限制**（这些是 v1 本身没有的能力，它会返回明确中文错误而非静默失败）：`delete_firewall_rule`、`operate_fail2ban_ssh`、`get_clam_records`、`clean_clam_records`、`update_clam_status`、`postgresql_change_privileges`。AI Agent、MCP Server、GPU 监控也是 v1 无接口（属 v2/XPack 专有）。

---

### 4. 其他

| 项目 | 形态 | 说明 |
|---|---|---|
| `1panel-rocket-cli` | npm CLI | 只做静态网站部署，配合 GitHub Actions 用；场景很窄 |
| `dsh-1panel-ops` | DSH 插件 | `github.com/lussey820/dsh-1panel-ops`，挂载服务器环境 + 驱动 1Panel；2026-08-19 首发，仅 0.1.0，太新 |
| `1panel-skill` | Skill | EaveLuo 同作者，宣称 580+ endpoints，裸 API 暴露 |

---

## 四、反向代理专题

这是最常被搞混的一点：**到底哪个能建反代？**

| 项目 | 建反代 | 依据 |
|---|---|---|
| **官方 `mcp-1panel`** | ✅ **原生支持，schema 完整** | 工具描述原文即 `"Create a static or reverse-proxy website managed by 1Panel."`；源码 `operations/website/create.go` 强制 `website_type` ∈ {static, proxy}，选 proxy 时 `proxy_address` 必填并过 `ValidateProxyAddress`，最终 `POST /websites` 带 `type:"proxy"` |
| `EaveLuo/1panel-mcp` | ⚠️ 理论能，实际难用 | 全包 grep `proxy` = 0 次，无专门工具；`create_website` 裸透传无 schema 提示。兜底只有 `update_nginx_conf` 手写 nginx |
| 官方 `1Panel-skills` | ❌ | 定位只读，写操作全是预留未实现 |
| `liyown/1panel-cli` | ⚠️ 绕道能 | 无 `website create`，但 `1p api POST ...` 可自己构 body |
| `1pctl` | ❌ | 只管面板进程 |

**官方 MCP 建反代的正确姿势：**

```json
{
  "domain": "app.example.com",
  "website_type": "proxy",
  "proxy_address": "http://127.0.0.1:3000"
}
```

两个必踩的坑：

1. **`access-level` 默认 `readonly`**，此时 `create_website` 根本不出现在 `tools/list` 里，智能体会回答"我没有这个能力"。**必须显式设 `readwrite`**。
2. **参数校验比 API 本身还严**：
   - `domain` 必须是**不带 scheme/端口/路径的纯 FQDN**，且至少两段标签——写 `app.example.com:8080` 或 `http://...` 直接报错
   - `proxy_address` 必须以 `http://` 或 `https://` 开头且含 host

---

## 五、鉴权：所有方案共用的底层

不管用哪个上层工具，底下都是同一套 1Panel API。

**开启 API**：登录面板 → 左下角用户菜单 →「API 接口」区域启用 → 维护 API Key / IP 白名单 / 有效期。（v2.2.1 之前入口在「面板设置」里。）

**请求头**：

| Header | 值 |
|---|---|
| `1Panel-Token` | 签名 |
| `1Panel-Timestamp` | 当前 Unix 时间戳（秒） |

**签名两种方式**（服务端都兼容，新接入推荐后者）：

```
方式一（旧，兼容）：Token = md5('1panel' + API_KEY + UnixTimestamp)
方式二（推荐）：    Token = hmac_sha256(API_KEY, '1panel:' + UnixTimestamp)
```

**Swagger**：`{host}:{port}/1panel/swagger/index.html` 可查全部接口。

**兜底思路**：官方 MCP 只有 11 个工具、官方 skill 只读、第三方要么零 star 要么裸透传——如果都不够用，直接照 Swagger 自己写一层是最彻底的。`1Panel-skills` 的 `scripts/client.ts` 和 `liyown/1panel-cli` 的 `internal/api/client.go` 都可以直接当签名参考实现。

---

## 六、踩坑清单

1. **IP 白名单**——最常见的报错来源。报 `调用 API 接口 IP 不在白名单` 时，把调用方出口 IP 加进去；测试可临时 `0.0.0.0/0` / `::/0`。
2. **两类密钥别搞混**——面板 API Key（连 1Panel）和 MCP 客户端连接用的访问令牌（如 `MCP_AUTH_TOKEN`）是两回事。客户端设备只需要后者。
3. **`sse` 别配**——官方 MCP `dev-v2` 已移除，只支持 stdio / streamable-http。
4. **认准 `dev-v2` 分支**——官方 MCP 的 `main` 是过时文档。
5. **`readonly` 是默认值**——想写就得显式提权，否则工具不出现，容易误判成"不支持"。
6. **`domain` 校验严格**——纯 FQDN，不带协议/端口/路径。
7. **时钟要同步**——签名含时间戳，建议 NTP，否则鉴权随机失败。
8. **第三方风险**——零 star / 单版本 / 无仓库字段 / 工具全开放的方案，先上测试面板。
9. **API Key 安全**——别提交进版本库；`liyown/1panel-cli` 用 Keychain 存是正确做法。

---

## 七、推荐组合

**求稳（生产环境）：**

```
官方 mcp-1panel (MCP_ACCESS_LEVEL=readonly)  ← 先只读挂上验证连通
  + 官方 1Panel-skills                        ← 补容器/日志/计划任务/节点视野
```

跑通确认无误后，再按需把 MCP 提到 `readwrite` 只为了建网站/证书/数据库。

**要批量脚本化**：加 `liyown/1panel-cli`，多 context 管多台机器，Keychain 存 key，stdout 纯结果适合管道。

**确实需要深度操作**：再评估 `EaveLuo/1panel-mcp`，测试面板先行。

**面板还是 v1**：直接用 `ffdkj/1panel-mcp-v1`。

---

## 附：资源汇总

| 项目 | 地址 |
|---|---|
| 官方 MCP Server | https://github.com/1Panel-dev/mcp-1panel |
| 官方 Skills + CLI | https://github.com/1Panel-dev/1Panel-skills |
| 第三方全功能 MCP | https://github.com/EaveLuo/1panel-mcp |
| 第三方 Go CLI | https://github.com/liyown/1panel-cli |
| v1 专用 MCP | https://github.com/ffdkj/1panel-mcp-v1 |
| DSH 插件 | https://github.com/lussey820/dsh-1panel-ops |
| 官方文档（MCP） | https://1panel.pro/docs/v2/user_manual/mcp/mcp_server |
| 官方 API 文档 | https://docs.fit2cloud.com/1panel/dev-manual/api-manual |
| 1Panel 主仓库 | https://github.com/1Panel-dev/1Panel |

---

**核对说明**：文中工具数量、API 版本、反向代理支持、传输方式等结论，均通过下载源码 / npm 包实际检索得出，非转述 README。star 数与发布时间来自第三方快照，可能滞后。

---

**分类**：教程
**标签**：官方 · 1panel · 1Panel
**作者**：子龙
**链接**：https://octohz.com/p/2181