投稿
  1. 3A网络资讯门户首页
  2. 系统运维
  3. Linux系统

Ubuntu 22.04 服务器部署 OpenClaw 完整教程

郭靖 • • Linux系统, 系统运维 • 阅读 5

OpenClaw 是一个支持 WhatsApp、Telegram、Discord、iMessage 等多平台的消息网关，可连接 AI 代理（如 Pi）实现自动化聊天。本教程将指导你在 Ubuntu 22.04 服务器上完成从零到完整配置的部署。

一、服务器环境要求

1.1 最低配置

资源最低要求推荐配置
CPU1 核2 核+
内存2 GB4 GB+
磁盘10 GB20 GB+ SSD
网络宽带上网稳定网络

1.2 软件要求

  • 操作系统: Ubuntu 22.04 LTS (推荐) 或 Ubuntu 20.04+
  • Node.js: >= 22 (必需)
  • 包管理器: npm 或 pnpm (推荐)
  • 可选: Docker (用于容器化部署)

1.3 检查环境

# 检查系统版本
lsb_release -a

# 检查 Node.js 版本 (需要 >= 22)
node -v

# 如果没有 Node.js 22+，安装：
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 pnpm (推荐)
npm install -g pnpm

二、安装 OpenClaw

2.1 方式一：使用安装脚本 (推荐)

# 下载并执行安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

安装脚本会自动：

  • 下载最新版本的 OpenClaw
  • 安装到全局
  • 创建必要的目录结构

2.2 方式二：使用 npm 全局安装

# 使用 npm 安装
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

2.3 方式三：从源码安装 (开发者)

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 全局安装
pnpm install -g .

2.4 验证安装

# 检查 OpenClaw 版本
openclaw --version

# 查看帮助
openclaw --help

三、初始化配置

3.1 运行引导程序

首次安装需要运行引导程序进行初始配置：

# 交互式引导 (推荐)
openclaw onboard --install-daemon

# 非交互式安装
openclaw onboard --non-interactive

引导程序会让你选择：

  1. Gateway 模式: 本地 (loopback) 或远程
  2. 认证方式:
  • Anthropic API Key
  • Anthropic Setup-token (Claude 订阅)
  • OpenAI API Key
  • Venice API Key
  • 其他模型提供商
  1. Channel 配置: WhatsApp、Telegram、Discord 等
  2. 后台服务: 安装 systemd 服务 (推荐)

3.2 手动初始化 (可选)

# 仅初始化，不安装后台服务
openclaw onboard

# 仅安装后台服务
openclaw onboard --install-daemon --skip-onboarding

四、配置文件详解

4.1 配置文件路径

OpenClaw 的主配置文件位于：

~/.openclaw/openclaw.json

这是一个 JSON5 格式的文件 (支持注释和尾随逗号)。

4.2 默认配置示例

{
  // Gateway 设置
  gateway: {
    port: 18789,              // Gateway 端口
    auth: {
      token: "your-token"     // Gateway 认证令牌
    }
  },

  // 代理配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",  // 工作目录
      model: {
        primary: "anthropic/claude-opus-4-5",  // 默认模型
        fallbacks: ["anthropic/claude-sonnet-4-5"]
      }
    }
  },

  // Channel 配置
  channels: {
    whatsapp: {
      dmPolicy: "pairing",    // 配对模式
      allowFrom: []           // 白名单
    }
  }
}

4.3 配置文件结构

{
  // Gateway 配置
  gateway: {
    port: number,             // 端口号
    auth: { token: string }, // 认证令牌
    bind: string              // 绑定地址
  },

  // 模型配置
  agents: {
    defaults: {
      workspace: string,      // 工作目录
      model: {
        primary: string,      // 主模型
        fallbacks: string[]   // 备用模型
      }
    },
    list: Agent[]             // 多代理配置
  },

  // Channel 配置
  channels: {
    whatsapp: { /* ... */ },
    telegram: { /* ... */ },
    discord: { /* ... */ }
  },

  // 消息配置
  messages: {
    responsePrefix: string,   // 回复前缀
    groupChat: { /* ... */ }
  },

  // 日志配置
  logging: {
    level: string,            // 日志级别
    file: string              // 日志文件路径
  },

  // 环境变量
  env: {
    // API keys 等
  }
}

