技能库 / 效率工具 / Ansible 自动化

全部分类开发编程创意写作商业办公教育学习效率工具数据分析技术集成通用语言翻译文档生成

Ansible 自动化

使用 Ansible 编写 playbook、角色与 inventory，完成批量配置与应用发布；变量与幂等细节见包内文档。

v1.0.0 botond-rackhost

作者 / 来源

skillhub

在来源站打开

登录后收藏登录后加入合集

安装方式

CLI 安装（推荐）

claw install shub-ansible-skill

需要安装 CLAW CLI

手动下载安装

下载 ZIP 后解压到技能目录即可安装。若在桌面客户端 WebView中直接下载出现异常，本站会改为提示页 + 原始链接，请按页内说明操作。

下载 ZIP (shub-ansible-skill-v1.0.0.zip)

触发指令

/ansible

跨平台安装指引

该技能声明兼容以下 1 个平台，将 ZIP 解压到对应目录即可被识别。

支持矩阵

Claude Code Coding Agent

macOS / Linux：~/.claude/skills/

Windows：%USERPROFILE%\.claude\skills\

unzip shub-ansible-skill-v1.0.0.zip -d ~/.claude/skills/

目录不存在时请先 mkdir -p 创建；启用 Skill 后请重启对应 Agent 让配置生效。

使用指南

Ansible 自动化

围绕 Ansible 自动化：使用 Ansible 编写 playbook、角色与 inventory，完成批量配置与应用发布；变量与幂等细节见包内文档。无需在每次任务前把零散英文说明手工拼进上下文，也减少与客户端默认行为脱节的试错；具体命令、钩子与 JSON 参数仍以 ZIP 包内 SKILL.md 为权威。下文结构与站内 MCP CLI 类专题稿相同：何时用、前置、流程、速查与故障。

何时使用

使用 Ansible 编写 playbook、角色与 inventory，完成批量配置与应用发布
变量与幂等细节见包内文档
已获取本技能 ZIP，并准备在 Claude Code / OpenClaw 中按 SKILL.md 挂载。
希望用中文专题稿快速判断「该不该启用」，再深入英文 SKILL 查参数与边界。
需要与团队对齐同一套触发方式、目录约定或回调格式时。

前置条件

通用：可运行 Claude Code 或文档要求的客户端；有可读写的项目工作区（或 SKILL.md 指定的沙箱目录）。
权威细节：API Key / OAuth、钩子路径、环境变量以 ZIP 内 SKILL.md 为准。

典型流程

从 ClawHub / 站内分发获取技能 ZIP，校验版本与校验和（若提供）。
阅读 SKILL.md 的安装段落：目录落点、客户端类型（Claude Code / OpenClaw / 脚本）。
用文档中的最小示例完成第一次调用（单文件修改、单次查询或单次委派）。
确认工作目录、权限边界与输出路径后，再处理多文件或长耗时任务。
需要回调 / Webhook / 通知时，按 SKILL.md 配置端点并在测试环境先验通。

与 ZIP / SKILL.md 的关系

站内专题稿与 MCP CLI 类 oss 稿同样：概括何时用、怎么接、怎么排错；命令模板、钩子名、JSON 字段、版本矩阵一律以 ZIP 内 SKILL.md 与 ClawHub 上游为准。

命令示例（摘自包内 SKILL.md）

以下为从上游 SKILL.md（或入库正文）自动抽取的终端/脚本片段；路径、环境变量与参数以当前 ZIP 与官方说明为准。

ClawHub slug：ansible-skill（安装命令以 SKILL.md / claw CLI 为准）。

# Install Ansible
pip install ansible

# Or on macOS
brew install ansible

# Verify
ansible --version

# Test connection
ansible all -i inventory/hosts.yml -m ping

# Run playbook
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

# Dry run (check mode)
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --check

# With specific tags
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --tags "security,nodejs"

# 1. Add host to inventory
cat >> inventory/hosts.yml << 'EOF'
        newserver:
          ansible_host: 1.2.3.4
          ansible_user: root
          ansible_ssh_pass: "initial_password"
          deploy_user: asdbot
          deploy_ssh_pubkey: "ssh-ed25519 AAAA... asdbot"
EOF

# 2. Run OpenClaw playbook
ansible-playbook -i inventory/hosts.yml playbooks/openclaw-vps.yml \
  --limit newserver \
  --ask-vault-pass

# 3. After initial setup, update inventory to use key auth
# ansible_user: asdbot
# ansible_ssh_private_key_file: ~/.ssh/id_ed25519

ansible-playbook -i inventory/hosts.yml playbooks/security.yml \
  --limit production \
  --tags "ssh,firewall"

# Update one server at a time
ansible-playbook -i inventory/hosts.yml playbooks/update.yml \
  --serial 1

