从零部署OpenClaw：构建私有AI助手并集成飞书全流程指南

1. 项目概述

如果你正在寻找一个能部署在自己服务器上、功能强大且能与飞书无缝集成的个人AI助手，那么OpenClaw绝对值得你花时间研究。它不像那些只能通过网页聊天的AI，OpenClaw更像是一个可以深度定制、拥有“大脑”和“手脚”的智能中枢。你可以把它想象成一个24小时在线的私人助理，不仅能通过飞书和你聊天，还能根据你的指令，调用各种工具来处理文档、查询信息，甚至管理你的工作流。

我最近就在一台Azure的虚拟机上，从零开始完整部署了一套OpenClaw，并成功接入了飞书。整个过程涉及云服务器配置、AI模型对接、反向代理、HTTPS证书以及飞书机器人开发等多个环节，虽然官方文档很全，但实际操作中还是有不少细节需要注意，尤其是针对国内用户使用Azure AI服务和飞书平台时的一些特殊配置。这篇文章，我就把我踩过的坑和验证过的完整流程，一步步拆解给你看。无论你是想搭建一个团队内部的智能问答机器人，还是想拥有一个完全受自己控制的AI伙伴，这篇指南都能帮你省下大量摸索的时间。

2. 核心思路与架构设计

在动手之前，我们先理清OpenClaw的核心工作逻辑和我们的部署架构。理解了这个，后面配置起来才会心中有数，遇到问题也知道该往哪个方向排查。

2.1 OpenClaw 的核心组件与工作流

OpenClaw的核心是Gateway（网关）。它扮演着“交通枢纽”和“大脑”的角色。所有外部请求，比如从飞书发来的消息，都会先到达Gateway。Gateway负责管理用户会话、调用配置好的AI模型（如GPT-4、Claude）进行推理，并根据AI的指令调度相应的工具（Tool）来执行具体任务，比如读取一个飞书文档。

一个典型的工作流是这样的：

1. 你在飞书上给机器人发送消息：“总结一下我昨天写的项目周报。”
2. 飞书服务器通过WebSocket长连接，将这条消息推送到你部署的OpenClaw Gateway。
3. Gateway识别出这是来自用户“张三”的请求，并加载“张三”之前的对话历史（上下文）。
4. Gateway将你的问题、历史上下文以及可用的工具列表（例如feishu_doc）一起发送给配置好的AI模型（比如Azure OpenAI的GPT-4）。
5. AI模型“思考”后回复：“我需要使用feishu_doc工具来获取周报文档的内容，请提供文档链接或ID。”
6. Gateway执行feishu_doc工具，向飞书API请求该文档的内容。
7. 获取内容后，Gateway再次将内容交给AI模型。
8. AI模型生成最终的总结文本，并通过Gateway回复给飞书，你就在飞书上看到了AI的总结。

所以，我们的部署本质上就是搭建并配置好这个Gateway，并为其接通“耳朵”（飞书通道）和“大脑”（AI模型）。

2.2 部署架构选型与考量

我们的目标是在云服务器上搭建一个稳定、可外网访问的服务。这里有几个关键决策点：

为什么选择 Azure VM？Azure、AWS、GCP或者国内的阿里云、腾讯云在基础虚拟机层面差异不大。选择Azure VM的原因之一是它与Azure OpenAI/Azure AI Claude服务的集成更顺畅，同区域访问延迟低、无需配置复杂的网络出口。当然，你也可以在任何支持Ubuntu的VPS上复现此流程。

为什么选择 Nginx + Let‘s Encrypt？OpenClaw Gateway默认监听HTTP端口。直接暴露HTTP服务既不安全（流量明文），也不专业。因此，我们需要一个反向代理。Nginx是目前最成熟、性能最好的Web服务器/反向代理之一，用它来：

• 终止SSL：处理复杂的HTTPS加密解密，让后端的Gateway专注于业务逻辑。
• 负载均衡与高可用：为未来扩展留出空间。
• 静态资源服务：如果需要，可以托管前端页面。

Let‘s Encrypt提供了免费的、自动化的SSL/TLS证书，完美解决了HTTPS的证书问题，Certbot工具可以让我们几乎一键完成证书的申请和续期。

