OpenClaw + 飞书 + DeepSeek (千问备用) 部署全流程 (踩坑实录)

备注

另外一篇文字针对 sh脚本 以及 claw onboard交互安装的 一步一步的选择做过说明
本文主要是命令行交互为主，可以避免部分json格式问题

当你用脚本执行在终端看到那个 Yes/No 的风险提示界面时，就说明 OpenClaw 已经装好了。

此时，openclaw 命令已全局可用，配置文件目录 ~/.openclaw/ 也已生成。你可以随时关掉这个向导，直接用命令行完成所有配置——本文主要就是这么做的。
配置树后面大概会长这样：openclaw.json是i核心配置文件

ls /root/.openclaw/
agents                    devices     logs           openclaw.json.bak        tasks
browser-existing-session  extensions  memory         openclaw.json.bak.1      update-check.json
canvas                    flows       memory-tdai    openclaw.json.last-good  workspace
completions               identity    openclaw.json  state

适用环境：Ubuntu 22.04 虚拟机，NAT 网络（已解决 DNS 问题）。全程命令行操作。
本文仅记录与 OpenClaw 直接相关的安装、渠道对接、模型接入部分。Ansible 等辅助工具不在此列。
所有 API Key 均已脱敏，请替换为自己的凭证。

零、前置依赖与 install.sh 做了什么

0.1 安装脚本的行前准备

在运行安装脚本之前,系统需要具备最基础的工具链。建议先执行：

sudo apt update
sudo apt install -y curl git ca-certificates build-essential

注意：一般情况下，国内云服务器或虚拟机镜像已自带这些工具。此步为兜底操作，确保脚本能正常执行。

0.2 国内安装脚本的真实作用

国内镜像安装脚本 https://open-claw.org.cn/install-cn.sh 在 bash 中执行后，会自动、按顺序完成以下工作：

  1. 系统检测：识别当前操作系统类型（Linux/macOS）和架构。
  2. 依赖安装：自动检测并安装 Node.js ≥ 22、npm、git、curl 等必要组件。如果系统中已存在 Node.js 但版本过低，脚本会自动升级或通过 nvm 安装合适版本。
  3. 镜像源配置：将 npm registry 切换至国内淘宝镜像源（https://registry.npmmirror.com），解决包下载慢和超时问题。
  4. 核心安装：通过 npm 从镜像源拉取 openclaw-cn 包并全局安装。
  5. 路径注入：将 OpenClaw 可执行文件路径写入 Shell 配置文件（~/.bashrc 或 ~/.zshrc），使其可在终端中直接调用。
  6. 初始化检查：提示用户运行 openclaw 命令验证安装是否成功。

关键命令回顾：

# 一行命令完成全部安装
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

安装完成后，重新打开终端或执行 source ~/.bashrc，使 openclaw 命令生效。检查版本：

openclaw --version
# 预期输出类似: 2026.2.23-cn

为什么我们不用 openclaw onboard？ 因为 onboard 向导在某些网络环境下会产生 JSON 格式冲突，并且其模型选择列表中的 DeepSeek 选项可能指向 OAuth 而非 API Key。我们全程使用 openclaw china setup + 手动编辑配置文件，确保配置精确受控。

一、DeepSeek 接入 (主模型)

1.1 获取 API Key

  1. 访问 DeepSeek API 平台（与网页版 chat.deepseek.com 不同）。
  2. 注册/登录后，进入「API Keys」页面，点击「创建 API Key」。
  3. 复制生成的 sk- 开头的密钥。新用户通常有 1000 万 Token 的免费额度。

1.2 用一条命令让 OpenClaw 识别 DeepSeek

这是整个部署中最实用的一步。分开写openclaw还会报错
通过 openclaw config set --json 一次写入完整的提供商配置，无需逐条添加：

openclaw config set models.providers.deepseek --json '{
  "baseUrl": "https://api.deepseek.com",
  "apiKey": "sk-你的DeepSeek密钥",
  "api": "openai-completions",
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat",
      "contextWindow": 65536,
      "maxTokens": 8192
    }
  ]
}'

命令解析：

参数 含义
models.providers.deepseek 在 OpenClaw 中注册一个名为 deepseek 的模型提供商
baseUrl DeepSeek API 端点，兼容 OpenAI 格式
apiKey 你的 DeepSeek API 密钥
api 声明此端点遵循 OpenAI Chat Completions 协议
models[0].id 模型唯一标识符 deepseek-chat（引用时必须写作 deepseek/deepseek-chat）
models[0].contextWindow 上下文窗口大小（65536 = 64K，完全满足 OpenClaw 最低 16K 的要求）
models[0].maxTokens 模型单次回复的最大输出长度

执行后验证：

openclaw models list

当输出中出现 deepseek/deepseek-chat 时，说明 OpenClaw 已经“认识”了 DeepSeek。

