OpenClaw Linux 完整安装指南

OpenClaw Linux 完整安装指南

本文档为可被 AI 工具解析的完整安装与配置步骤，适用于在 Linux（含 openEuler/CUOS、Ubuntu、CentOS 等）上安装 OpenClaw，并配置 DeepSeek 与飞书（Feishu）渠道。

---

一、系统要求

项目	要求
操作系统	Ubuntu 20.04/22.04、CentOS、openEuler、CUOS 等
Node.js	≥ 22.12.0（必须）
内存	建议 ≥ 4GB
磁盘	至少 20GB 可用空间
网络	安装时需能访问 npm 注册表与 GitHub（部分依赖）；飞书需能访问飞书开放平台与长连接服务

---

二、安装 Node.js 22

OpenClaw 要求 Node.js ≥ 22，系统自带的 Node 20 不满足要求。

方式 A：官方二进制包（推荐，无需 root 改系统包）

# 架构：aarch64 用 linux-arm64，x86_64 用 linux-x64
NODE_VERSION="v22.22.0"
NODE_ARCH="linux-arm64"   # 或 linux-x64
cd /tmp
curl -fsSL -o node.tar.xz "https://nodejs.org/download/release/${NODE_VERSION}/node-${NODE_VERSION}-${NODE_ARCH}.tar.xz"
sudo tar -xJf node.tar.xz -C /usr/local --strip-components=1
/usr/local/bin/node -v   # 应显示 v22.x.x

确保使用 Node 22：将 /usr/local/bin 置于 PATH 前面，或写入 ~/.bashrc：

export PATH=/usr/local/bin:$PATH

方式 B：NVM（不修改系统目录）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

---

三、安装 OpenClaw

方式 A：npm 全局安装（推荐）

export PATH=/usr/local/bin:$PATH
sudo npm install -g openclaw@latest

若依赖从 GitHub 拉取失败，可配置 Git 使用 HTTPS 后重试：

git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"

方式 B：官方一键脚本（需可访问 openclaw.ai）

curl -fsSL https://openclaw.ai/install.sh | bash

方式 C：Docker

sudo docker pull openclaw/openclaw:latest
sudo docker run -d --name openclaw -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

验证安装

openclaw --version
openclaw doctor

---

四、配置 DeepSeek 模型

4.1 配置文件位置

• 主配置：~/.openclaw/openclaw.json

4.2 添加 DeepSeek 提供商与默认模型

在 ~/.openclaw/openclaw.json 中确保存在以下结构（若文件不存在可先创建仅含 meta 的空对象，再合并）：