为什么选择飞书作为首个通道？对于国内团队和个人来说，飞书是日常沟通和协作的核心工具。将AI助手集成到飞书，意味着你可以在最自然的工作场景中使用它——在群聊中@它提问，私聊它处理任务，甚至让它直接操作飞书文档和表格。这种“开箱即用”的集成体验，远比要求团队成员去访问一个单独的网页或安装新应用要好得多。

基于以上考量，我们最终的部署架构图（逻辑上）如下：

[用户飞书客户端] | v [飞书开放平台服务器] --(WebSocket长连接)--> [你的公网域名:443] | | | v (HTTPS) | [Nginx (反向代理)] | | | v (HTTP) | [OpenClaw Gateway:18789] | | +--(API调用)------------------------------>+ | | v v [飞书云文档/知识库] [Azure AI 服务]

这个架构清晰地将公网访问、安全加密、业务逻辑和AI能力分层，是生产环境可用的稳健设计。

3. 云端环境准备：创建与配置 Azure VM

一切从一台干净的云服务器开始。这里我会详细说明通过Azure CLI和Portal两种方式，并解释每个参数背后的意义。

3.1 通过 Azure CLI 快速创建（推荐）

对于习惯命令行的开发者，Azure CLI是最高效的方式。首先确保你本地已安装并登录Azure CLI (az login)。

# 创建资源组，相当于一个逻辑上的文件夹，用来管理所有相关资源。 # `eastasia` 是东亚（香港）区域，国内访问速度较好。你也可以选择 `japaneast` 等。 az group create --name openclaw-rg --location eastasia # 创建虚拟机 az vm create ` --resource-group openclaw-rg ` # 放入刚创建的资源组 --name openclawUbuntu ` # VM名称 --image Canonical:ubuntu-24_04-lts:server:latest ` # 使用Ubuntu 24.04 LTS镜像 --size Standard_B1ms ` # VM规格：1核2G内存 --admin-username aristo7298 ` # 管理员用户名（不要用root） --generate-ssh-keys ` # 自动生成SSH密钥对，私钥保存在本地 ~/.ssh --public-ip-sku Standard ` # 分配一个标准版公网IP --os-disk-size-gb 128 # 系统盘大小设为128GB，为Docker或未来数据留足空间

规格选择详解：Standard_B1ms是B系列可突增性能的VM，性价比高，对于只运行OpenClaw Gateway和Nginx来说完全足够。如果你计划在同一台机器上运行需要大量CPU的模型服务或其他应用，建议选择Standard_B2s（2核4G）或更高规格。--generate-ssh-keys会创建一对名为id_rsa和id_rsa.pub的密钥，并将公钥自动注入VM。请务必妥善保管本地生成的私钥。

创建完成后，CLI会输出包括publicIpAddress在内的JSON信息，记下这个IP。

3.2 配置网络安全组（开放端口）

虚拟机默认的网络安全组（NSG）可能只开放了SSH（22）端口。我们需要手动开放HTTP（80）和HTTPS（443）端口。

# 开放HTTP 80端口，用于后续Certbot的域名验证和HTTP到HTTPS的重定向 az vm open-port --resource-group openclaw-rg --name openclawUbuntu --port 80 --priority 1010 # 开放HTTPS 443端口，用于外部安全访问我们的服务 az vm open-port --resource-group openclaw-rg --name openclawUbuntu --port 443 --priority 1020

--priority指定规则的优先级，数字越小优先级越高。我们为自定义规则设置一个较高的数字（1010, 1020），避免与默认规则冲突。

重要安全原则：Gateway的服务端口（默认18789）绝对不要直接对公网开放。它应该只监听本地回环地址（127.0.0.1），由前面的Nginx反向代理来保护。这样，所有流量都必须先经过Nginx，我们可以方便地在Nginx层添加防火墙规则、速率限制、WAF等安全措施。

3.3 设置DNS域名标签（强烈推荐）

VM的公网IP可能会变（比如重启后如果使用动态IP）。为它绑定一个DNS域名标签，可以获得一个形如<label>.<region>.cloudapp.azure.com的稳定域名。

