🐧 OpenClaw Ubuntu 新手配置手册

从零开始，一步步配好 OpenClaw + 模型 + 飞书
适用：Ubuntu 22.04 / 24.04 LTS 虚拟机

---

---

📦 准备清单

开始之前，把这些东西准备好：

东西	在哪拿	备注
中转 API 地址	中转平台	通常是一个 URL
中转 API Key	中转平台	一串密钥
中转模型 ID	中转平台文档	模型的名称标识
飞书 App ID	飞书开放平台	格式 cli_xxxxx
飞书 App Secret	飞书开放平台	🔒 保密，别外发

---

🖥️ 第一步：装系统

1. 在虚拟机软件中安装 Ubuntu 24.04 LTS Server
2. VM 配置：4GB+ 内存、50GB 磁盘、网络用桥接模式
3. 装完后，虚拟机软件里 打个快照，命名为 干净系统

---

⚙️ 第二步：初始化系统

打开 VM 终端，一行一行执行：

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential

配置编译缓存（可选，OpenClaw 基于 Node.js，此项可加速启动）：

cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
EOF
source ~/.bashrc

💾 打快照，命名为 系统初始化

---

🚀 第三步：安装 OpenClaw

执行安装脚本：

# 建议先 curl -fsSL https://openclaw.ai/install.sh 查看脚本内容，确认安全后再执行
curl -fsSL https://openclaw.ai/install.sh | bash

安装过程中会启动配置向导，跟着走就行。如果向导没自动启动，手动跑：

openclaw onboard

验证安装：

openclaw --version
openclaw doctor

设置开机自启：

openclaw gateway install
openclaw gateway start
openclaw status

看到 Gateway is running 就对了。

💾 打快照，命名为 OpenClaw 安装完成

---

🌐 第四步：配置 Dashboard 远程访问

在 VM 上启动 Dashboard：

openclaw dashboard

查看 VM 的 IP 地址：

hostname -I

记下输出的 IP（比如 192.168.1.100）。

然后在你 本地电脑 上（Windows 用 PowerShell 或 CMD）：

ssh -N -L 3000:localhost:3000 你的用户名@VM的IP

📌 -N 表示只做端口转发、不打开远程 shell。

输入密码登录后，本地浏览器打开：

http://localhost:3000

看到 Dashboard 界面就成功了。

💾 打快照，命名为 Dashboard 可用

---

🤖 第五步：配置模型

方式 A：Dashboard 可视化配置（推荐新手）

在浏览器 Dashboard 中操作：

1. 点左侧 Settings

2. 点 Models 选项卡

3. 点 Add Provider，填写：

   • Provider Name：my-provider（自定义名称）
   • Base URL：你的中转 API 地址
   • API Key：你的中转 API Key
   • API Type：选 OpenAI Compatible

4. 点 Add Model，填写：

   • Model ID：你的模型 ID（从中转平台文档查）
   • Display Name：自定义显示名
   • Context Window：200000
   • Max Tokens：32000

5. 把这个模型设为 Default Model

6. 点 Save

方式 B：手动编辑配置文件

在 VM 终端中：

nano ~/.openclaw/openclaw.json

写入（替换所有 YOUR_XXX 为实际值）：

{
  "env": {
    "MY_API_KEY": "YOUR_API_KEY"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "my-provider/YOUR_MODEL_ID"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "my-provider": {
        "baseUrl": "YOUR_BASE_URL",
        "apiKey": "${MY_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "YOUR_MODEL_ID",
            "name": "YOUR_DISPLAY_NAME",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 32000
          }
        ]
      }
    }
  }
}

保存（Ctrl+O → 回车 → Ctrl+X），然后重启：

openclaw gateway restart

验证模型

openclaw models list
openclaw models status

在 Dashboard 对话界面发一条消息测试，有回复就成功了。

💾 打快照，命名为 模型配置完成

---

🎯 第六步：配置 Agent 规则

方式 A：Dashboard 配置

1. Settings → Agents
2. 编辑默认 Agent
3. 找到 System Prompt，填入：

