中国区- OpenClaw + 飞书 + DeepSeek (千问备用) 部署全流程 (含踩坑实录)-中国区命令行篇

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"]'

六、日常维护命令

# 服务管理
systemctl --user status openclaw-gateway.service  # 查看 systemd 服务状态
openclaw gateway restart                           # 重启网关
openclaw gateway stop                              # 停止网关

# 状态与诊断
openclaw status                                    # 总览
openclaw gateway status                            # 网关状态
openclaw channels status --probe                   # 渠道连接详情
openclaw models list                               # 已注册模型列表

# 日志 (排查问题第一入口)
openclaw logs --follow                             # 实时日志

# 模型切换
openclaw models set deepseek/deepseek-chat          # 临时切换主模型

# 飞书配对审批
openclaw pairing approve feishu <CODE>              # 授权新用户

# 更新
openclaw update                                     # 升级到最新版

---

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