教程2026年5月12日8,857 浏览约 9 分钟阅读

OpenClaw 完整本地部署安装与使用指南 手把手接入飞书机器人

本文提供适配 macOS、Linux、Windows 的 OpenClaw 完整本地部署教程，包含基础环境安装、交互式配置、通义千问模型适配、飞书机器人插件安装、配对授权及故障排查卸载全流程，新手也能一键跟着部署。

OpenClaw 完整本地部署安装与使用指南 手把手接入飞书机器人

OpenClaw 完整本地部署安装与使用指南（接入飞书）

前言

OpenClaw是一款功能强大的终端式AI助手，支持多模型适配、多渠道接入，可本地部署也支持云端一键安装。

官方官网：openclaw.ai/ GitHub仓库：github.com/openclaw/op…

部署方式：本地部署（本文核心）、云端一键安装（阿里云/火山引擎/mini max均提供）、Docker镜像安装（需自行下载镜像） 本文档为本地部署+飞书机器人接入的完整实操指南，适配macOS/Linux/Windows系统

一、准备工作：安装基础环境

OpenClaw运行依赖Node.js 24+ 和 Git，Node.js安装包自带npm，无需单独下载，以下为各系统适配的安装步骤，Windows操作需全程以管理员身份打开PowerShell。

1. Node.js 安装

方式1：官方下载（推荐新手）

官方地址：nodejs.org/

选择 LTS v24+ （稳定）版本，页面自动识别系统，直接下载对应安装包； 安装时默认选项即可，务必勾选Add to PATH，确保命令行可识别。

方式2：包管理器安装（推荐开发人员，macOS/Linux）

macOS需先安装Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install node
brew link node --overwrite --force

国内镜像源加速（解决下载缓慢）

# 配置npm淘宝镜像
npm config set registry https://registry.npmmirror.com/

2. Git 安装

方式1：官方下载

官方地址：git-scm.com/

页面自动识别系统，Windows选64位版本，macOS/Linux选对应入口； 安装时务必勾选Add Git to PATH，新手保持默认选项即可。

方式2：包管理器安装（macOS/Linux） 
# macOS
brew install git

# Linux（Debian/Ubuntu）
sudo apt install -y git

# Linux（CentOS/RHEL）
sudo dnf install -y git

3. 安装后验证（必做，确认环境生效）

打开命令行（Windows/PowerShell、macOS/Linux/终端），输入以下命令，能显示对应版本号即安装成功：

# 验证Node.js
node -v
# 验证npm
npm -v
# 验证Git
git --version

补充：Git安装后可配置全局用户信息（可选，避免部分git操作报错）

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

二、OpenClaw 安装步骤

1. macOS/Linux 系统

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

2. Windows 系统（PowerShell 管理员身份）

iwr -useb https://openclaw.ai/install.ps1 | iex

注意：macOS/Linux部分目录安装需要sudo权限，若出现权限错误，可在命令前加sudo。

三、安装后交互式配置（核心步骤）

安装完成后自动进入交互式配置流程，按以下选项选择即可，部分配置可后续在Web UI/终端修改。

配置项 选择/操作 配置说明
I understand this is powerful and inherently risky. Continue? 选择 "Yes" 确认知晓风险并继续部署
Onboarding mode 选择 “QuickStart” 快速启动模式，适合新手，简化配置
Model/auth provider 选免费Qwen / 选"Skip for now" 推荐先选Qwen（免费），后续可配置火山引擎等其他模型；暂不配置则选Skip
Filter models by provider 选择 "All providers" 显示所有模型提供商，方便后续切换
Default model 使用默认配置 保持默认，后续可在配置文件中修改
Select channel (QuickStart) 选择 “Skip for now” 暂不配置渠道，后续专门配置飞书渠道
Configure skills now? (recommended) 选择 “No” 暂不配置技能，后续按需添加
Enable hooks? 按空格键选中 → 按回车键下一步 启用钩子功能，支持命令日志、会话记忆等核心特性
How do you want to hatch your bot? 选择 "Hatch in TUI" 从终端界面启动机器人，基础交互更便捷

四、OpenClaw 配置指南（适配Qwen模型）

配置核心为模型提供商配置，本文以免费的Qwen模型为例，提供 Web UI（可视化，推荐新手）和终端（配置文件，适合开发人员）两种方式。

前置准备

Qwen API Key获取地址：bailian.console.aliyun.com/cn-beijing/，后续配置需替换占位符。

