今天要聊的OpenClaw（江湖人称"小龙虾"），本质上是一个扎根在本地的AI智能体框架。它的核心亮点在于，既能绑定你本地的Ollama开源模型——免费的，也能接入国内各种云大模型的免费额度，甚至还能跟飞书机器人联动。什么意思呢？就是你可以躺在沙发上，拿手机发条飞书消息，让它在千里之外的电脑上执行代码、读文档、处理文件，一口气搞定。

这篇文章，从安装到配置，再到飞书远程控制，以及常见的坑和一言不合的修复方案，一股脑儿全说清。

一、安装前置要求

动手之前，先过一遍几个硬性门槛：

1. Node.js版本不能低于22.19，建议上到24 LTS，版本太低直接不认。
2. 系统这边，Windows10往后、全系列macOS、Linux Ubuntu/Debian、甚至WSL2，都行。
3. Windows用户尤其注意：要用管理员权限跑终端，并且最好是临时关掉杀毒软件或者Defender的实时防护，否则它会拦着你读写文件、操控键鼠，那就尴尬了。
4. 安装路径不能有中文和空格，纯英文路径走起。
5. 端口要放行，本地网关默认是18789，但飞书走的是长连接，不需要公网端口映射，这点省心不少。

二、全平台一键安装（推荐新手）

1. Windows（PowerShell管理员）

官方原版脚本：

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

如果遇到下载超时，换国内加速镜像：

iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

弹框提示脚本被禁止执行？先解锁一下权限：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# 出来提示，输入Y确认，再跑上面的安装脚本

2. macOS / Linux / WSL2

官方脚本走起：

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

国内用户也可以换加速版：

curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

3. npm手动安装（适合想精准控制版本的开发者）

# 全局安装
npm install -g openclaw@latest
# pnpm更快，推荐
pnpm add -g openclaw@latest
pnpm approve-builds -g

4. 验证安装成功

新开一个终端窗口，跑一下命令：

openclaw --version
# 初始化向导，首次必跑
openclaw onboard
# 启动网关服务，这是核心后台
openclaw gateway start
# 查看网关运行状态
openclaw gateway status

只要输出版本号，说明装好了。

三、免费模型两种配置方案（零付费）

方案A：本地Ollama开源模型（完全离线、永久免费，首选）

全程不消耗API额度，本地显卡运行，而且支持工具调用——说白了，飞书指令执行那些关键操作都依赖它。

步骤1：安装Ollama

直接去官网ollama.com下载：

• Windows/macOS：双击安装包，下一步到底。
• Linux一键脚本：

curl -fsSL https://ollama.com/install.sh | sh

步骤2：拉取适配OpenClaw的免费模型（必须支持Function Call）

轻量低配机器，比如8G内存：

ollama pull qwen3.5:7b

16G内存，办公或者写代码最舒适：

ollama pull qwen2.5:14b
ollama pull deepseek-r1:14b # 推理能力强，文档分析利器

32G以上内存的高性能机器，直接上大模型：

ollama pull qwen3.5:27b

查看已下载的模型：ollama list

步骤3：OpenClaw绑定Ollama本地模型

1. 保持Ollama后台运行，默认地址是http://127.0.0.1:11434
2. 然后在OpenClaw里添加本地模型源：

openclaw models add ollama
# 选择默认主模型
openclaw models set ollama/qwen3.5:7b
# 校验模型状态
openclaw models status
# 测试对话
openclaw chat "测试本地模型是否可用"

方案B：国内云模型免费额度（无显卡电脑，联网使用）

1. 通义千问免费版（阿里百炼，每月有个人免费token）

1. 先去阿里云百炼控制台创建API Key。
2. 接着在OpenClaw里配置：

openclaw models auth setup-token --provider qwen
# 粘贴API Key，设置默认模型
openclaw models set qwen-portal/coder-model

2. 智谱GLM免费个人套餐

1. 智谱开放平台获取API Key。
2. 配置命令如下：

openclaw models auth setup-token --provider zhipu
openclaw models set glm-4-flash # 免费高速版

模型通用调试命令

/model list        # 查看所有可用模型
/model 模型名      # 临时切换对话模型
openclaw doctor --fix # 自动修复模型配置异常

四、飞书机器人完整连接教程（长连接无需内网穿透）

远程操控电脑最日常的场景，其实是躺在床上想让它帮你打开个截图，或者跑个脚本。这个时候，飞书机器人就派上用场了。

阶段1：飞书开放平台创建企业自建应用