五、配置大模型

5.1 Anthropic (Claude) 配置

方式一：API Key

# 设置 API Key
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"

# 或在配置文件中设置

配置示例：

{
  env: {
    ANTHROPIC_API_KEY: "sk-ant-api03-xxx"
  },
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["anthropic/claude-sonnet-4-5"]
      }
    }
  }
}

方式二：Setup-token (Claude 订阅)

# 在有 Claude CLI 的机器上生成 token
claude setup-token

# 粘贴到 OpenClaw
openclaw models auth paste-token --provider anthropic

5.2 Venice AI 配置 (推荐隐私模式)

# 1. 获取 API Key: https://venice.ai/settings/api-keys
export VENICE_API_KEY="vapi_xxx"

# 2. 交互式配置
openclaw onboard --auth-choice venice-api-key

配置示例：

{
  env: {
    VENICE_API_KEY: "vapi_xxx"
  },
  agents: {
    defaults: {
      model: {
        primary: "venice/llama-3.3-70b"  // 隐私优先
        // 或: "venice/claude-opus-45"    // 高质量
      }
    }
  }
}

5.3 OpenAI 配置

export OPENAI_API_KEY="sk-xxx"

配置示例：

{
  env: {
    OPENAI_API_KEY: "sk-xxx"
  },
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4o",
        fallbacks: ["openai/gpt-4-turbo"]
      }
    }
  }
}

5.4 其他模型提供商

Ollama (本地模型)

{
  models: {
    mode: "merge",
    providers: {
      ollama: {
        baseUrl: "http://localhost:11434/v1",
        apiKey: "ollama",  // 不需要真实 key
        api: "openai-completions",
        models: [
          {
            id: "llama3.1",
            name: "Llama 3.1 70B",
            contextWindow: 131072,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/llama3.1"
      }
    }
  }
}

OpenRouter

{
  env: {
    OPENROUTER_API_KEY: "sk-or-v1-xxx"
  },
  agents: {
    defaults: {
      model: {
        primary: "openrouter/deepseek/deepseek-chat"
      }
    }
  }
}

5.5 提示词缓存 (Anthropic)

{
  models: {
    mode: "merge",
    providers: {
      anthropic: {
        params: {
          // short: 5分钟, long: 1小时
          cacheRetention: "long"
        }
      }
    }
  }
}

六、配置 Channel

6.1 Telegram 配置

步骤 1：创建 Bot

  1. 在 Telegram 中联系 @BotFather
  2. 发送 /newbot 创建新机器人
  3. 记录 Bot Token

步骤 2：配置 Token

方式一：环境变量

export TELEGRAM_BOT_TOKEN="123456:ABC-xxx"

方式二：配置文件

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-xxx",
      dmPolicy: "pairing",           // 配对模式
      groups: {
        "*": {
          requireMention: true       // 群组需要 @ 提及
        }
      }
    }
  }
}

完整 Telegram 配置示例

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-xxx",
      dmPolicy: "pairing",           // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"],   // 白名单
      groups: {
        "*": {
          requireMention: true,      // 默认需要 @ 提及
          // "-1001234567890": {      // 特定群组配置
          //   requireMention: false  // 该群组无需 @ 提及
          // }
        }
      },
      customCommands: [              // 自定义命令
        { command: "backup", description: "Git backup" },
        { command: "status", description: "Check status" }
      ],
      historyLimit: 50,              // 群组历史消息数
      textChunkLimit: 4000,          // 文本分块大小
      streamMode: "partial",         // 流式模式
      linkPreview: true,             // 链接预览
      mediaMaxMb: 5                  // 媒体文件大小限制
    }
  }
}

步骤 3：启动 Gateway

openclaw gateway --port 18789

步骤 4：配对 (首次使用)

首次发送 DM 给机器人会收到配对码，批准后即可使用：

# 列出待配对请求
openclaw pairing list telegram

# 批准配对
openclaw pairing approve telegram <code>

6.2 WhatsApp 配置

