2026最新OpenClaw完整入门教程:安装、免费模型配置、问题排查详解

OpenClaw（小龙虾）是本地AI智能体框架，支持本地Ollama开源免费模型、国内免费云大模型、飞书机器人联动，可远程通过飞书下发指令操控本地电脑、执行文档/代码/自动化任务。

一、安装前置要求

1. Node.js 版本强制：≥22.19 / 24+，推荐Node24 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文件

临时关闭实时防护，解压/安装完成后添加安装目录信任白名单

模型配置异常

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