方式一：Web UI 配置（可视化，推荐新手）

  1. 打开Web UI
openclaw dashboard

打开后自动在浏览器弹出页面，若未弹出，手动访问本地地址即可。

  1. 进入配置页面 左侧菜单栏依次选择：Settings → Config → Authentication → 页面底部选择Raw模式（纯文本编辑配置）。

  2. 配置models.providers（Qwen模型核心配置） 替换原有内容，将<QWEN_API_KEY>替换为自己的Qwen API Key：

"models": {
  "providers": {
    "qwen-portal": {
      "baseUrl": "https://portal.qwen.ai/v1",
      "apiKey": "<QWEN_API_KEY>",
      "api": "openai-completions",
      "models": [
        {
          "id": "coder-model",
          "name": "Qwen Coder",
          "reasoning": false,
          "input": ["text"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        },
        {
          "id": "vision-model",
          "name": "Qwen Vision",
          "reasoning": false,
          "input": ["text", "image"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}
  1. 增加认证配置信息auth.profiles
"auth": {
  "profiles": {
    "qwen-portal:default": {
      "provider": "qwen-portal",
      "mode": "oauth"
    }
  }
}
  1. 修改agents.defaults（默认模型与工作空间配置） 将<你的工作空间目录>替换为实际路径： macOS/Linux默认/Users/你的用户名/.openclaw/workspace Windows默认C:\Users\你的用户名.openclaw\workspace 目录不存在会自动创建。
"agents": {
  "defaults": {
    "model": {
      "primary": "qwen-portal/coder-model"
    },
    "models": {
      "qwen-portal/coder-model": {
        "alias": "qwen"
      },
      "qwen-portal/vision-model": {}
    },
    "workspace": "<你的工作空间目录>",
    "compaction": {
      "mode": "safeguard"
    },
    "maxConcurrent": 1,
    "subagents": {
      "maxConcurrent": 2
    }
  }
}
  1. 配置命令黑名单（可选，禁止高风险命令） 添加在配置文件对应位置，防止机器人执行摄像头、录屏等高危操作：
"nodes": {
  "denyCommands": [
    "camera.snap",
    "camera.clip",
    "screen.record",
    "calendar.add",
    "contacts.add",
    "reminders.add"
  ]
}
  1. 保存并生效配置 点击页面右上角Save保存配置； 保存完成后点击Update更新配置； 验证配置：
openclaw config validate

无报错即配置正确。

方式二：终端配置（配置文件编辑，适合开发人员）

  1. 打开配置文件
# macOS/Linux
nano ~/.openclaw/openclaw.json

# Windows（PowerShell）
notepad $HOME/.openclaw/openclaw.json
  1. 完整配置模板 替换配置文件原有内容，需修改<QWEN_API_KEY>和<你的工作空间目录>，其他保持默认：
{
  "meta": {
    "lastTouchedVersion": "2026.2.25",
    "lastTouchedAt": "2026-02-26T12:51:37.823Z"
  },
  "wizard": {
    "lastRunAt": "2026-02-26T12:51:37.794Z",
    "lastRunCommand": "doctor",
    "lastRunVersion": "2026.2.25",
    "lastRunMode": "local"
  },
  "auth": {
    "profiles": {
      "qwen-portal:default": {
        "provider": "qwen-portal",
        "mode": "oauth"
      }
    }
  },
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "<QWEN_API_KEY>",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "vision-model",
            "name": "Qwen Vision",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "qwen-portal/coder-model"
      },
      "models": {
        "qwen-portal/coder-model": {
          "alias": "qwen"
        },
        "qwen-portal/vision-model": {}
      },
      "workspace": "<你的工作空间目录>",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 1,
      "subagents": {
        "maxConcurrent": 2
      }
    },
    "messages": {
      "ackReactionScope": "group-mentions"
    },
    "commands": {
      "native": "auto",
      "nativeSkills": "auto",
      "restart": true,
      "ownerDisplay": "raw"
    },
    "session": {
      "dmScope": "per-channel-peer"
    },
    "gateway": {
      "mode": "local",
      "port": 18789,
      "bind": "loopback",
      "auth": {
        "mode": "token",
        "token": "__OPENCLAW_REDACTED__"
      },
      "tailscale": {
        "mode": "off",
        "resetOnExit": false
      },
      "nodes": {
        "denyCommands": [
          "camera.snap",
          "camera.clip",
          "screen.record",
          "calendar.add",
          "contacts.add",
          "reminders.add"
        ]
      }
    }
  }
}
  1. 保存并退出编辑器
  • nano编辑器（macOS/Linux）：按Ctrl + O保存 → 按Enter确认 → 按Ctrl + X退出；
  • 记事本（Windows）：直接点击保存并关闭。
  1. 验证配置并重启服务
# 验证配置是否正确
openclaw config validate
# 重启网关使配置生效
openclaw gateway restart

五、OpenClaw 基础使用

支持Web UI 和 TUI（终端界面） 两种交互方式，可根据需求选择，核心功能一致。

方式一：Web UI 交互（可视化，推荐）

# 启动Web UI，自动在浏览器打开
openclaw dashboard

核心功能：Chat对话、模型配置、渠道管理、插件管理； 关键页面：Chat（AI对话）、Settings（配置）、Plugins（插件）。

方式二：TUI 终端交互（轻量，无需浏览器）

# 启动TUI终端界面
openclaw tui

TUI 常用命令（输入后按回车执行）

/status  # 查看网关状态（核心，确认服务是否运行）
/help    # 查看所有常用命令
/exit    # 退出TUI界面
/model   # 切换AI模型

状态正常标准：/status显示Runtime: running、RPC probe: success，无任何错误提示。

六、接入飞书机器人

完成OpenClaw基础配置后，接入飞书机器人实现飞书内AI对话，分为安装飞书插件、创建飞书应用、配置OpenClaw飞书参数、配置飞书机器人权限四步。

前置准备

飞书开放平台入口：open.feishu.cn

步骤一：安装OpenClaw飞书插件

提供3种安装方式，按顺序尝试，方式1失败则用方式2/3。

方式1：官方命令安装（推荐） 
openclaw plugins install @m1heng-clawd/feishu
方式2：手动下载安装（方式1失败时） 
# 1. 下载插件包到当前目录
curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
# 2. 从本地安装插件
openclaw plugins install ./feishu-0.1.3.tgz
方式3：OpenClaw自动安装

在TUI/Web UI的Chat界面发送以下内容，替换<App ID>和<App Secret>：

帮我安装飞书插件：https://github.com/AlexAnys/openclaw-feishu
我的飞书应用配置信息如下：
App ID: <App ID>
App Secret: <App Secret>

OpenClaw会自动完成安装、配置、重启。

方式4：界面选择安装

回到 openclaw config 自行选择 feishu 插件进行安装（新版支持，最便捷）

步骤二：在飞书开放平台创建企业自建应用

  1. 飞书开放平台登录后，点击右上角开发者后台；
  2. 点击创建企业自建应用，填写应用名称、应用描述，点击创建；
  3. 进入基础信息 → 凭证与基础信息，记录App ID和App Secret；
  4. 进入测试企业和人员，添加测试人员/测试群组。

步骤三：在OpenClaw中配置飞书参数

终端执行以下命令，替换<App ID>和<App Secret>：

# 配置飞书App ID
openclaw config set channels.feishu.appId "<App ID>"
# 配置飞书App Secret
openclaw config set channels.feishu.appSecret "<App Secret>"
# 启用飞书渠道
openclaw config set channels.feishu.enabled true
# 配置长连接模式
openclaw config set channels.feishu.connectionMode websocket
# 单聊策略为配对授权
openclaw config set channels.feishu.dmPolicy pairing
# 群聊策略为白名单
openclaw config set channels.feishu.groupPolicy allowlist
# 群聊需@机器人才响应
openclaw config set channels.feishu.requireMention true

配置完成后重启网关：

openclaw gateway restart

步骤四：配置飞书机器人权限与事件订阅

  1. 应用能力 → 添加机器人卡片；
  2. 完善机器人使用说明；
  3. 事件与回调选择「使用长连接接收事件」；
  4. 添加事件 im.message.receive_v1 并开通权限；
  5. 权限管理开通 im:message、contact:user.base:readonly；
  6. 应用发布 → 创建版本并发布生效。

七、飞书机器人配对授权

步骤1：获取配对码

在飞书向机器人发送任意消息，会收到配对提示。

步骤2：终端执行配对命令

openclaw pairing approve feishu xxxx

配对成功终端输出：Pairing approved successfully。

步骤3：重启网关使授权生效

openclaw gateway restart

步骤4：验证授权

再次发送消息能正常回复即配置完成。

八、问题排查与卸载

（一）自诊断与问题修复

# 1. 自动诊断并修复配置
openclaw doctor --fix
# 2. 重启网关
openclaw gateway restart
# 3. 检查网关状态
openclaw gateway status
常见问题排查
  1. 网关端口18789占用
# macOS/Linux 查看端口
lsof -i:18789
# Windows 查看端口
netstat -ano | findstr "18789"

# 杀死进程 macOS/Linux
kill -9 PID
# Windows
taskkill /F /PID PID

# 修改网关端口
openclaw config set agents.gateway.port 18788
openclaw gateway restart
  1. 飞书机器人无响应：重装插件 → 重启网关 → 核对长连接配置。
  2. 模型调用失败：核对API Key、检查网络、重启网关。

（二）彻底卸载OpenClaw

macOS/Linux 卸载 
# 停止网关服务
openclaw gateway stop
# 卸载全局npm包
npm uninstall -g openclaw
# 删除配置缓存
rm -rf ~/.openclaw
rm -rf /tmp/openclaw
# 删除macOS启动项
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 删除Linux systemd服务
sudo rm -f /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload
# 杀死相关进程
pkill -f "node.*openclaw"
pkill -f openclaw
Windows 卸载（PowerShell管理员） 
# 停止网关服务
openclaw gateway stop
# 卸载全局npm包
npm uninstall -g openclaw
# 删除配置缓存
Remove-Item -Recurse -Force $HOME/.openclaw
Remove-Item -Recurse -Force $env:TMP/openclaw
# 杀死进程
taskkill /F /IM node.exe /FI "WINDOWTITLE eq openclaw"
taskkill /F /IM openclaw.exe

九、附录

附录1：常用OpenClaw命令（速查）

# 服务管理
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status

# 配置管理
openclaw config validate
openclaw config set <key> <value>

# 插件管理
openclaw plugins list
openclaw plugins install <插件地址>
openclaw plugins uninstall <插件名>

# 诊断与修复
openclaw doctor
openclaw doctor --fix

# 交互方式
openclaw dashboard
openclaw tui

# 飞书配对
openclaw pairing approve feishu <配对码>

附录2：常见问题FAQ

Q：安装时提示curl/wget缺失？ A：macOS执行brew install curl；Linux执行sudo apt install curl wget；Windows安装Git Bash自带curl。

Q：配置文件修改后不生效？ A：执行openclaw config validate校验配置，再执行openclaw gateway restart重启网关。

Q：飞书机器人发布后企业内无法使用？ A：在飞书开发者后台添加全部测试人员，重新发布版本。

Q：TUI/Web UI无法启动？ A：核对Node.js版本≥v24，执行openclaw doctor --fix修复后重启服务。

优质API服务推荐

在使用OpenClaw本地部署过程中，除了自带模型外，搭配KoalaAPI使用体验极佳，非常适合个人及小型团队接入多模型调用。

KoalaAPI 完美兼容OpenClaw的OpenAI接口协议格式，无需额外修改配置即可直接接入；聚合了主流大模型接口，响应速度稳定、延迟低，计费性价比高，支持按量计费无门槛使用。同时适配本地私有化部署的OpenClaw终端调用、飞书机器人模型对话等场景，省去自行申请各大模型官方密钥的繁琐流程，是搭配OpenClaw搭建本地AI助手、企业内部智能机器人的优选API服务。

标签OpenClaw 本地部署OpenClaw 安装教程OpenClaw 接入飞书OpenClaw 配置指南OpenClaw 飞书机器人
Koala API · 一站式大模型 API 中转

把博客读到的，落地到你的下一个项目

国内直连 · 兼容 OpenAI SDK · GPT / Claude / Gemini 等主流模型聚合

立即注册查看接入教程

延伸阅读

2026-05-19

给小龙虾上把锁：Sandbox 沙箱机制

详解 OpenClaw 沙箱部署配置，搭配 KOALAAPI 优化 Agent 安全运行环境

2026-05-18

67 个 AI 编程必会知识，1.6w 字一次讲透！

详解 AI 编程全套核心术语，搭配 KoalaAPI 快速上手 AI 开发与实操

2026-05-18

Skill学习指南🧑‍💻｜AI Agent技能包从零入门到精通

详解AI Skill概念、目录结构、加载机制，附带实战案例，搭配KoalaAPI快速上手AI编程。

2026-05-15

程序员最常用的10个AI提示词

整理程序员全套 AI 提示词模板，覆盖代码生成、排错、优化，适配 AI 编程快速上手