# 首先，我们需要知道公网IP资源的精确名称。上面`az vm create`输出的IP是临时的视图，我们需要操作的是独立的“公共IP地址”资源。 # 列出资源组内的公共IP资源 az network public-ip list -g openclaw-rg -o table # 假设输出中Name列为 `openclawUbuntuPublicIP` # 为其设置DNS标签，这里标签设为 `myopenclaw` az network public-ip update ` --resource-group openclaw-rg ` --name openclawUbuntuPublicIP ` --dns-name myopenclaw

设置成功后，你就可以通过myopenclaw.eastasia.cloudapp.azure.com这个域名来访问你的VM，无需记忆IP地址。后续申请HTTPS证书也必须使用域名。

3.4 通过 Azure Portal 创建（可视化操作）

如果你更喜欢图形界面：

1. 登录 Azure Portal 。
2. 搜索并进入“虚拟机”服务，点击“创建”。
3. 基础标签页：选择你的订阅、资源组（或新建），输入虚拟机名称，区域选择“东亚”或其他，映像选择“Ubuntu Server 24.04 LTS”。
4. 大小：点击“查看所有大小”，搜索并选择“B1ms”。
5. 管理员账户：选择“SSH公钥”。你需要将本地的~/.ssh/id_rsa.pub文件内容粘贴到“公钥”框中，或者使用Azure生成并下载密钥对。
6. 入站端口规则：选择“允许选定端口”，并添加“HTTP (80)”和“HTTPS (443)”。SSH (22)默认已添加。
7. 其他标签页保持默认，最后点击“审阅 + 创建”，通过验证后点击“创建”。
8. 创建完成后，进入虚拟机资源，在左侧菜单找到“网络”->“网络接口”->“IP配置”，点击你的公共IP地址资源。在它的“概述”或“配置”页面，可以找到“DNS名称”配置项，将其设置为一个唯一的标签。

3.5 首次SSH连接与基础系统更新

使用你创建VM时使用的私钥进行连接。如果你用的是Azure CLI生成的密钥，它通常保存在%USERPROFILE%\.ssh\id_rsa(Windows) 或~/.ssh/id_rsa(Linux/macOS)。

# 使用IP连接 ssh -i ~/.ssh/id_rsa aristo7298@<你的VM公网IP> # 或者使用域名连接（如果已设置DNS标签） ssh -i ~/.ssh/id_rsa aristo7298@myopenclaw.eastasia.cloudapp.azure.com

首次连接会提示确认主机指纹，输入yes即可。

登录后，第一件事是更新系统软件包，确保安全性和稳定性。

sudo apt update && sudo apt upgrade -y

这个命令会更新软件包列表并升级所有可升级的包。-y参数表示自动确认，在非交互式脚本中很有用。升级完成后，建议重启一次 (sudo reboot)，以确保所有更新生效，然后重新SSH连接。

4. 安装与配置 OpenClaw Gateway

系统环境就绪后，我们开始安装主角——OpenClaw。

4.1 安装 Node.js 运行环境

OpenClaw基于Node.js开发，要求版本>=22。Ubuntu 24.04的默认仓库可能不包含这么新的版本，所以我们使用NodeSource官方仓库。

# 下载并执行NodeSource的安装脚本，添加Node.js 22的软件源 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # 安装Node.js和npm（Node包管理器） sudo apt install -y nodejs # 验证安装 node --version # 应输出 v22.x.x npm --version # 应输出 10.x.x

如果node --version显示的是旧版本（如v18），请检查是否之前安装过其他版本的Node.js（例如通过snap）。可以使用which node查看路径，或考虑使用nvm进行多版本管理。对于纯净系统，上述步骤即可。

4.2 全局安装 OpenClaw CLI

OpenClaw提供了一个命令行工具openclaw，用于管理Gateway、插件和配置。我们将其全局安装。

sudo npm install -g openclaw@latest

安装完成后，验证命令是否可用：

openclaw --version

这会显示OpenClaw的版本号，例如0.1.0-alpha.123。

4.3 使用引导向导进行初始配置

OpenClaw提供了一个交互式的引导命令onboard，它能帮你完成最基础的配置。这是最推荐新手使用的方式。

openclaw onboard --install-daemon

执行这个命令后，你会进入一个交互式问答流程：