登录飞书开放平台open.feishu.cn，创建一个企业自建应用，名字可以随便起，比如OpenClaw本地助手。

添加应用能力，找到并开启【机器人】。

到基础信息里复制三样东西：App ID、App Secret、Verification Token。

权限批量导入（必须）

打开权限管理→批量导入，把下面的最小权限JSON粘贴进去：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:chat",
      "contact:user",
      "docx:document:readonly",
      "drive:file:readonly"
    ]
  }
}

事件订阅这一步是关键：

• 订阅方式选择长连接接收事件，不需要你有公网IP或者ngrok。
• 添加事件：im.message.receive_v1（接收消息）。
• 保存并开通事件权限。

最后，版本管理→发布应用到企业内部。

阶段2：OpenClaw配置飞书通道

在终端中添加飞书渠道：

openclaw channel add feishu

按提示依次粘贴AppID、AppSecret、VerificationToken。

如果想允许私聊和群聊全响应，需要手动配置两个参数：

openclaw config set channels.feishu.dmPolicy open
openclaw config set channels.feishu.allowFrom '["*"]' --strict-json

最后重启网关：openclaw gateway restart

阶段3：测试验证

1. 在飞书里搜索刚才创建的机器人名字，加好友或拉进群聊。
2. @它发一条指令，比如列出桌面所有文件。
3. 如果本地OpenClaw能执行任务并返回结果，就算对接成功了。

多机器人扩展

想再加一个？很简单：

openclaw channel add feishu --name feishu_work

五、高频常见问题与一键排查方案

安装启动类报错

1. openclaw 不是有效命令

多半是因为npm全局路径没加到系统环境变量里。修复方法：

• Windows：环境变量Path里新增C:Users用户名AppDataRoamingnpm
• 或者重装全局包：npm uninstall -g openclaw && npm install -g openclaw

2. 网关启动失败、端口18789被占用

# Windows查找占用端口进程
netstat -ano | findstr 18789
# Linux/macOS
lsof -i:18789
# 强制重启网关
openclaw gateway stop && openclaw gateway start

3. 杀毒软件直接删除OpenClaw文件

很多杀毒软件对这类工具比较敏感。最直接的办法：临时关闭实时防护，安装完成后把OpenClaw的安装目录加进白名单。

模型配置异常

1. Ollama模型调用超时、无返回

• 先确认ollama服务是否在运行：ollama list有输出才行。
• 修改配置文件~/.openclaw/config.yaml，加一行超时参数：

modelGateway:
  ollamaTimeout: 60000

改完重启网关：openclaw gateway restart

2. 工具调用失败（飞书下发指令无操作）

问题出在模型不支持Function Call，比如旧版Llama、Gemma2基础版。直接切换Qwen2.5/DeepSeek-R1系列模型就能解决。

3. 提示上下文窗口不足

编辑config.yaml增大上下文即可：

contextWindow: 65536

4. 云模型提示No API key found

# 重新绑定密钥
openclaw models auth setup-token --provider qwen
openclaw models status

飞书机器人无响应（最常见的问题）

1. @机器人完全不回复消息

按以下顺序排查：

① 检查网关：openclaw gateway status必须显示running。

② 看实时日志，定位错误：openclaw logs --follow

③ 飞书后台仔细校验：权限全部开通、事件订阅为长连接、应用已经发布。

④ 如果以上都对了，就重新录入一遍AppID/AppSecret，再重启网关试试。

2. 机器人能收到消息，但执行本地任务报错

• 关闭Windows UAC权限限制，以管理员身份启动OpenClaw。
• 确认Ollama或云模型正常运行。

3. 只能单聊、群聊@无响应

修改配置，放开群聊权限：

openclaw config set channels.feishu.allowGroup true
openclaw gateway restart

通用万能排查命令

# 自动检测并修复全部配置问题
openclaw doctor --fix
# 实时查看运行日志
openclaw logs --follow
# 重置全部配置（实在不行就用这招）
openclaw config reset
openclaw gateway restart

六、基础运维常用命令汇总

# 网关生命周期
openclaw gateway start    # 启动后台服务
openclaw gateway stop     # 停止服务
openclaw gateway restart  # 重载配置
openclaw gateway status   # 运行状态检查

# 模型管理
openclaw models list
openclaw models set [模型名]
openclaw models status

# 飞书渠道管理
openclaw channel list
openclaw channel remove feishu # 删除失效机器人配置

# 日志与诊断
openclaw logs --follow
openclaw doctor --fix