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，命令行优先。

配置

{
  "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 传输（远程场景）：

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 用法

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 就自带，只管面板自身，不碰业务资源：

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

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

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

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，所以建网站/反代不直接支持。但有通用逃生口：

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 建反代的正确姿势：

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

两个必踩的坑：

access-level 默认 readonly，此时 create_website 根本不出现在 tools/list 里，智能体会回答"我没有这个能力"。必须显式设 readwrite。
参数校验比 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 都可以直接当签名参考实现。

六、踩坑清单

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

26400举报0

子龙•1个月前

点击获取 ^_^

被收录：

官方 1panel 1Panel

暂无评论