步骤 1：准备工作

  • 需要一个独立的手机号 (推荐)
  • VoIP 和虚拟号码通常被封锁
  • 建议使用实体 SIM 卡或本地 eSIM

步骤 2：配置

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",           // 配对模式
      allowFrom: ["+15551234567"],   // 白名单
      textChunkLimit: 4000,          // 文本分块
      chunkMode: "length",           // 分块模式
      mediaMaxMb: 50,                // 媒体大小限制
      sendReadReceipts: true         // 已读回执
    }
  }
}

步骤 3：登录 (扫码)

# 开始扫码登录
openclaw channels login

# 多账户登录
openclaw channels login --account <accountId>

扫码流程：

  1. 在手机上打开 WhatsApp
  2. 设置 → 已关联设备 → 关联新设备
  3. 扫描显示的二维码

完整 WhatsApp 配置示例

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",           // pairing | allowlist | open | disabled
      allowFrom: ["+15551234567"],   // 白名单
      groupPolicy: "allowlist",      // 群组策略
      groups: {
        "*": {
          requireMention: true       // 群组需要 @ 提及
        }
      },
      textChunkLimit: 4000,
      chunkMode: "length",           // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true,
      historyLimit: 50,              // 群组历史消息数
      // 多账户支持
      accounts: {},
        personal: {
        default: {},
        work: {}
      }
    }
  }
}

步骤 4：配对 (首次使用)

首次收到未知发送者的消息会收到配对码：

# 列出待配对请求
openclaw pairing list whatsapp

# 批准配对
openclaw pairing approve whatsapp <code>

6.3 Discord 配置

步骤 1：创建 Discord Bot

  1. 访问 https://discord.com/developers/applications
  2. 创建新应用 → Bot → 添加 Bot
  3. 复制 Bot Token
  4. 启用 Message Content Intent

步骤 2：配置

{
  channels: {
    discord: {
      enabled: true,
      token: "MTIzNDU2Nzg5MDEyMzQ1Njc4.XXXXX.XXXXX",
      dm: {
        enabled: true,
        policy: "pairing",           // 配对模式
        allowFrom: ["1234567890"],   // 白名单
        groupEnabled: false
      },
      guilds: {
        "123456789012345678": {      // 服务器 ID
          channels: {
            "general": {
              allow: true,
              requireMention: true
            },
            "help": {
              allow: true,
              requireMention: false
            }
          }
        }
      },
      historyLimit: 20,              // 历史消息数
      textChunkLimit: 2000,          // 文本分块
      maxLinesPerMessage: 17,        // 最大行数
      allowBots: false               // 是否允许 Bot 消息
    }
  }
}

步骤 3：邀请 Bot 到服务器

在 Discord Developer Portal → OAuth2 → URL Generator 生成邀请链接。

6.4 多 Channel 完整配置示例

{
  gateway: {
    port: 18789,
    auth: {
      token: "your-gateway-token"
    }
  },

  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["anthropic/claude-sonnet-4-5"]
      },
      sandbox: {
        mode: "non-main",           // 非主会话使用沙箱
        scope: "session"
      }
    },
    list: [
      {
        id: "main",
        identity: {
          name: "Assistant",
          emoji: "🦞"
        }
      }
    ]
  },

  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-xxx",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    },

    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groups": { requireMention: true }
     : {
        "* }
    },

    discord: {
      enabled: true,
      token: "MTIzNDU2Nzg5MTEyMzQ1Njc4.XXXXX.XXXXX",
      dm: {
        policy: "pairing"
      }
    }
  },

  messages: {
    responsePrefix: "🦞",
    groupChat: {
      mentionPatterns: ["@assistant", "@openclaw"]
    }
  },

  env: {
    ANTHROPIC_API_KEY: "sk-ant-api03-xxx"
  },

  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log"
  }
}

七、启动和管理

7.1 手动启动

# 前台启动 (调试)
openclaw gateway --port 18789 --verbose

# 后台启动
openclaw gateway --port 18789 &

# 指定配置文件
openclaw gateway --config /path/to/openclaw.json

7.2 后台服务管理

如果安装了 systemd 服务：

