OpenClaw macOS 本地部署及飞书机器人配置指南

之后就可以直接输入 openclaw 了。

2.4 验证安装

openclaw --version

应显示版本号（如 2026.3.3）。

🧠 三、配置千问模型（阿里百炼）

OpenClaw 需要一个大模型作为'大脑'。我们以阿里云百炼平台的千问模型为例。

3.1 获取阿里百炼 API Key

1. 登录 阿里云百炼平台。
2. 左侧导航栏进入 密钥管理 → 创建 API Key，复制生成的 sk-xxxx。

3.2 确定模型 Base URL

根据你的地域选择：

• 北京：https://dashscope.aliyuncs.com/compatible-mode/v1
• 新加坡：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
• 美国：https://dashscope-us.aliyuncs.com/compatible-mode/v1

3.3 配置 OpenClaw

执行以下命令，将 sk-xxxx 替换为你的真实 API Key，并根据地域修改 baseUrl。

# 一次性设置整个 provider（注意 JSON 格式）
openclaw config set models.providers.bailian --json '{ "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-你的 API 密钥", "api": "openai-completions", "models": [ { "id": "qwen3-max-2026-01-23", "name": "qwen3-max", "reasoning": false, "input": ["text"], "contextWindow": 258000, "maxTokens": 65536 } ] }'
# 设置模型合并模式
openclaw config set models.mode "merge"
# 设置默认代理使用的模型
openclaw config set agents.defaults.model.primary "bailian/qwen3-max-2026-01-23"

验证配置：

openclaw config get models.providers.bailian

可能的问题：Error: Config validation failed 原因：配置必须一次性提供完整对象，不能分步设置。请确保使用上面的 --json 完整命令。

📱 四、配置飞书频道

飞书作为消息收发渠道，需要先在飞书开放平台创建应用，然后在 OpenClaw 中配置。

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

1. 访问 飞书开放平台，点击'创建应用' → '企业自建应用'。
2. 填写应用名称、描述，创建成功后进入应用管理页。
3. 记录 App ID 和 App Secret（在'凭证与基础信息'中）。

4.2 安装飞书插件（如果未安装）

openclaw plugins install @openclaw/feishu

检查插件状态：

openclaw plugins list | grep feishu

应显示 loaded。

4.3 配置飞书频道

# 启用飞书频道
openclaw config set channels.feishu.enabled true --json
# 设置 App ID 和 Secret（替换为你的真实值）
openclaw config set channels.feishu.appId "cli_你的 AppID"
openclaw config set channels.feishu.appSecret "你的 AppSecret"

验证：

openclaw config get channels.feishu

4.4 启动网关（关键步骤）

必须遵守顺序：先启动网关，再去飞书后台保存长连接。

openclaw gateway

保持此终端窗口打开，观察日志。当看到类似以下信息时，表示飞书插件已成功连接：

[feishu] successfully obtained token
[feishu] connected to Feishu long-living gateway

4.5 在飞书后台完成最终配置

不要关闭网关终端，打开浏览器进入你的飞书应用后台：

1. 事件与回调 → 事件配置：
   • 将'订阅方式'从 HTTP 切换为 '使用长连接接收事件'。
   • 点击 保存（此时应该成功，不会报错）。
   • 添加事件：im.message.receive_v1。
2. 权限管理：
   • 使用'批量导入/导出权限'功能，导入以下权限列表：

   {
     "scopes": {
       "tenant": [
         "contact:user.base:readonly",
         "im:message",
         "im:message.group_at_msg:readonly",
         "im:message.p2p_msg:readonly",
         "im:message:send_as_bot",
         "im:resource"
       ],
       "user": []
     }
   }
   

3. 版本管理与发布：
   • 创建一个新版本（如 1.0.1），填写更新说明，点击'发布'。

4.6 验证飞书状态

在另一个终端窗口（或标签页）执行：

openclaw status

如果 Feishu 频道显示 ON 和 OK，说明配置成功。

✅ 五、测试对话

1. 打开飞书客户端，找到你刚刚配置的机器人。
2. 在终端输入配对信息，完成后即可使用。

openclaw pairing approve feishu 配对码

发送一条消息，例如'hi'。

❗ 六、常见问题及解决办法

6.1 安装 OpenClaw 时 npm install 失败

• 现象：卡住或报网络错误。

解决：设置国内镜像源：

npm config set registry https://registry.npmmirror.com

再重新安装。

6.2 飞书后台保存长连接时提示'未检测到应用连接信息'

• 原因：网关未运行，或 App ID/Secret 错误。
• 解决：确保网关已启动（openclaw gateway）并保持运行，App ID/Secret 正确。必须先在 OpenClaw 中配置并启动网关，再去飞书后台保存。

6.3 飞书插件提示 failed to obtain token (400 错误)

• 原因：App Secret 错误，或应用未发布/未启用。
• 解决：
  • 重新核对 App ID 和 Secret。
  • 在飞书后台检查应用状态，确保至少有一个已发布的版本。
  • 添加必要的权限（尤其是 contact:user.base:readonly）。

6.4 调用模型时返回 Range of input length should be [1, 258048]

• 原因：发送给模型的提示总长度超过模型限制（258048 tokens），可能是历史消息累积过长。
• 解决：
  • 修改模型配置中的 contextWindow 为 258000。
  • 重启网关清空历史会话。
  • 限制飞书插件发送的历史消息数量（尝试 openclaw config set channels.feishu.maxHistoryMessages 3）。
  • 检查并精简代理的技能列表（openclaw skills list）。

6.5 网关启动时报 Gateway already running / 端口占用

• 原因：另一个终端或后台进程已运行网关。
• 解决：
  • 找到占用端口的进程：lsof -i :18789。
  • 终止进程：kill -9 <PID>。
  • 或直接找到运行网关的终端，按 Ctrl+C 停止。

6.6 飞书插件出现重复 ID 警告

• 现象：duplicate plugin id detected: feishu
• 原因：在多个插件目录（如 ~/openclaw/extensions 和 ~/.openclaw/extensions）同时存在飞书插件。

解决：删除项目源码内的插件副本：

rm -rf ~/openclaw/extensions/feishu

6.7 模型返回 400 错误，提示缺少某些权限（如 contact 权限）

• 原因：飞书应用未添加必要的通讯录权限。
• 解决：按错误信息中的链接添加权限，并发布新版本。

📚 七、参考资源

• OpenClaw 官方文档：https://docs.openclaw.ai
• 飞书开放平台：https://open.feishu.cn
• 阿里云百炼：https://bailian.console.aliyun.com