你是一个技术面试复习助手。
- 回答专业简洁，不废话
- 优先用代码示例说明
- 不确定时坦诚说明
- 可以主动出题测试
- 复杂概念先给结论再展开

4. 保存

方式 B：配置文件

在 ~/.openclaw/openclaw.json 的 agents.defaults 中加入 systemPrompt 字段：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "my-provider/YOUR_MODEL_ID"
      },
      "systemPrompt": "你的系统提示词"
    }
  }
}

💾 打快照，命名为 Agent 规则配置完成

---

💬 第七步：接入飞书

7.1 创建飞书应用

1. 打开 https://open.feishu.cn/app
2. 点 创建企业自建应用
3. 填应用名称、描述，上传图标

7.2 获取凭证

应用页面 → 凭证与基础信息 → 复制：

• App ID
• App Secret 🔒

7.3 配置权限

权限管理 → 逐个搜索并添加以下权限：

权限标识	说明
im:message	消息基础权限
im:message:send_as_bot	以机器人身份发消息
im:message.p2p_msg:readonly	读取私聊消息
im:message.group_at_msg:readonly	读取群聊 @ 消息
im:message:readonly	读取消息
im:chat.members:bot_access	获取群成员信息
im:resource	获取消息中的资源

7.4 启用机器人

应用能力 → 机器人 → 启用 → 设置名称

7.5 配置 OpenClaw 飞书通道

⚠️ 先完成这一步再做 7.6，因为 Gateway 需要先运行起来，飞书长连接验证才能通过。

在 VM 终端执行：

openclaw channels add

选择 Feishu，输入 App ID 和 App Secret。

或者在 Dashboard 中：

Settings → Channels → Add Channel → Feishu → 填入 App ID 和 App Secret → Save

重启：

openclaw gateway restart

7.6 配置事件订阅

回到飞书开放平台：

1. 开发配置 → 事件订阅
2. 选择 使用长连接接收事件
3. 添加事件：搜索 im.message.receive_v1 并添加
4. 保存

7.7 发布应用

版本管理与发布 → 创建版本 → 提交审核 → 等审批通过

7.8 测试

1. 飞书中找到机器人，发一条消息
2. 首次会收到配对码
3. VM 终端执行：

openclaw pairing list feishu
openclaw pairing approve feishu 你的配对码

4. 再发消息，有回复就成功了

💾 打快照，命名为 飞书接入完成

---

📄 配置总览

以下是完整的 ~/.openclaw/openclaw.json，所有占位符替换后即可使用：

{
  "env": {
    "MY_API_KEY": "YOUR_API_KEY"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "my-provider/YOUR_MODEL_ID"
      },
      "systemPrompt": "你的系统提示词"
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "my-provider": {
        "baseUrl": "YOUR_BASE_URL",
        "apiKey": "${MY_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "YOUR_MODEL_ID",
            "name": "YOUR_DISPLAY_NAME",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "YOUR_FEISHU_APP_ID",
          "appSecret": "YOUR_FEISHU_APP_SECRET",
          "botName": "YOUR_BOT_NAME"
        }
      }
    }
  }
}

---

✅ 最终验证清单

执行以下命令检查状态：

openclaw status          # Gateway running
openclaw models list     # 模型可见
openclaw models status   # 模型可用
openclaw doctor          # 无报错

手动验证：

• Dashboard 能打开，能对话
• 飞书机器人能收到消息、能回复

全部通过就搞定了！🎉

---

🔧 常见问题速查

问题	解决方案
openclaw 命令找不到	echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
模型 401 报错	检查 Key、Base URL、中转平台余额
飞书不回复	确认应用已发布、事件订阅已配置、Gateway 在运行
Dashboard 打不开	检查 SSH 隧道：ssh -N -L 3000:localhost:3000 用户名@IP
VM 网络不通	ip addr show 看 IP，确认虚拟机是桥接模式
内存不够	sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

---

📝 作者提示：每次完成关键步骤后打快照，出问题可以快速回滚！