1panel-api

1Panel API スキル

🎯 Agent にその場で curl を組み立てさせるのではなく、ツールを使って 1Panel を操作します。

このリポジトリには、1Panel API ドキュメントと依存関係のない Node.js ツール層が含まれています。

• tools/1panel-tool.js：コマンドライン／JSON tool-call 実行ツール
• tools/1panel-mcp.js：MCP stdio サーバー。MCP 対応の Agent にツールを公開します
• tools/1panel-lib.js：トークン計算、API リクエスト、エンドポイントインデックスの解析
• docs/SKILL-*.md：モジュールごとに整理した 1Panel API エンドポイントドキュメント

クイックスタート

1. Node.js を準備する

組み込みの fetch を使用するため、Node.js 18 以降が必要です。npm 依存関係のインストールは不要です。

node --version

2. 1Panel の接続情報を設定する

初回使用時に、以下の情報を指定または設定してください。

情報	環境変数	説明	例
1Panel アドレス	ONEPANEL_BASE_URL	サーバーの IP／ドメイン名 + パネルのポート	http://192.168.1.100:8888
API Key	ONEPANEL_API_KEY	パネルの「設定」→「API キー」で生成	xxxxxxxx
自己署名 HTTPS を許可	ONEPANEL_INSECURE	自己署名証明書を使用する場合は true に設定できます	true

export ONEPANEL_BASE_URL='http://你的地址:8888'
export ONEPANEL_API_KEY='你的 API Key'

3. API Key を取得する

1. 1Panel パネルにログインします
2. 「設定」→「API キー」に移動します
3. 「作成」をクリックして新しいキーを生成します
4. 生成したキーを ONEPANEL_API_KEY にコピーします

Agent の使用ルール

Agent がこのスキルを使用して 1Panel を管理する場合：

1. Node ツール／MCP ツールを優先して使用し、curl を手書きしないでください。
2. インターフェースのパスが不明な場合は、まず onepanel_endpoint_search を呼び出してエンドポイントを検索します。
3. インターフェースを確認したら、onepanel_get、onepanel_post、または onepanel_request を呼び出します。
4. 削除、サービスの停止・再起動、設定の上書き、ファイルのクリーンアップなどの危険な操作を行う前に、影響範囲をユーザーに確認します。
5. ユーザーに結果を返す際は、呼び出したツール、エンドポイント、ステータスコード、主な結果を説明します。

MCP ツール

tools/1panel-mcp.js は以下のツールを公開します。

ツール	用途
onepanel_endpoint_search	このリポジトリに組み込まれた 1Panel API エンドポイントインデックスを検索します
onepanel_modules	組み込み API モジュールを一覧表示します
onepanel_get	1Panel API エンドポイントに GET リクエストを送信します
onepanel_post	1Panel API エンドポイントに POST リクエストを送信します
onepanel_request	任意のメソッドで 1Panel API エンドポイントを呼び出します

MCP の設定例

以下の設定を MCP 対応 Agent の設定に追加します。

{
  "mcpServers": {
    "1panel": {
      "command": "node",
      "args": ["/absolute/path/to/1Panel-Skills/tools/1panel-mcp.js"],
      "env": {
        "ONEPANEL_BASE_URL": "http://你的地址:8888",
        "ONEPANEL_API_KEY": "你的 API Key"
      }
    }
  }
}

Hermes Agent を使用する場合は、以下を使用できます。

hermes mcp add 1panel --command "node /absolute/path/to/1Panel-Skills/tools/1panel-mcp.js"

次に、Hermes の環境変数で ONEPANEL_BASE_URL と ONEPANEL_API_KEY を設定します。セッションを再起動すると、MCP ツールを使用できるようになります。

CLI／JSON tool-call の使用方法

エンドポイントを検索する

node tools/1panel-tool.js endpoints --keyword container --limit 5

モジュールを照会する

node tools/1panel-tool.js modules

GET リクエスト

node tools/1panel-tool.js get /containers/status

POST リクエスト

node tools/1panel-tool.js post /containers/search \
  --body '{"page":1,"pageSize":20}'

汎用リクエスト

node tools/1panel-tool.js request \
  --method GET \
  --path /containers/status

JSON tool-call モード

node tools/1panel-tool.js tool-call '{
  "tool": "onepanel_request",
  "args": {
    "method": "GET",
    "path": "/containers/status"
  }
}'

戻り値はすべて JSON 形式で、以下を含みます。

{
  "ok": true,
  "status": 200,
  "statusText": "OK",
  "url": "http://example:8888/api/v2/containers/status",
  "data": {}
}

認証の実装

Node ツールは内部で 1Panel API 認証を自動的に行うため、Agent が手動でトークンを計算する必要はありません。

認証ロジック：

timestamp = 当前 Unix 秒级时间戳
token = md5("1panel" + apiKey + timestamp)
headers:
  1Panel-Token: token
  1Panel-Timestamp: timestamp
  Content-Type: application/json

機能モジュール

モジュール	説明
アプリ	アプリストア、インストール済みアプリの管理
Web サイト	Web サイトの作成、設定、リバースプロキシ、SSL
コンテナ	Docker コンテナの管理
データベース	MySQL、PostgreSQL、Redis、MongoDB
ファイル	ファイルのアップロード、ダウンロード、圧縮、展開
バックアップ	バックアップと復元
Cron ジョブ	定期タスク
ランタイム	PHP、Node、Python、Go、Java の実行環境
ホスト	ホストの監視、ファイアウォール、SSH、ディスク管理
設定	システム設定、ユーザー管理

エンドポイントインデックス全体については INDEX.md を、詳細な API ドキュメントについては docs ディレクトリを参照してください。

よくあるワークフロー

Docker／コンテナの状態を確認する

1. エンドポイントを検索します：onepanel_endpoint_search({"keyword":"containers status"})
2. 呼び出します：onepanel_get({"path":"/containers/status"})
3. 返されたコンテナ数、イメージ数、ネットワーク数に基づいて結果を報告します。

コンテナをページネーションで照会する

呼び出します：

{
  "tool": "onepanel_post",
  "args": {
    "path": "/containers/search",
    "body": {"page": 1, "pageSize": 20}
  }
}

未知のインターフェースを呼び出す

1. onepanel_endpoint_search を使い、キーワードまたはモジュールでパスを検索します。
2. 対応する docs/SKILL-*.md のパラメーター表を確認します。
3. onepanel_request に method、path、query、body を渡します。

検証

npm test

このコマンドは Node ファイルの構文をチェックし、エンドポイントインデックスを docs/ から正常に解析できることを確認します。