oneclickvirt

GitHub

管理OneClickVirt容器和虚拟机实例、提供商节点及系统健康检查的AI辅助技能,支持通过MCP进行日常运维与故障排查。

触发场景

需要创建、启动或停止虚拟机/容器实例 执行平台健康检查或监控资源状态 查询提供商节点信息或进行故障排查

安装

npx skills add oneclickvirt/oneclickvirt --skill oneclickvirt -g -y
更多选项

非标准路径

npx skills add https://github.com/oneclickvirt/oneclickvirt/tree/main/skills -g -y

不安装直接使用

npx skills use oneclickvirt/oneclickvirt@oneclickvirt

指定 Agent (Claude Code)

npx skills add oneclickvirt/oneclickvirt --skill oneclickvirt -a claude-code -g -y

安装 repo 全部 skill

npx skills add oneclickvirt/oneclickvirt --all -g -y

预览 repo 内 skill

npx skills add oneclickvirt/oneclickvirt --list

SKILL.md

Frontmatter
{
    "name": "oneclickvirt",
    "metadata": {
        "author": "oneclickvirt",
        "version": "0.3.0",
        "homepage": "https:\/\/github.com\/oneclickvirt\/oneclickvirt"
    },
    "description": "OneClickVirt operations skill for managing containers, virtual machines, provider nodes, health checks, and metrics through MCP."
}

OneClickVirt Skill

Overview

This skill helps an AI assistant operate a OneClickVirt deployment through the built-in MCP server. It is useful for routine instance management, provider inspection, platform health checks, and guided troubleshooting.

What this skill can do:

  • List, create, start, stop, restart, inspect, and delete instances.
  • List providers and run provider health checks.
  • Read system status, health, configuration, and monitoring resources.
  • Use prompt templates for common container, VM, status, and troubleshooting workflows.

Prerequisites

  • Python 3.9+ for the installer. Prebuilt MCP binaries support Linux/Windows amd64 and ARM64; other platforms can use an existing binary or SSH transport.
  • A running OneClickVirt API endpoint.
  • An administrator API token from the Web UI under Profile -> API Tokens.
  • HTTPS for remote OneClickVirt deployments.

Installation

Install or update the latest stable release from GitHub:

curl -fL --retry 3 https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/main/scripts/install_skill.py -o install_skill.py
python3 install_skill.py --client claude

The same installer is available from the CNB public source mirror:

curl -fL --retry 3 https://cnb.cool/oneclickvirt/oneclickvirt/-/git/raw/main/scripts/install_skill.py -o install_skill.py
python3 install_skill.py --client claude

Choose --client codex or --client openclaw for those clients. The default directories are ~/.claude/skills/oneclickvirt, ~/.agents/skills/oneclickvirt, and ~/.openclaw/skills/oneclickvirt; --skill-dir overrides the destination. On Windows, download the same script and run it with Python 3.9+ (py -3 install_skill.py --client claude).

Both entry points resolve one published GitHub Release, verify its Skill and binary checksums, and install them together. CNB mirrors source; these release archives are downloaded from GitHub. The installer creates SKILL.md directly in the Skill directory and a separate oneclickvirt-mcp binary in ~/.local/bin. It does not start the controller or alter services, databases, client settings, or existing API tokens.

Repeat the download and installation commands to update. Pass --version with an exact published tag to pin a release or return to it; the Skill and binary use that same tag. install.json records the installed version. Reuse an existing controller binary with --mcp-command /opt/oneclickvirt/server/oneclickvirt-server, or use --skip-binary to install only the Skill files. A Skill alone does not configure or start MCP.

The installer generates mcp.codex.toml for ~/.codex/config.toml, mcp.claude.json for the project .mcp.json, and mcp.openclaw.json for ~/.openclaw/openclaw.json. Merge the matching file while keeping existing entries, retain the absolute binary path, and set your API URL/token. mcp.example.json remains a Claude-format compatibility example. The Claude Code structure is:

{
  "mcpServers": {
    "oneclickvirt": {
      "command": "oneclickvirt-mcp",
      "args": ["mcp"],
      "env": {
        "ONE_CLICK_VIRT_API_URL": "https://your-domain.com",
        "ONE_CLICK_VIRT_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

The command must be visible to the MCP client; GUI clients may not inherit your shell's PATH. A controller installed by the project uses /opt/oneclickvirt/server/oneclickvirt-server, not /opt/oneclickvirt/server/oneclickvirt. macOS has no prebuilt controller asset: use --skip-binary and configure an existing native build or an SSH MCP transport to Linux. Restart the MCP client after configuration. See the installation guide for release archives and SSH examples.

Usage

Available MCP tools:

  • list_instances — List all virtual machine and container instances in OneClickVirt
  • create_instance — Create a new virtual machine or container instance
  • start_instance — Start a stopped instance
  • stop_instance — Stop a running instance
  • restart_instance — Restart an instance
  • delete_instance — Delete an instance (DANGER: irreversible)
  • get_instance_detail — Get detailed information about a specific instance
  • list_providers — List all virtualization provider nodes
  • health_check — Run a health check on a provider node
  • get_instance_logs — Get recent logs from an instance
  • get_system_status — Get overall system status including instance counts and resource usage
  • get_metrics — Get monitoring metrics for the system, a provider, or an instance

Available resources:

  • oneclickvirt://instances/list — Current list of all instances
  • oneclickvirt://providers/list — Current list of all provider nodes
  • oneclickvirt://system/status — Overall system health and metrics
  • oneclickvirt://health/status — Public OneClickVirt API health status
  • oneclickvirt://config/system — Administrator-visible system configuration

Available prompt templates:

  • create_debian_container — Template for creating a Debian Linux container
  • create_ubuntu_vm — Template for creating an Ubuntu virtual machine
  • troubleshoot_instance — Template for troubleshooting an instance that won't start
  • quick_status_check — Template for checking instance, provider, and platform health

Examples

  • "List running instances and summarize anything frozen or stopped."
  • "Create a Debian 12 container on provider 1 with 2 CPU, 1 GB memory, and 20 GB disk."
  • "Run a quick status check for the platform."
  • "Check provider 3 health and summarize capacity concerns."
  • "Troubleshoot instance 42 and suggest the safest next action."

Troubleshooting

  • command not found: oneclickvirt-mcp: use the absolute command path from the installed mcp.example.json in the client config.
  • 401 Unauthorized: verify ONE_CLICK_VIRT_API_TOKEN is an active administrator token.
  • Connection refused: verify ONE_CLICK_VIRT_API_URL and that /api/v1/health is reachable.
  • Tools do not appear: restart the MCP client and inspect its MCP server logs.

Security

  • Prefer environment variables over command-line token arguments.
  • Use a dedicated token with the minimum required permissions.
  • Review destructive requests such as delete_instance before confirming.
  • Use HTTPS for remote API endpoints.

版本历史

  • 6935665 当前 2026-11-02 16:58

    新增自动化安装脚本以支持多客户端配置生成;增加Windows原生MCP安装测试;修复发布版本技能包验证问题。

  • 44ad6a5 2026-07-05 20:22

元信息

文件数
0
版本
1a2fcd2
Hash
9c230579
收录时间
2026-07-05 20:22

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-18 06:25
浙ICP备14020137号-1