# Check disk space on all servers
ansible all -i inventory/hosts.yml -m shell -a "df -h"

# Restart service
ansible openclaw -i inventory/hosts.yml -m systemd -a "name=openclaw state=restarted"

# Copy file
ansible all -i inventory/hosts.yml -m copy -a "src=./file.txt dest=/tmp/"

# Create encrypted vars file
ansible-vault create inventory/group_vars/all/vault.yml

# Edit encrypted file
ansible-vault edit inventory/group_vars/all/vault.yml

# Run with vault
ansible-playbook site.yml --ask-vault-pass

# Or use vault password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass

# Test SSH connection manually
ssh -v user@host

# Debug Ansible connection
ansible host -i inventory -m ping -vvv

# Check inventory parsing
ansible-inventory -i inventory --list

# Verbose output
ansible-playbook site.yml -v    # Basic
ansible-playbook site.yml -vv   # More
ansible-playbook site.yml -vvv  # Maximum

# Step through tasks
ansible-playbook site.yml --step

# Start at specific task
ansible-playbook site.yml --start-at-task="Install nginx"

# Check mode (dry run)
ansible-playbook site.yml --check --diff

# Run playbook via exec tool
exec command="ansible-playbook -i skills/ansible/inventory/hosts.yml skills/ansible/playbooks/openclaw-vps.yml --limit eva"

# Ad-hoc command
exec command="ansible eva -i skills/ansible/inventory/hosts.yml -m shell -a 'systemctl status openclaw'"

站内入库时的触发命令（完整语义见 ZIP）：

# 使用本技能时可在对话中引用或执行上述指令；完整参数与示例见下载包内 SKILL.md。
/ansible

最佳实践

先 SKILL.md 再猜参数；站内专题稿不替代 schema 与必填字段说明。
委派任务时写清验收标准（命令、文件路径、测试命令），减少来回追问。
长任务用文档推荐的回调 / 日志落盘代替高频轮询，省 Token 也省机器负载。
多技能同时启用时，注意钩子加载顺序与重复工具调用（以 SKILL.md 冲突说明为准）。

调试与排错

打开 stderr 与客户端日志；PTY/tmux 场景同时看面板最后几十行输出。
参数错误时对照 SKILL.md 中的 JSON/CLI 示例（引号、转义、工作目录）。
网络类失败：查代理、防火墙、MCP 传输方式（stdio / HTTP / SSE）。

速查

| 动作 | 说明 | |------|------| | 获取技能包 | ClawHub / 站内 ZIP，核对版本 | | 权威步骤 | 优先阅读 ZIP 内 SKILL.md | | 首次试跑 | 使用 SKILL.md 最小示例 | | 验收 | 对照路径、测试命令或回调负载 |

常见故障

无输出或立即退出 → 工作目录错误、依赖未装、或 Claude Code 未登录；按 SKILL.md 自检清单执行。
权限被拒绝 → 检查沙箱路径、--permission-mode 与工具白名单。
与简介不符 → 以英文 SKILL 与上游仓库为准，站内稿仅作结构化导读。

# Ansible Skill

Infrastructure as Code automation for server provisioning, configuration management, and orchestration.

## Quick Start

### Prerequisites

```bash
# Install Ansible
pip install ansible

# Or on macOS
brew install ansible

# Verify
ansible --version
```

### Run Your First Playbook

```bash
# Test connection
ansible all -i inventory/hosts.yml -m ping

# Run playbook
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

# Dry run (check mode)
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --check

# With specific tags
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --tags "security,nodejs"
```

## Directory Structure

```
skills/ansible/
├── SKILL.md              # This file
├── inventory/            # Host inventories
│   ├── hosts.yml         # Main inventory
│   └── group_vars/       # Group variables
├── playbooks/            # Runnable playbooks
│   ├── site.yml          # Master playbook
│   ├── openclaw-vps.yml  # OpenClaw VPS setup
│   └── security.yml      # Security hardening
├── roles/                # Reusable roles
│   ├── common/           # Base system setup
│   ├── security/         # Hardening (SSH, fail2ban, UFW)
│   ├── nodejs/           # Node.js installation
│   └── openclaw/         # OpenClaw installation
└── references/           # Documentation
    ├── best-practices.md
    ├── modules-cheatsheet.md
    └── troubleshooting.md
```

## Core Concepts

### Inventory

Define your hosts in `inventory/hosts.yml`:

```yaml
all:
  children:
    vps:
      hosts:
        eva:
          ansible_host: 217.13.104.208
          ansible_user: root
          ansible_ssh_pass: "{{ vault_eva_password }}"
        plane:
          ansible_host: 217.13.104.99
          ansible_user: asdbot
          ansible_ssh_private_key_file: ~/.ssh/id_ed25519_plane
    
    openclaw:
      hosts:
        eva:
```