1. 运行模式 (Mode)：选择local。这是最常见的模式，Gateway进程直接运行在当前系统用户下。其他模式如docker适用于容器化部署。
2. Gateway 端口 (Port)：直接按回车使用默认的18789。记住这个端口，我们后面配置Nginx时会用到。
3. 认证模式 (Auth Mode)：选择token。系统会自动生成一个长长的、随机的Token。请务必妥善保存这个Token，它是后续从外部（如浏览器）访问Gateway控制台的密码。你可以在~/.openclaw/openclaw.json配置文件的gateway.auth.token字段找到它。
4. 主模型配置 (Primary Model)：如果你手头已经有OpenAI或Anthropic的API Key，可以在这里输入并配置。如果没有，可以先跳过，我们后面会详细配置Azure的AI服务。
5. 安装系统服务 (Install Daemon)：因为我们使用了--install-daemon参数，向导会自动为我们创建一个systemd用户服务。这意味着OpenClaw Gateway会以守护进程的形式在后台运行，即使你断开SSH连接也不会停止，并且支持开机自启。

引导完成后，Gateway服务应该已经启动。你可以用以下命令检查：

# 查看Gateway服务状态 openclaw gateway status # 预期输出：running (pid xxxx) # 查看实时日志 openclaw logs --follow # 按 Ctrl+C 退出日志查看

如果状态是running，恭喜你，OpenClaw Gateway的核心服务已经成功跑起来了！它的配置文件位于~/.openclaw/openclaw.json，我们后续的很多定制化操作都需要编辑这个文件。

5. 配置 AI 模型提供商（以 Azure 为例）

OpenClaw本身不提供AI能力，它需要连接后端的“大脑”。这里我以国内相对容易申请且稳定的Azure OpenAI和Azure AI Claude服务为例。如果你有OpenAI或Anthropic的直接API，配置会更简单。

5.1 获取 Azure AI 服务资源

在开始之前，你需要有一个Azure账户，并创建相应的AI服务资源。

1. 登录 Azure Portal 。
2. 搜索“Azure OpenAI”或“Azure AI Services”，创建相应资源。
3. 记下关键信息：
   • 终结点 (Endpoint)：格式类似https://<你的资源名称>.openai.azure.com/或https://<你的资源名称>.cognitiveservices.azure.com/。
   • API 密钥：在资源的“密钥与终结点”页面可以找到。
   • 模型部署名称：在Azure OpenAI Studio中，你需要将模型（如GPT-4）部署到一个自定义的“部署名称”下，这个名称就是配置中的id。

5.2 编辑 OpenClaw 配置文件

现在我们来修改~/.openclaw/openclaw.json，添加模型提供商。

nano ~/.openclaw/openclaw.json

你会看到一个基础的JSON配置文件。我们需要在models.providers对象中添加新的提供商。

配置 Azure OpenAI：找到"models": { "mode": "merge", "providers": {} }部分，在providers对象中添加如下配置块：