{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "YOUR_DEEPSEEK_API_KEY",
        "api": "openai-completions",
        "models": [
          { "id": "deepseek-chat", "name": "DeepSeek Chat" },
          { "id": "deepseek-reasoner", "name": "DeepSeek Reasoner" },
          { "id": "deepseek-v3", "name": "DeepSeek V3" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  }
}

• 将 YOUR_DEEPSEEK_API_KEY 替换为实际 DeepSeek API Key（格式通常为 sk-...）。
• 默认模型为 deepseek/deepseek-chat，可在对话或配置中改为 deepseek/deepseek-reasoner、deepseek/deepseek-v3。

4.3 可选：用 CLI 设置默认模型

openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"
openclaw models list   # 确认 deepseek 为 default

4.4 校验配置

openclaw config validate

---

五、配置飞书（Feishu）渠道

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

1. 打开 飞书开放平台，使用飞书账号登录。
2. 创建「企业自建应用」：选择图标、填写应用名称与描述，点击「创建企业自建应用」。
3. 在「凭证与基础信息」页面复制并保存：
   • App ID （格式如 cli_xxx）
   • App Secret（仅显示一次，务必保存）

5.2 权限管理：批量导入权限

1. 在应用左侧进入 「权限管理」。
2. 点击 「批量导入」。
3. 在输入框中粘贴以下 JSON（完整复制），然后确认导入。

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

4. 按飞书提示完成权限申请/审批（企业自建应用通常自动通过）。

5.3 启用机器人能力

1. 进入 「应用能力」→「机器人」。
2. 配置机器人名称，开启机器人能力。

5.4 事件订阅：添加事件并启用长连接

注意：需先完成「六、安装并启动网关」，再在飞书侧保存「长连接」配置，否则可能保存失败。

1. 在应用左侧进入 「事件订阅」（或「开发配置」→「事件与回调」）。
2. 添加事件 ：添加 im.message.receive_v1（接收单聊/群聊消息）。
3. 接收方式 ：选择 「使用长连接接收事件」（WebSocket 模式），不要选「HTTP 请求」。
4. 保存配置。

5.5 在 OpenClaw 中配置飞书

在 ~/.openclaw/openclaw.json 的 channels 中加入（与现有 models、agents 等并列）：

"channels": {
  "feishu": {
    "enabled": true,
    "dmPolicy": "pairing",
    "streaming": true,
    "accounts": {
      "main": {
        "appId": "YOUR_FEISHU_APP_ID",
        "appSecret": "YOUR_FEISHU_APP_SECRET",
        "botName": "OpenClaw 助手"
      }
    }
  }
}

• 将 YOUR_FEISHU_APP_ID、YOUR_FEISHU_APP_SECRET 替换为 5.1 中获取的 App ID 和 App Secret。
• dmPolicy: "pairing" 表示私聊需配对码，管理员批准后可对话。

或使用 CLI 添加渠道（交互式）：

openclaw channels add
# 选择 Feishu，按提示输入 App ID 和 App Secret

5.6 发布应用

在「版本管理与发布」中创建版本并发布，等待审批（企业自建应用通常自动通过）。

---

六、安装并启动网关

6.1 设置网关模式（若尚未设置）

openclaw config set gateway.mode local

6.2 安装 systemd 用户服务并启动

openclaw gateway install

• 若提示「No gateway token found」，安装过程会自动生成并写入配置。
• 服务安装到：~/.config/systemd/user/openclaw-gateway.service。

6.3 启动与开机自启（用户级 systemd）

systemctl --user start openclaw-gateway.service
systemctl --user enable openclaw-gateway.service

若使用 openclaw gateway install 已自动启用，可只确认状态：

systemctl --user status openclaw-gateway.service

6.4 检查网关状态

openclaw gateway status

• 网关启动后需数秒「预热」（加载 agent、连接飞书等），若首次显示「RPC probe: failed」或「port not listening」，可等待约 10 秒后再次执行 openclaw gateway status。
• 正常时可见：Runtime running、端口 18789 监听、Dashboard: http://127.0.0.1:18789/。

6.5 前台运行（调试用）

openclaw gateway

---

七、飞书配对与验证

7.1 私聊配对

• 在飞书中找到所创建的应用机器人，发送一条消息。
• 默认策略下，机器人会回复一个 配对码。
• 在终端执行（将 <配对码> 替换为实际收到的码）：

openclaw pairing approve feishu <配对码>

• 查看待批准列表：openclaw pairing list feishu

7.2 群组使用

• 将机器人拉入群聊，在群内 @机器人 发送消息即可（默认需 @ 才回复）。
• 群组 ID 等可通过 openclaw logs --follow 在日志中查看。

7.3 常用飞书内命令（以文本发送）

命令	说明
/status	查看机器人状态
/reset	重置对话会话
/model	查看/切换模型

---

八、常用命令速查

命令	说明
openclaw --version	查看版本
openclaw doctor	检查环境与配置
openclaw doctor --fix	自动修复部分配置
openclaw config validate	校验配置文件
openclaw config file	打印配置文件路径
openclaw models list	列出可用模型及默认模型
openclaw models set <model>	设置默认模型
openclaw gateway status	网关状态
openclaw gateway install	安装并启用网关服务
openclaw gateway restart	重启网关
openclaw gateway stop	停止网关
openclaw logs --follow	实时查看日志
openclaw pairing list feishu	飞书待批准配对列表
openclaw pairing approve feishu <CODE>	批准飞书配对

---

九、故障排除

9.1 网关显示运行但 RPC 探测失败 / 端口未监听

• 多为启动后尚未完成预热，等待约 10～30 秒后再次执行 openclaw gateway status。
• 查看日志：openclaw logs --follow 或 journalctl --user -u openclaw-gateway.service -n 200 --no-pager。
• 确认端口：ss -tlnp | grep 18789 或 netstat -tlnp | grep 18789。

9.2 飞书收不到消息 / 长连接保存失败

• 确认网关已启动：openclaw gateway status。
• 确认事件订阅已添加 im.message.receive_v1 且选择「使用长连接接收事件」。
• 确认应用已发布、权限已审批。
• 查看网关日志中是否有 feishu WebSocket 相关错误。

9.3 配置校验失败

• 运行 openclaw config validate 查看具体错误键路径。
• 常见错误：models.defaults 不被识别（应使用 agents.defaults.model.primary）；provider 缺少 baseUrl 或 models 数组。
• 修复后再次执行 openclaw config validate。

9.4 Node 版本不对

• 确保 which node 和 which npm 指向 Node 22：node -v 应 ≥ v22.12.0。
• 若使用二进制安装，保证 export PATH=/usr/local/bin:$PATH 或已在 ~/.bashrc 中配置。

---

十、配置文件结构参考

以下为最小可用的 ~/.openclaw/openclaw.json 结构示例（占位符需替换为实际值）：

{
  "meta": {
    "lastTouchedVersion": "2026.3.11",
    "lastTouchedAt": "2026-03-12T00:00:00.000Z"
  },
  "gateway": {
    "mode": "local"
  },
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-xxxxxxxx",
        "api": "openai-completions",
        "models": [
          { "id": "deepseek-chat", "name": "DeepSeek Chat" },
          { "id": "deepseek-reasoner", "name": "DeepSeek Reasoner" },
          { "id": "deepseek-v3", "name": "DeepSeek V3" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "deepseek/deepseek-chat" }
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "streaming": true,
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxx",
          "appSecret": "xxxxxxxx",
          "botName": "OpenClaw 助手"
        }
      }
    }
  }
}

---

十一、文档与资源

• OpenClaw 官方文档：https://docs.openclaw.ai
• 飞书渠道文档：https://docs.openclaw.ai/zh-CN/channels/feishu
• 故障排除：https://docs.openclaw.ai/troubleshooting

---

本文档基于 OpenClaw 2026.3.11 及飞书开放平台当前界面整理，步骤与字段名若随版本变化，以官方文档为准。# OpenClaw Linux 完整安装指南

本文档为可被 AI 工具解析的完整安装与配置步骤，适用于在 Linux（含 openEuler/CUOS、Ubuntu、CentOS 等）上安装 OpenClaw，并配置 DeepSeek 与飞书（Feishu）渠道。

---