常见错误：

错误现象 最可能原因 快速修复
Unknown model: deepseek/deepseek-chat 未注册 provider 或忘记写 deepseek/ 前缀 确保已在 models.providers 下配置 deepseek 及 models 列表
Error: Config validation failed: models.providers.deepseek.baseUrl: Invalid input 逐条配置时校验顺序冲突 改用 --json 一次性写入

1.3 将 DeepSeek 设为默认主模型

openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

此时在飞书中与机器人对话，回复“我是 DeepSeek 的模型”即表示主模型生效。

二、千问接入 (备用模型)

2.1 获取千问 API Key （ 估计有更新 有参数写错 回头弄完 再更新）

  1. 访问 阿里云百炼控制台。
  2. 进入「API Key 管理」，创建新 Key 并复制。
  3. 新用户有 100 万 Token 免费额度（有效期 3 个月），可在模型列表中找到 qwen-plus、qwen-max 等。

2.2 一条命令接入千问

千问需要一个唯一标识 custom-dashscope-aliyuncs-com（这个名字来源是：china setup 配置自定义端点时，系统会根据 baseURL 自动生成 endpoint ID。这里我们手动指定以保持与后续配置一致）：

openclaw config set models.providers.custom-dashscope-aliyuncs-com --json '{
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "sk-你的千问密钥",
  "api": "openai-completions",
  "models": [
    {
      "id": "qwen-plus",
      "name": "Qwen Plus",
      "contextWindow": 131072,
      "maxTokens": 4096
    }
  ]
}'

参数说明：

参数 含义
models.providers.custom-dashscope-aliyuncs-com 千问在 OpenClaw 中的唯一 Provider ID，引用时必须使用 custom-dashscope-aliyuncs-com/qwen-plus
baseUrl 阿里云百炼的 OpenAI 兼容端点
contextWindow 131072 = 128K，充分满足 OpenClaw 最低要求
api 声明协议类型为 OpenAI Chat Completions

验证接入成功：

openclaw models list

当输出中出现 custom-dashscope-aliyuncs-com/qwen-plus 时，说明千问已注册。

2.3 添加千问为备用模型

当 DeepSeek 因限流、网络超时、余额不足等特定错误导致调用失败时，OpenClaw 会按 fallbacks 列表顺序自动切换：

openclaw config set agents.defaults.model.fallbacks '["custom-dashscope-aliyuncs-com/qwen-plus"]'

注意：

  • 备用模型必须使用完整的 provider_id/model_id 格式。
  • 仅当主模型因认证失败、API 超限、网络超时等原因失败时，才会触发切换；内容安全拦截或临时命令 /model 指定模型时不会切换。

三、飞书渠道对接

3.1 飞书开放平台创建应用

  1. 登录 飞书开放平台，创建「企业自建应用」。
  2. 添加「机器人」能力。
  3. 权限管理：搜索并开通以下权限（每开通一个权限，都需在最后统一发布版本）：
    • im:message（收发消息）
    • im:message.p2p_msg:readonly（读取单聊）
    • im:message.group_at_msg:readonly（读取群聊 @）
    • im:message:send_as_bot（以应用身份发消息）
    • im:message.reactions:write_only（表情回复）
  4. 事件订阅：选择「使用长连接接收事件」，订阅 im.message.receive_v1。
  5. 发布应用：点击「创建版本」→ 填写版本号 → 发布。这一步极其容易遗忘！

3.2 安装飞书插件

openclaw plugins install @openclaw-china/channels

安装成功后会看到「OpenClaw China Channels 已就绪!」的提示。

踩坑内置 feishu 插件：OpenClaw 自带的 feishu 插件存在文件结构问题，会导致 entry escapes package directory 报错。如果遇到此错误，执行以下清理步骤：

# 确保白名单只保留 channels
openclaw config set plugins.allow '["channels"]'
# 禁用损坏的内置飞书条目
openclaw plugins disable feishu-china
# 删除残留文件
rm -rf ~/.openclaw/extensions/feishu*

3.3 配置飞书凭证

openclaw china setup

按交互提示依次输入：

  • 渠道选择：Feishu
  • App ID：cli_xxxxxxxxxxxx
  • App Secret：xxxxxxxxxxxxxxxxxxxxxxxxxxxx

3.4 用户配对审批

首次在飞书给机器人发消息时，会收到一条「access not configured」信息，内附一个配对码（例如 X25N87JS）。

在服务器执行：

openclaw pairing approve feishu X25N87JS

随后再发消息即可正常获得 AI 回复。

四、重启服务与验证

完成上述全部配置后，重启网关：

openclaw gateway restart

检查运行状态：

openclaw gateway status
# 预期看到 Runtime: running

查看当前使用的模型：

openclaw status | grep -A 5 "Sessions"
# 预期输出中包含 "deepseek-chat"