{ "models": { "mode": "merge", "providers": { "azure-openai": { // 提供商ID，可自定义，但后续引用需一致 "baseUrl": "https://<你的资源名>.openai.azure.com/openai/v1", // Azure OpenAI终结点 "apiKey": "<你的API密钥1>", // 这里填写密钥，但注意下面headers里也要用 "api": "openai-responses", // 指定使用OpenAI兼容的API格式 "authHeader": false, // 关键！Azure OpenAI使用api-key头，而非标准的Authorization头 "headers": { "api-key": "<你的API密钥1>" // 认证头 }, "models": [ { "id": "gpt-4o", // 必须与你在Azure门户中创建的“部署名称”完全一致 "name": "GPT-4o (Azure)", // 在OpenClaw UI中显示的名称 "reasoning": false, // 是否为推理模型（如o1系列）。GPT-4o不是，设为false "input": ["text", "image"], // 支持的输入类型 "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, // 成本跟踪，自托管可设为0 "contextWindow": 128000, // 上下文窗口大小（token数），根据模型实际情况填写 "maxTokens": 4096, // 单次回复最大token数 "compat": { "supportsStore": false } // 推理模型才需要设为true } ] } } } }

关键点解析：

• authHeader: false：这是Azure OpenAI与官方OpenAI API的主要区别。设为false后，OpenClaw不会自动添加Authorization: Bearer <apiKey>的请求头。
• headers: { "api-key": "..." }：我们手动指定Azure OpenAI要求的api-key请求头。
• id: 这个字段必须与你Azure门户中模型部署的名称一模一样，大小写敏感。
• reasoning和compat.supportsStore: 只有像GPT-4o-mini、o1这样的“推理模型”才需要将reasoning设为true，并且compat.supportsStore也必须设为true。对于普通聊天模型如GPT-4o、gpt-35-turbo，保持false即可。

配置 Azure AI Claude：在同一个providers对象内，继续添加Azure Claude的配置：

"azure-claude": { "baseUrl": "https://<你的资源名>.cognitiveservices.azure.com/anthropic", // 注意：结尾没有/v1！ "apiKey": "<你的API密钥2>", "api": "anthropic-messages", // 指定使用Anthropic Messages API格式 "authHeader": false, // 关键！Azure Claude使用x-api-key头 "headers": { "x-api-key": "<你的API密钥2>", // Azure Claude的认证头 "anthropic-version": "2023-06-01" // 必需的API版本头 }, "models": [ { "id": "claude-3-5-sonnet-20241022", // 模型ID，需与Azure中提供的模型ID一致 "name": "Claude 3.5 Sonnet (Azure)", "reasoning": true, // Claude 3.5 Sonnet是推理模型 "input": ["text", "image"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 200000, "maxTokens": 8192, "compat": { "supportsStore": true } // 推理模型必须为true } ] }

关键点解析（极易出错）：

• baseUrl：千万不要在末尾加/v1！Anthropic的SDK或OpenClaw内部会自动补全。如果你写成.../anthropic/v1，最终请求会变成.../anthropic/v1/v1/messages，导致404错误。这是我踩过的最大的坑。
• headers：必须包含anthropic-version。x-api-key是Azure Claude的认证方式。
• reasoning和compat.supportsStore: Claude 3.5 Sonnet是推理模型，两者都必须设为true。

5.3 设置默认使用的模型

配置好提供商后，我们需要告诉OpenClaw默认使用哪个模型来响应请求。在配置文件的agents.defaults部分进行设置。

{ "agents": { "defaults": { "model": { "primary": "azure-claude/claude-3-5-sonnet-20241022" // 格式：<提供商ID>/<模型ID> }, "models": { // 定义此代理可用的模型列表 "azure-claude/claude-3-5-sonnet-20241022": {}, "azure-openai/gpt-4o": {} } } } }

这里我将Azure Claude设为了主模型。models对象里列出了这个默认代理可以切换使用的所有模型。

5.4 重启 Gateway 并验证模型

保存配置文件后，重启Gateway使配置生效。

openclaw gateway restart

然后，我们可以检查模型状态，看是否配置成功。

openclaw models status

这个命令会列出所有已配置的模型及其状态（如是否可用）。如果看到你刚添加的模型显示为可用（available: true），说明配置正确，Gateway已经能成功连接到你的AI服务了。

实操心得：在修改配置文件时，建议使用nano或vim等命令行编辑器直接在服务器上操作，避免因Windows/macOS与Linux换行符不同导致的问题。每次修改后，务必使用openclaw gateway restart重启服务，而不是reload。修改模型配置后，建议先用openclaw models status验证连通性，再测试对话功能。

6. 配置 Nginx 反向代理与 HTTPS

现在我们的Gateway在本地跑起来了，但我们需要通过公网域名安全地访问它。这就需要Nginx出场了。

6.1 安装 Nginx

在Ubuntu上安装Nginx非常简单。

sudo apt install -y nginx

安装完成后，Nginx会自动启动。你可以通过sudo systemctl status nginx查看状态。

6.2 创建 OpenClaw 专属站点配置

我们不直接修改Nginx的默认配置，而是为OpenClaw创建一个独立的配置文件。

sudo nano /etc/nginx/sites-available/openclaw

将以下配置粘贴进去，请务必将server_name替换成你之前为VM设置的DNS域名（例如myopenclaw.eastasia.cloudapp.azure.com）。

server { listen 80; # 监听HTTP 80端口 server_name myopenclaw.eastasia.cloudapp.azure.com; # 你的域名 # 将所有请求转发到本地的OpenClaw Gateway location / { proxy_pass http://127.0.0.1:18789; # 指向Gateway的本地地址和端口 # 以下是一组标准的反向代理设置，对于WebSocket支持至关重要 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # 传递原始请求的头信息，确保后端能获取真实客户端IP等信息 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 设置超时时间，避免长连接任务（如AI生成长文本）被中断 proxy_read_timeout 86400; proxy_send_timeout 86400; } }

配置详解：

• proxy_pass: 这是核心指令，将流量转发给后端服务。127.0.0.1表示本地回环地址，确保外部无法直接访问18789端口。
• proxy_http_version 1.1和Upgrade/Connection头：这是支持WebSocket协议的关键。飞书长连接模式就是基于WebSocket的，没有这几行，飞书机器人将无法建立连接。
• X-Forwarded-*头：将客户端的真实IP和协议传递给Gateway，便于日志记录和安全审计。
• proxy_read_timeout 86400: 将读超时设为24小时，防止AI处理复杂任务时连接被Nginx关闭。

6.3 启用站点并测试配置

创建符号链接，将配置启用：

# 创建符号链接到sites-enabled目录 sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ # （可选）禁用Nginx默认的欢迎页面站点，避免冲突 sudo rm /etc/nginx/sites-enabled/default # 测试Nginx配置语法是否正确 sudo nginx -t # 预期输出：nginx: configuration file /etc/nginx/nginx.conf test is successful # 重新加载Nginx配置，使新站点生效 sudo systemctl reload nginx

现在，你应该可以通过HTTP访问你的域名了（例如http://myopenclaw.eastasia.cloudapp.azure.com）。如果看到OpenClaw的Control UI登录界面，说明Nginx反向代理配置成功。不过，现在还缺一把“安全锁”——HTTPS。

7. 使用 Let‘s Encrypt 配置 HTTPS

HTTP是明文传输，不安全。我们需要为域名申请SSL/TLS证书，启用HTTPS。Let‘s Encrypt提供了免费的自动化证书。

7.1 安装 Certbot

Certbot是EFF（电子前沿基金会）维护的自动化证书管理工具，与Nginx集成得很好。

sudo apt install -y certbot python3-certbot-nginx

7.2 申请并自动配置 SSL 证书

一条命令搞定证书申请和Nginx配置更新：

sudo certbot --nginx -d myopenclaw.eastasia.cloudapp.azure.com

执行过程中，Certbot会：

1. 询问你的邮箱（用于接收证书到期提醒）。
2. 询问你是否同意服务条款。
3. 询问你是否愿意分享邮箱给EFF（可选）。
4. 自动验证域名所有权：它会尝试在你的网站根目录下创建一个临时文件，并通过HTTP访问它。这正是为什么我们必须先配置好Nginx的HTTP（80端口）站点并确保域名能访问。
5. 验证成功后，自动从Let‘s Encrypt获取证书。
6. 询问你是否要将所有HTTP流量重定向到HTTPS。强烈建议选择“2: Redirect”，这样用户访问http://你的域名时，会自动跳转到https://。

整个过程完全自动化。完成后，Certbot会修改你的Nginx配置文件（/etc/nginx/sites-available/openclaw），添加SSL监听块和重定向规则。

7.3 验证证书与自动续期

Let‘s Encrypt证书有效期为90天，但Certbot会自动设置一个定时任务（systemd timer或cron job）来续期。

# 模拟运行续期任务，检查自动续期是否配置正确 sudo certbot renew --dry-run # 查看已安装的证书信息 sudo certbot certificates

如果renew --dry-run成功，说明自动续期配置正常。现在，用浏览器访问https://你的域名，你应该能看到绿色的安全锁标志，并且自动跳转到了HTTPS版本。

注意事项：Certbot的自动续期依赖于80端口可被外部访问以完成验证。请确保你的服务器防火墙（包括Azure NSG）始终开放80端口。如果未来你关闭了80端口，证书续期将会失败。

8. 配置 systemd 用户服务实现持久化

我们希望OpenClaw Gateway能在服务器启动时自动运行，并且在当前用户退出登录（断开SSH）后依然保持运行。这就需要用到systemd用户服务（user service）和linger功能。

8.1 理解 systemd 用户服务与 linger

• systemd 用户服务：服务配置文件存储在~/.config/systemd/user/下，以当前用户权限运行。我们用openclaw onboard --install-daemon时，它已经帮我们创建好了这个服务（openclaw-gateway.service）。
• linger：默认情况下，当用户的所有会话（如SSH）都退出时，该用户的systemd用户服务会被停止。loginctl enable-linger命令可以改变这一行为，允许用户服务在用户未登录时持续运行。这对于部署后台服务至关重要。

8.2 检查并启用 linger

首先，检查服务是否已创建并运行：

systemctl --user status openclaw-gateway

如果服务不存在，你可能需要手动创建服务文件（参考原始指南的7.2节）。如果服务存在但未运行，用systemctl --user start openclaw-gateway启动它。

接下来，启用linger，这是确保服务持久化的关键一步：

sudo loginctl enable-linger $(whoami)

这个命令需要sudo权限。执行后，即使用户完全退出，其用户服务也会继续运行。

8.3 管理服务的常用命令

掌握这些命令，方便日常运维：

# 查看服务状态 systemctl --user status openclaw-gateway # 启动服务 systemctl --user start openclaw-gateway # 停止服务 systemctl --user stop openclaw-gateway # 重启服务（修改配置后常用） systemctl --user restart openclaw-gateway # 启用开机自启 systemctl --user enable openclaw-gateway # 查看服务日志 journalctl --user -u openclaw-gateway -f # -f 表示实时跟踪

现在，即使你关闭SSH终端，OpenClaw Gateway也会继续在后台运行。你可以通过openclaw gateway status命令来确认。

9. 设备配对：从外网访问控制台

当你第一次通过HTTPS域名访问OpenClaw的Control UI（即WebChat界面）时，会看到一个要求输入Gateway Token的页面。这是一种安全措施，防止未经授权的设备访问你的AI助手。

9.1 配对流程详解

1. 获取Token：Token在初始配置时自动生成，保存在~/.openclaw/openclaw.json配置文件的gateway.auth.token字段里。你可以用cat ~/.openclaw/openclaw.json | grep -A2 -B2 token命令快速查看。
2. 访问UI：在浏览器中打开https://你的域名。
3. 输入Token：在页面提示处，粘贴你的Gateway Token并提交。
4. 服务器端批准：此时，在VM的SSH会话中，执行以下命令：

   # 列出等待批准的设备配对请求 openclaw devices list # 输出会显示请求的ID和设备信息 # 例如：ID: abc123, Name: Chrome on Windows, Status: pending # 批准特定的配对请求 openclaw devices approve abc123

5. 完成配对：批准后，浏览器页面会自动刷新，进入OpenClaw的Control UI。这台设备（浏览器）就被记住了，以后访问无需再次配对。

9.2 配对机制的安全意义

这种“一次批准”的配对机制，在保证便捷性的同时提供了基础安全。Token相当于总密码，而设备配对相当于授权了具体的设备。即使Token不慎泄露，攻击者也需要从一台你未授权过的新设备发起访问，这给了你发现异常的机会。你可以在Control UI的“设置”或通过openclaw devices list/openclaw devices revoke <ID>命令管理已配对的设备。

10. 集成飞书：让AI助手融入工作流

这是最后，也是最激动人心的一步——将你的AI助手接入飞书。

10.1 安装飞书插件

OpenClaw通过插件系统支持不同平台。首先安装飞书官方插件。

openclaw plugins install @openclaw/feishu

安装完成后，使用openclaw plugins list确认插件已安装并启用。

10.2 在飞书开放平台创建应用

这一步需要在飞书开放平台进行一系列配置，以创建一个能与OpenClaw通信的“机器人应用”。

Step 1: 创建企业自建应用

1. 访问 飞书开放平台 并登录。如果你使用Lark国际版，请访问open.larksuite.com。
2. 点击“创建企业自建应用”，填写应用名称（如“我的AI助手”）、描述，并上传一个图标。

Step 2: 获取凭证在应用的“凭证与基础信息”页面，找到：

• App ID：格式为cli_xxxxxxxx。
• App Secret：点击“显示”后复制。务必妥善保管，它相当于机器人的密码。

Step 3: 配置权限（最关键的一步）在“权限管理”页面，点击“批量导入权限”，将原始指南中提供的完整权限JSON粘贴进去。这些权限决定了你的机器人能做什么，例如读取消息、发送消息、访问云文档等。缺少必要权限会导致功能异常。

Step 4: 启用机器人能力在“应用能力” -> “机器人”中，启用机器人功能，并设置机器人的名称（用户看到的名称）。

Step 5: 配置事件订阅（启用长连接）在“事件订阅”页面：

1. 选择“使用长连接接收事件”。这是推荐模式，飞书服务器会主动与你的OpenClaw Gateway建立WebSocket连接，无需你提供公网回调URL，避免了内网穿透的麻烦。
2. 在“订阅事件”中，添加im.message.receive_v1（接收消息事件）。这是机器人能响应用户消息的基础。

Step 6: 发布应用在“版本管理与发布”中，创建版本并提交审核。对于企业自建应用，通常管理员（你自己）秒批通过。发布后，应用才正式生效。

10.3 在 OpenClaw 中配置飞书通道

有三种方式配置，推荐使用CLI，交互式体验最好。

openclaw channels add

根据提示：

1. 选择通道类型Feishu。
2. 输入刚才复制的App ID。
3. 输入App Secret。 CLI会自动将配置写入~/.openclaw/openclaw.json。

你也可以手动编辑配置文件，在channels部分添加如下内容：

{ "channels": { "feishu": { "enabled": true, "dmPolicy": "pairing", // 私聊策略：pairing（需配对）, open（开放）, allowlist（白名单） "accounts": { "main": { // 账户标识，可自定义 "appId": "cli_xxxxxxxxxxxxx", "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "botName": "我的AI助手" } } } } }

10.4 重启服务并验证连接

配置完成后，重启Gateway使飞书插件生效。

openclaw gateway restart

然后查看日志，寻找飞书连接成功的证据：

openclaw logs --follow

在日志中，你应该能看到类似[feishu] Connected to account: main或feishu channel initialized的信息，这表明飞书插件已成功启动并尝试连接。注意：只有当你在飞书开放平台完成“发布应用”后，连接才会最终建立。

10.5 在飞书中完成用户配对

连接建立后，你还需要在飞书侧完成用户配对，机器人才能与你对话。

1. 在飞书（或Lark）中，搜索你创建的机器人名称，或在工作台的应用列表中找到它。
2. 打开与机器人的私聊窗口，发送任意消息（如“你好”）。
3. 机器人会回复一个配对码（pairing code），一串数字或字母。
4. 回到VM的SSH终端，执行：

   # 查看来自飞书通道的配对请求 openclaw pairing list feishu # 输出会显示待处理的配对码和用户信息 # 批准配对 openclaw pairing approve feishu <你收到的配对码>

5. 批准后，飞书中的机器人会发送确认消息。现在，你就可以像和朋友聊天一样，在飞书中向你的AI助手提问了！

10.6 飞书高级配置与调优

基础功能打通后，你可以根据团队需求进行更精细的配置：

• 群聊策略 (groupPolicy)：默认是"open"，允许机器人被添加到任何群。可以改为"allowlist"，只允许特定的群ID，或者"disabled"完全禁用群聊。
• 流式输出 (streaming)：默认为true，AI思考回复时会通过飞书的“交互卡片”实时更新内容，体验更好。如果遇到卡片显示问题，可以设为false，等AI完全回复完再一次性发送。
• API配额优化：如果机器人使用频繁，可能触发飞书API调用频率限制。可以关闭一些非核心功能来减少调用：

  "typingIndicator": false, // 不显示“对方正在输入”状态 "resolveSenderNames": false // 不解析发送者姓名（日志中显示ID）

至此，一个部署在Azure VM上、通过HTTPS安全访问、并深度集成飞书的个人AI助手就全部搭建完成了。你可以通过飞书与它进行复杂的多轮对话，它也能利用飞书工具帮你处理文档，真正成为了一个融入日常工作流的智能伙伴。