Ansible 自动化批量部署 OpenClaw

概述

当你需要在多台服务器上部署 OpenClaw 实例时，手动操作不仅耗时而且容易出错。Ansible 作为无代理的自动化工具，非常适合用来管理 OpenClaw 的批量部署。

前置条件

控制节点准备

# 安装 Ansible
pip install ansible

# 验证安装
ansible --version

目标服务器要求

• 可通过 SSH 访问
• Python 3.8 或更高版本
• 具有 sudo 权限的用户

项目结构

推荐使用以下目录结构组织你的 Ansible 项目：

openclaw-deploy/
├── ansible.cfg
├── inventory/
│   ├── production.yml
│   └── staging.yml
├── group_vars/
│   ├── all.yml
│   └── openclaw_servers.yml
├── host_vars/
│   └── server1.yml
├── roles/
│   └── openclaw/
│       ├── tasks/
│       │   ├── main.yml
│       │   ├── install.yml
│       │   ├── configure.yml
│       │   └── service.yml
│       ├── templates/
│       │   ├── openclaw.json5.j2
│       │   └── openclaw.service.j2
│       ├── handlers/
│       │   └── main.yml
│       └── defaults/
│           └── main.yml
└── playbooks/
    ├── deploy.yml
    ├── update.yml
    └── rollback.yml

主机清单配置

inventory/production.yml

all:
  children:
    openclaw_servers:
      hosts:
        server1:
          ansible_host: 192.168.1.10
          openclaw_instance_name: "主助手"
        server2:
          ansible_host: 192.168.1.11
          openclaw_instance_name: "客服助手"
        server3:
          ansible_host: 192.168.1.12
          openclaw_instance_name: "内部工具"
      vars:
        ansible_user: deploy
        ansible_python_interpreter: /usr/bin/python3

角色定义

roles/openclaw/defaults/main.yml

openclaw_version: "latest"
openclaw_user: "openclaw"
openclaw_group: "openclaw"
openclaw_home: "/opt/openclaw"
openclaw_config_dir: "/etc/openclaw"
openclaw_data_dir: "/var/lib/openclaw"

# 模型配置
openclaw_model_provider: "anthropic"
openclaw_model_name: "claude-sonnet-4-20250514"

# 频道启用控制
openclaw_channels_whatsapp: false
openclaw_channels_discord: false
openclaw_channels_slack: false

roles/openclaw/tasks/install.yml

---
- name: 创建 OpenClaw 用户
  ansible.builtin.user:
    name: ""
    group: ""
    home: ""
    shell: /usr/sbin/nologin
    system: yes
    create_home: yes

- name: 安装系统依赖
  ansible.builtin.apt:
    name:
      - curl
      - git
      - nodejs
      - npm
    state: present
    update_cache: yes

- name: 安装 OpenClaw
  ansible.builtin.shell: |
    curl -fsSL https://get.openclaw.dev | bash -s -- --version 
  args:
    creates: /usr/local/bin/openclaw

- name: 验证安装
  ansible.builtin.command: openclaw --version
  register: openclaw_installed_version
  changed_when: false

- name: 输出已安装版本
  ansible.builtin.debug:
    msg: "OpenClaw 版本: "

roles/openclaw/tasks/configure.yml

---
- name: 创建配置目录
  ansible.builtin.file:
    path: ""
    state: directory
    owner: ""
    group: ""
    mode: "0750"

- name: 部署配置文件
  ansible.builtin.template:
    src: openclaw.json5.j2
    dest: "/openclaw.json5"
    owner: ""
    group: ""
    mode: "0640"
  notify: 重启 OpenClaw

- name: 配置环境变量文件
  ansible.builtin.template:
    src: openclaw.env.j2
    dest: "/.env"
    owner: ""
    group: ""
    mode: "0600"
  notify: 重启 OpenClaw

roles/openclaw/templates/openclaw.json5.j2

{
  model: {
    provider: "",
    model: ""
  },

  channels: {



  },

  systemPrompt: "你是一个有用的助手。"
}

roles/openclaw/handlers/main.yml

---
- name: 重启 OpenClaw
  ansible.builtin.systemd:
    name: openclaw
    state: restarted
    daemon_reload: yes

Playbook 定义

playbooks/deploy.yml

---
- name: 部署 OpenClaw
  hosts: openclaw_servers
  become: yes
  roles:
    - openclaw

  post_tasks:
    - name: 检查服务状态
      ansible.builtin.command: openclaw doctor
      register: health_check
      changed_when: false

    - name: 输出健康检查结果
      ansible.builtin.debug:
        msg: ""

playbooks/update.yml

---
- name: 滚动更新 OpenClaw
  hosts: openclaw_servers
  become: yes
  serial: 1  # 逐台更新，保证服务可用性

  tasks:
    - name: 备份当前配置
      ansible.builtin.copy:
        src: "/openclaw.json5"
        dest: "/openclaw.json5.bak"
        remote_src: yes

    - name: 更新 OpenClaw
      ansible.builtin.shell: |
        openclaw self-update
      notify: 重启 OpenClaw

    - name: 等待服务就绪
      ansible.builtin.uri:
        url: "http://localhost:3000/health"
        status_code: 200
      retries: 10
      delay: 5

  handlers:
    - name: 重启 OpenClaw
      ansible.builtin.systemd:
        name: openclaw
        state: restarted

执行部署

# 首次完整部署
ansible-playbook -i inventory/production.yml playbooks/deploy.yml

# 仅部署到特定服务器
ansible-playbook -i inventory/production.yml playbooks/deploy.yml --limit server1

# 预演模式（不实际执行）
ansible-playbook -i inventory/production.yml playbooks/deploy.yml --check --diff

# 滚动更新
ansible-playbook -i inventory/production.yml playbooks/update.yml

使用 Ansible Vault 管理密钥

# 加密敏感变量文件
ansible-vault encrypt group_vars/openclaw_servers.yml

# 执行时提供密码
ansible-playbook -i inventory/production.yml playbooks/deploy.yml --ask-vault-pass

# 或使用密码文件
ansible-playbook -i inventory/production.yml playbooks/deploy.yml --vault-password-file ~/.vault_pass

常见排错

SSH 连接失败

# 测试连通性
ansible openclaw_servers -i inventory/production.yml -m ping

# 指定 SSH 密钥
ansible-playbook -i inventory/production.yml playbooks/deploy.yml --private-key ~/.ssh/openclaw_deploy

配置变更未生效

确认 handler 被正确触发，也可手动重启：

ansible openclaw_servers -i inventory/production.yml -m systemd -a "name=openclaw state=restarted" --become

通过 Ansible 的自动化能力，即使管理数十台 OpenClaw 实例也能轻松应对，同时确保所有节点配置一致。