在飞书中发送一条消息，检查回复内容确认 AI 正常工作。

五、踩坑速查表 (基于实测)

错误现象 最可能原因 快速修复
entry escapes package directory: ./index.ts 飞书插件冲突/损坏 清理 feishu* 残留，白名单只保留 channels
99991672 权限拒绝 (Access denied) 飞书应用权限不全或未发布版本 补开 im:message.reactions:write_only，并创建版本发布
No API key found for provider "anthropic" 默认模型仍指向 Anthropic，但未配凭证 执行 openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"
Model "qwen-plus" specified without provider 模型名缺少 provider 前缀 改为 custom-dashscope-aliyuncs-com/qwen-plus
Model context window too small (4096 tokens) 所配模型上下文窗口 < 16K 换用 DeepSeek (64K) 或千问 qwen-plus (128K)
Unknown model: deepseek/deepseek-chat 未注册 provider 或模型 ID 拼写错误 检查 models.providers.deepseek 是否配置，以及模型 ID 是否为 deepseek-chat
飞书无反应且日志无任何输出 应用未发布版本，或“事件与回调”未选择长连接 去飞书后台确认应用已发布，且开启「使用长连接接收事件」
插件安装后网关无法启动 plugins.allow 白名单为空导致插件加载失败 设置 openclaw config set plugins.allow '["channels"]'

六、日常维护命令

# ============================================================
# OpenClaw 常用命令完整版
# ============================================================

# -------------------- 一、服务管理 --------------------
systemctl --user status openclaw-gateway.service   # 查看服务状态
systemctl --user start openclaw-gateway.service    # 启动服务
systemctl --user stop openclaw-gateway.service     # 停止服务
systemctl --user restart openclaw-gateway.service  # 重启服务

openclaw gateway restart                            # 重启网关
openclaw gateway stop                               # 停止网关
openclaw gateway start                              # 启动网关

# -------------------- 二、状态与诊断 --------------------
openclaw status                                     # 总览状态
openclaw gateway status                             # 网关状态
openclaw channels status --probe                    # 渠道连接详情
openclaw status --deep                              # 深度检查

openclaw doctor                                     # 健康诊断（只读）
openclaw doctor --fix                               # 自动修复
openclaw doctor --deep                              # 深度诊断

openclaw models list                                # 已注册模型列表

# -------------------- 三、日志（排查第一入口） --------------------
openclaw logs --follow                              # 实时日志
openclaw logs --tail 100                            # 最近100条
openclaw logs --level debug                         # 调试级别日志

# -------------------- 四、插件管理 --------------------
openclaw plugins list                               # 列出已安装插件
openclaw plugins list --enabled                     # 仅已启用的
openclaw plugins list --verbose                     # 详细信息
openclaw plugins install <名称>                      # 安装插件
openclaw plugins uninstall <名称>                    # 卸载插件
openclaw plugins enable <名称>                       # 启用插件
openclaw plugins disable <名称>                      # 禁用插件
openclaw plugins doctor                             # 插件诊断

# -------------------- 五、配置管理 --------------------
openclaw configure                                  # 交互式配置
openclaw config get                                 # 查看全部配置
openclaw config get <key>                           # 查看指定配置
openclaw config set <key> <value> --json            # 设置配置值

# -------------------- 六、模型切换 --------------------
openclaw models set deepseek/deepseek-chat          # 临时切换主模型
openclaw models set ollama/llama3                   # 切换本地模型

# -------------------- 七、飞书配对审批 --------------------
openclaw pairing approve feishu <CODE>              # 授权新用户
openclaw pairing list                               # 查看待配对请求
openclaw pairing list feishu                        # 查看飞书配对列表
openclaw pairing list --approved                    # 查看已批准用户

# -------------------- 八、更新 --------------------
openclaw update                                     # 升级到最新版
openclaw --version                                  # 查看版本

# ============================================================
# 最常用命令（日常必备）
# ============================================================
# openclaw status                          # 看一眼状态
# openclaw logs --follow                   # 有问题先看日志
# openclaw gateway restart                 # 改完配置重启
# openclaw doctor --fix                    # 一键修复
# openclaw pairing approve feishu <CODE>   # 飞书授权

部署完成。 你现在拥有一个基于 OpenClaw、通过飞书提供服务、以 DeepSeek 为主力模型、千问为自动备用的私有 AI 助手。如需扩展至钉钉或企业微信，流程雷同，核心思路不变。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

分不清 Trae、通义灵码、MarsCode、Cursor？按开发场景选，一步不踩坑

avatar DeepSeek技术社区
cover

你的 Agent 为什么总失忆？—— Memory 设计从入门到 Claude Code

avatar DeepSeek技术社区
cover

【案例分享】全网首个华三数据中心流量可视化实验，基于EVE-NG V7平台

avatar DeepSeek技术社区