# 查看服务状态
openclaw gateway status

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

# 查看日志
openclaw logs

# 实时日志
openclaw logs --follow

7.3 开机自启

# 安装开机自启
sudo systemctl enable openclaw-gateway

# 禁用开机自启
sudo systemctl disable openclaw-gateway

八、常用命令

8.1 Gateway 管理

# 查看状态
openclaw status

# 健康检查
openclaw health

# 深度健康检查
openclaw health --deep

# 配置验证
openclaw doctor

8.2 Channel 管理

# 查看已配置的 Channel
openclaw channels list

# 登录 Channel (WhatsApp 扫码)
openclaw channels login

# 退出登录
openclaw channels logout

# 重新登录
openclaw channels login --account <accountId>

8.3 配对管理

# 列出待配对请求
openclaw pairing list

# 批准配对
openclaw pairing approve <channel> <code>

# 拒绝配对
openclaw pairing reject <channel> <code>

# 清除所有待配对请求
openclaw pairing clear

8.4 消息发送

# 发送测试消息
openclaw message send --target +15551234567 --message "Hello from OpenClaw"

# Telegram
openclaw message send --target tg:123456789 --message "Hello"

# Discord
openclaw message send --target channel:123456789 --message "Hello"

8.5 模型管理

# 查看模型列表
openclaw models list

# 查看当前模型状态
openclaw models status

# 设置默认模型
openclaw models set anthropic/claude-opus-4-5

# 测试模型连接
openclaw chat --model anthropic/claude-opus-4-5 "Hello"

8.6 配置管理

# 查看当前配置
openclaw config get

# 编辑配置 (交互式)
openclaw config edit

# 设置配置项
openclaw config set channels.telegram.botToken "xxx"

# 验证配置
openclaw doctor

九、常见问题排查

9.1 Gateway 无法启动

# 检查端口是否被占用
lsof -i :18789

# 查看详细错误
openclaw doctor

# 检查日志
openclaw logs --follow

9.2 模型认证失败

# 检查 API Key
echo $ANTHROPIC_API_KEY

# 测试模型连接
openclaw models status

# 重新认证
openclaw onboard --auth-choice anthropic-api-key

9.3 Channel 连接问题

# WhatsApp 重新登录
openclaw channels logout
openclaw channels login

# Telegram 检查网络
curl -I https://api.telegram.org

# Discord 检查 Token
openclaw channels list

9.4 权限问题

# 确保用户有权限访问配置目录
chmod -R 700 ~/.openclaw/

# 确保日志目录存在
mkdir -p /tmp/openclaw

9.5 性能优化

# 检查资源使用
openclaw status

# 查看并发限制
openclaw health | grep concurrent

# 调整并发数 (配置文件)
{
  agents: {
    defaults: {
      maxConcurrent: 5
    }
  }
}

十、安全建议

10.1 保护 API Key

# 使用环境变量而非配置文件
export ANTHROPIC_API_KEY="sk-ant-xxx"

# 或使用密钥管理服务

10.2 限制访问来源

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567", "+15559876543"]
    },
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: ["tg:123456789"]
    }
  }
}

10.3 群组控制

{
  channels: {
    telegram: {
      groups: {
        // 只允许特定群组
        "-1001234567890": {
          requireMention: true
        }
      }
    }
  }
}

10.4 审计日志

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    redactSensitive: "tools"
  }
}

十一、更新和升级

11.1 更新 OpenClaw

# 通过 npm 更新
npm update -g openclaw@latest

# 通过安装脚本更新
curl -fsSL https://openclaw.ai/install.sh | bash

11.2 重启服务

# systemd 服务
openclaw gateway restart

# 手动启动
# 先停止旧进程，再启动新进程
pkill -f openclaw
openclaw gateway --port 18789 &

11.3 回滚版本

# 查看历史版本
npm list -g openclaw

# 安装特定版本
npm install -g openclaw@<version>

十二、Docker 部署 (可选)

12.1 使用 Docker Compose

version: '3.8'

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports18789:187:
      - "89"
    volumes:
      - ~/.openclaw:/root/.openclaw
      - ./workspace:/root/.openclaw/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - VENICE_API_KEY=${VENICE_API_KEY}
    command: gateway --port 18789