### Playbooks

Entry points for automation:

```yaml
# playbooks/site.yml - Master playbook
---
- name: Configure all servers
  hosts: all
  become: yes
  roles:
    - common
    - security

- name: Setup OpenClaw servers
  hosts: openclaw
  become: yes
  roles:
    - nodejs
    - openclaw
```

### Roles

Reusable, modular configurations:

```yaml
# roles/common/tasks/main.yml
---
- name: Update apt cache
  ansible.builtin.apt:
    update_cache: yes
    cache_valid_time: 3600
  when: ansible_os_family == "Debian"

- name: Install essential packages
  ansible.builtin.apt:
    name:
      - curl
      - wget
      - git
      - htop
      - vim
      - unzip
    state: present
```

## Included Roles

### 1. common
Base system configuration:
- System updates
- Essential packages
- Timezone configuration
- User creation with SSH keys

### 2. security
Hardening following CIS benchmarks:
- SSH hardening (key-only, no root)
- fail2ban for brute-force protection
- UFW firewall configuration
- Automatic security updates

### 3. nodejs
Node.js installation via NodeSource:
- Configurable version (default: 22.x LTS)
- npm global packages
- pm2 process manager (optional)

### 4. openclaw
Complete OpenClaw setup:
- Node.js (via nodejs role)
- OpenClaw npm installation
- Systemd service
- Configuration file setup

## Usage Patterns

### Pattern 1: New VPS Setup (OpenClaw)

```bash
# 1. Add host to inventory
cat >> inventory/hosts.yml << 'EOF'
        newserver:
          ansible_host: 1.2.3.4
          ansible_user: root
          ansible_ssh_pass: "initial_password"
          deploy_user: asdbot
          deploy_ssh_pubkey: "ssh-ed25519 AAAA... asdbot"
EOF

# 2. Run OpenClaw playbook
ansible-playbook -i inventory/hosts.yml playbooks/openclaw-vps.yml \
  --limit newserver \
  --ask-vault-pass

# 3. After initial setup, update inventory to use key auth
# ansible_user: asdbot
# ansible_ssh_private_key_file: ~/.ssh/id_ed25519
```

### Pattern 2: Security Hardening Only

```bash
ansible-playbook -i inventory/hosts.yml playbooks/security.yml \
  --limit production \
  --tags "ssh,firewall"
```

### Pattern 3: Rolling Updates

```bash
# Update one server at a time
ansible-playbook -i inventory/hosts.yml playbooks/update.yml \
  --serial 1
```

### Pattern 4: Ad-hoc Commands

```bash
# Check disk space on all servers
ansible all -i inventory/hosts.yml -m shell -a "df -h"

# Restart service
ansible openclaw -i inventory/hosts.yml -m systemd -a "name=openclaw state=restarted"

# Copy file
ansible all -i inventory/hosts.yml -m copy -a "src=./file.txt dest=/tmp/"
```

## Variables & Secrets

### Group Variables

```yaml
# inventory/group_vars/all.yml
---
timezone: Europe/Budapest
deploy_user: asdbot
ssh_port: 22

# Security
security_ssh_password_auth: false
security_ssh_permit_root: false
security_fail2ban_enabled: true
security_ufw_enabled: true
security_ufw_allowed_ports:
  - 22
  - 80
  - 443

# Node.js
nodejs_version: "22.x"
```

### Vault for Secrets

```bash
# Create encrypted vars file
ansible-vault create inventory/group_vars/all/vault.yml

# Edit encrypted file
ansible-vault edit inventory/group_vars/all/vault.yml

# Run with vault
ansible-playbook site.yml --ask-vault-pass

# Or use vault password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass
```

Vault file structure:
```yaml
# inventory/group_vars/all/vault.yml
---
vault_eva_password: "y8UGHR1qH"
vault_deploy_ssh_key: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----
```

## Common Modules

| Module | Purpose | Example |
|--------|---------|---------|
| `apt` | Package management (Debian) | `apt: name=nginx state=present` |
| `yum` | Package management (RHEL) | `yum: name=nginx state=present` |
| `copy` | Copy files | `copy: src=file dest=/path/` |
| `template` | Template files (Jinja2) | `template: src=nginx.conf.j2 dest=/etc/nginx/nginx.conf` |
| `file` | File/directory management | `file: path=/dir state=directory mode=0755` |
| `user` | User management | `user: name=asdbot groups=sudo shell=/bin/bash` |
| `authorized_key` | SSH keys | `authorized_key: user=asdbot key="{{ ssh_key }}"` |
| `systemd` | Service management | `systemd: name=nginx state=started enabled=yes` |
| `ufw` | Firewall (Ubuntu) | `ufw: rule=allow port=22 proto=tcp` |
| `lineinfile` | Edit single line | `lineinfile: path=/etc/ssh/sshd_config regexp='^PermitRootLogin' line='PermitRootLogin no'` |
| `git` | Clone repos | `git: repo=https://github.com/x/y.git dest=/opt/y` |
| `npm` | npm packages | `npm: name=openclaw global=yes` |
| `command` | Run command | `command: /opt/script.sh` |
| `shell` | Run shell command | `shell: cat /etc/passwd \| grep root` |