12.2 启动 Docker

# 创建 .env 文件
echo "ANTHROPIC_API_KEY=sk-ant-xxx" > .env
echo "TELEGRAM_BOT_TOKEN=xxx" >> .env

# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f

十三、参考链接

  • 官方文档: https://docs.openclaw.ai
  • GitHub: https://github.com/openclaw/openclaw
  • 社区: https://discord.com/invite/clawd
  • 插件市场: https://clawhub.com

💡 提示: 生产环境建议使用独立的手机号、配置白名单、定期备份配置和凭证文件。

文章来源：https://www.cnaaa.net，转载请注明出处：https://www.cnaaa.net/archives/12366

赞 (0)
郭靖的头像郭靖
0 0
上一篇 2025年12月19日 下午1:36
下一篇 2024年5月10日 下午3:26

相关推荐

  • Linux忘记文件具体位置，怎么快速找到 系统运维

    Linux忘记文件具体位置，怎么快速找到

    要查找目录或者文件，可以使用ls、find和locate命令；要查找指定的源文件、二进制文件和manual文件等，可以使用whereis命令；要查询命令或者别名的位置，可以使用which命令。 ls命令 ls（list）命令是Linux和Unix系统中一个非常基本和常用的命令，用于列出指定目录中的文件和子目录。ls命令的主要功能是显示目录内容，包括文件名、权…

    凯影的头像 凯影
    2023年12月8日
    90200
  • 关于编码你必须知道的知识和技巧 系统运维

    关于编码你必须知道的知识和技巧

    乱码问题是所有运维职业生涯中都会遇到的问题，本篇文章带你探究背后的原理以及解决的技巧 字符编码 我们知道计算机只认识二进制数据，其他格式的数据都需要转换成二进制才能被计算机处理，也就是说我们在计算机上看到的文本、视频、可执行程序等格式的文件，最终都会转换成二进制数据交给计算机处理 计算机中最小的数据单位是bit，也叫二进制位，每一个bit都有0和1两种状态，…

    郭靖的头像 郭靖
    2023年1月16日
    1.3K00
  • 常见的windows网络管理命令 Windows系统

    常见的windows网络管理命令

    ipconfig命令 ipconfig实用程序可用于显示当前机器的TCP/IP配置。 tracert命令 路由追踪命令，用来显示数据包到达目的主机所经过的路径。 一般添加 -d 参数 ，不将地址解析为计算机名，加快路由速度 nslookup命令 nslookup命令可以指定查询的类型，可以查到DNS记录的生存时间还可以指定使用哪个DNS服务器进行解释。 ip…

    郭靖的头像 郭靖
    2022年6月10日
    1.3K00
  • NetSet – 自动化网络流量安全增强工具 Linux系统

    NetSet – 自动化网络流量安全增强工具

    NetSet旨在自动执行多个操作，以帮助用户保护网络流量。它还提供了一种通过Tor收集代理和运行实用程序的简便方法。NetSet安装和使用的也是自动配置，该工具主要用于辅助性网络安全任务。 实现了一种按需使用的终端多路复用器，它的会话通过Tor路由网关。通过自动安装和配置DNSCrypt-proxy来保护DNS流量。Tor Wall功能强制所有流量通过Tor…

    郭靖的头像 郭靖
    2023年10月8日
    1.5K00
  • Rocky9的安装与基本配置 Linux系统

    Rocky9的安装与基本配置

    安装 Rocky Linux 9.0 设置语言为：中文 — 简体中文（中国） 注意： 默认 Rocky Linux 9.0 安全设置禁用了 SSH 使用 root 密码登录了，所以在设置 root 用户密码的时候，记得勾选[允许 root 用户使用密码进行 SSH 登录] 开始安装 安装完成，点击[重启系统] 内核升级到了5.14 登录成功 防火墙配置 SE…

    郭靖的头像 郭靖
    2023年4月7日
    2.4K00

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

在线咨询： QQ交谈

邮件：712342017@qq.com

工作时间：周一至周五，8:30-17:30，节假日休息

关注微信