## Best Practices

### 1. Always Name Tasks
```yaml
# Good
- name: Install nginx web server
  apt:
    name: nginx
    state: present

# Bad
- apt: name=nginx
```

### 2. Use FQCN (Fully Qualified Collection Names)
```yaml
# Good
- ansible.builtin.apt:
    name: nginx

# Acceptable but less clear
- apt:
    name: nginx
```

### 3. Explicit State
```yaml
# Good - explicit state
- ansible.builtin.apt:
    name: nginx
    state: present

# Bad - implicit state
- ansible.builtin.apt:
    name: nginx
```

### 4. Idempotency
Write tasks that can run multiple times safely:
```yaml
# Good - idempotent
- name: Ensure config line exists
  ansible.builtin.lineinfile:
    path: /etc/ssh/sshd_config
    regexp: '^PasswordAuthentication'
    line: 'PasswordAuthentication no'

# Bad - not idempotent
- name: Add config line
  ansible.builtin.shell: echo "PasswordAuthentication no" >> /etc/ssh/sshd_config
```

### 5. Use Handlers for Restarts
```yaml
# tasks/main.yml
- name: Update SSH config
  ansible.builtin.template:
    src: sshd_config.j2
    dest: /etc/ssh/sshd_config
  notify: Restart SSH

# handlers/main.yml
- name: Restart SSH
  ansible.builtin.systemd:
    name: sshd
    state: restarted
```

### 6. Tags for Selective Runs
```yaml
- name: Security tasks
  ansible.builtin.include_tasks: security.yml
  tags: [security, hardening]

- name: App deployment
  ansible.builtin.include_tasks: deploy.yml
  tags: [deploy, app]
```

## Troubleshooting

### Connection Issues

```bash
# Test SSH connection manually
ssh -v user@host

# Debug Ansible connection
ansible host -i inventory -m ping -vvv

# Check inventory parsing
ansible-inventory -i inventory --list
```

### Common Errors

**"Permission denied"**
- Check SSH key permissions: `chmod 600 ~/.ssh/id_*`
- Verify user has sudo access
- Add `become: yes` to playbook

**"Host key verification failed"**
- Add to ansible.cfg: `host_key_checking = False`
- Or add host key: `ssh-keyscan -H host >> ~/.ssh/known_hosts`

**"Module not found"**
- Use FQCN: `ansible.builtin.apt` instead of `apt`
- Install collection: `ansible-galaxy collection install community.general`

### Debugging Playbooks

```bash
# Verbose output
ansible-playbook site.yml -v    # Basic
ansible-playbook site.yml -vv   # More
ansible-playbook site.yml -vvv  # Maximum

# Step through tasks
ansible-playbook site.yml --step

# Start at specific task
ansible-playbook site.yml --start-at-task="Install nginx"

# Check mode (dry run)
ansible-playbook site.yml --check --diff
```

## Integration with OpenClaw

### From OpenClaw Agent

```bash
# Run playbook via exec tool
exec command="ansible-playbook -i skills/ansible/inventory/hosts.yml skills/ansible/playbooks/openclaw-vps.yml --limit eva"

# Ad-hoc command
exec command="ansible eva -i skills/ansible/inventory/hosts.yml -m shell -a 'systemctl status openclaw'"
```

### Storing Credentials

Use OpenClaw's Vaultwarden integration:
```bash
# Get password from vault cache
PASSWORD=$(.secrets/get-secret.sh "VPS - Eva")

# Use in ansible (not recommended - use ansible-vault instead)
ansible-playbook site.yml -e "ansible_ssh_pass=$PASSWORD"
```

Better: Store in Ansible Vault and use `--ask-vault-pass`.

## References

- `references/best-practices.md` - Detailed best practices guide
- `references/modules-cheatsheet.md` - Common modules quick reference
- `references/troubleshooting.md` - Extended troubleshooting guide

## External Resources

- [Ansible Documentation](https://docs.ansible.com/)
- [Ansible Galaxy](https://galaxy.ansible.com/) - Community roles
- [geerlingguy roles](https://github.com/geerlingguy?tab=repositories&q=ansible-role) - High quality roles
- [Ansible for DevOps](https://www.ansiblefordevops.com/) - Book by Jeff Geerling