ClawdBot保姆级部署指南：本地运行Telegram全能翻译机器人（含OCR/语音转写）

你是否厌倦了在群聊里反复复制粘贴文字去网页翻译？是否想让一张截图里的外文菜单、一段会议录音、甚至群友发来的模糊证件照，都能秒变中文？ClawdBot 不是另一个云端 SaaS 服务，而是一个真正属于你自己的、能装进笔记本或树莓派的 AI 翻译中枢——它不依赖外部 API 密钥，不上传隐私数据，不收订阅费，所有 OCR、语音转写、多语言翻译、汇率天气查询，都在你本地设备上安静完成。

这不是概念演示，而是已验证的工程实践。本文将带你从零开始，用最直白的方式，在普通 Linux 或 macOS 机器上完整部署 ClawdBot，并让它真正跑起来、连上 Telegram、处理真实消息。过程中不绕弯、不跳步、不假设你懂 Docker 网络或 vLLM 配置，每一步都附带可执行命令和明确反馈判断标准。部署完成后，你将拥有一个：
私有、离线、无数据外泄风险的翻译助手
支持语音→文字→翻译全流程（Whisper tiny 本地运行）
支持图片→文字识别→翻译（PaddleOCR 轻量模型）
内置 /weather /fx /wiki 等高频实用命令
群聊中 @bot 即自动识别语言并返回结果（0.8 秒内）
所有配置通过 Web 界面或 JSON 文件直观管理

准备好后，我们直接开始。

1. 环境准备与一键部署

ClawdBot 的设计哲学是“开箱即用”，它的部署流程刻意避开了传统 AI 项目常见的环境冲突、CUDA 版本地狱、Python 依赖打架等问题。核心依赖全部打包进官方镜像，你只需确保系统满足最低要求，然后一条命令启动。

1.1 基础环境检查

请在终端中依次执行以下命令，确认你的设备满足条件：

# 检查 Docker 是否已安装（ClawdBot 必须运行在 Docker 环境中）
docker --version

# 检查 docker-compose 是否可用（v2.x 推荐，v1.x 也可用）
docker-compose --version

# 检查系统内存（建议 ≥ 4GB，树莓派 4B 4GB 版实测稳定）
free -h | grep Mem

# 检查磁盘空间（镜像约 300MB，工作目录建议预留 ≥ 2GB）
df -h | grep $(df . | tail -1 | awk '{print $1}')
  • 如果 docker 和 docker-compose 均返回版本号（如 Docker version 26.1.4），且内存 ≥ 4GB、磁盘空间充足，可继续。
  • 若未安装 Docker，请先访问 Docker 官方文档 根据你的操作系统完成安装。注意：Mac 用户请务必使用 Docker Desktop（非仅 CLI 工具），Windows 用户需启用 WSL2。

1.2 下载并启动 ClawdBot

ClawdBot 提供了预构建的 docker-compose.yml 启动包，无需手动编写配置。我们使用 curl 直接拉取并启动：

# 创建专属工作目录（推荐放在用户主目录下，便于后续管理）
mkdir -p ~/clawdbot && cd ~/clawdbot

# 下载官方 docker-compose 配置（此为稳定版，非开发分支）
curl -fsSL https://raw.githubusercontent.com/clawd-bot/clawd/main/docker-compose.yml -o docker-compose.yml

# 启动服务（后台运行，-d 参数）
docker-compose up -d

# 查看服务状态（等待 10–20 秒，直到显示 "healthy"）
docker-compose ps

你会看到类似输出：

NAME                COMMAND                  SERVICE             STATUS              PORTS
clawdbot-gateway    "/app/bin/gateway ..."   gateway             healthy (starting)  0.0.0.0:18780->18780/tcp, 0.0.0.0:7860->7860/tcp
clawdbot-web        "/app/bin/web ..."       web                 healthy             0.0.0.0:7860->7860/tcp

注意：首次启动会自动拉取约 300MB 的镜像，耗时取决于网络速度。若 STATUS 长时间显示 starting，请执行 docker-compose logs gateway 查看具体初始化日志。

1.3 验证基础服务是否就绪

服务启动后，ClawdBot 的 Web 控制台（Dashboard）和内部网关（Gateway）即已就绪。我们通过命令行快速验证：

# 检查 Gateway 是否响应（这是所有功能的通信中枢）
curl -s http://localhost:18780/health | jq .status 2>/dev/null || echo " Gateway 未响应"

# 检查 Web UI 是否可访问（返回 HTML 片段即表示正常）
curl -s http://localhost:7860 | head -n 1 | grep -q "<html>" && echo " Web UI 可访问" || echo " Web UI 不可用"

如果两条都显示 ，说明底层服务已成功运行。接下来，我们将为你开通 Web 界面的访问权限。

2. Web 控制台（Dashboard）访问与授权

ClawdBot 的 Web 控制台默认启用了设备认证机制，这是其隐私优先设计的关键一环——它不会让你直接输入账号密码，而是通过“设备请求 → 人工批准”的方式建立可信连接，杜绝未授权访问。

2.1 获取待审批的设备请求

打开终端，执行以下命令列出当前所有待处理的设备请求：

clawdbot devices list

你会看到类似输出：

ID                                    Status     Created At           Last Seen
a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8  pending    2026-01-24 14:22:18  -

只要 Status 显示为 pending，就说明你的浏览器已向 ClawdBot 发送了连接请求，但尚未被批准。

2.2 批准设备并获取访问链接

复制上面输出中的 ID（一长串字母数字组合），执行批准命令：

clawdbot devices approve a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8

批准成功后，终端会显示：

 Device approved. You may now access the dashboard.

此时，你有两种方式打开控制台：

  • 方式一（推荐）：直接访问本地地址
    在浏览器中打开 http://localhost:7860。如果页面正常加载，说明一切顺利。

  • 方式二（远程/无 GUI 场景）：使用带 Token 的链接
    若你在服务器上操作（如通过 SSH 连接树莓派），或本地无法直连，执行：

    clawdbot dashboard

    终端将输出类似内容：

    Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
Then open:
http://localhost:7860/
http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762

    将 http://localhost:7860/... 这一行完整复制，粘贴到你本地电脑的浏览器地址栏中即可访问。该 Token 一次性有效，刷新页面后需重新执行 clawdbot dashboard 获取新链接。

小贴士：如果你使用的是 macOS 或 Windows，且 Docker Desktop 正常运行，http://localhost:7860 几乎总能成功。Linux 服务器用户请确保防火墙放行 7860 端口，或使用 ssh -L 7860:localhost:7860 user@server 建立本地端口转发。

2.3 熟悉控制台界面布局

成功进入 Dashboard 后，你会看到一个简洁的三栏式界面：

  • 左侧导航栏：包含 Home（概览）、Config（配置）、Models（模型管理）、Channels（消息通道）、Logs（日志）等模块。
  • 中间主区域：根据所选菜单动态展示内容，例如 Home 页会显示当前活跃模型、在线设备数、最近处理的消息摘要。
  • 右上角用户头像：点击可查看当前登录设备、退出登录或切换账户（ClawdBot 支持多用户，但默认单机单用户）。

此时，你已拥有了一个完全可控的 AI 助手管理入口。下一步，我们将让它真正“开口说话”——接入 Telegram。

3. Telegram 机器人配置与实测

ClawdBot 的核心价值在于无缝融入你的日常沟通场景。配置 Telegram 通道是整个流程中最关键的一步，它决定了你的机器人能否接收消息、理解意图、并返回结果。

3.1 获取 Telegram Bot Token

这一步需要你先在 Telegram 中创建一个 Bot。请按以下步骤操作（全程在手机或电脑版 Telegram App 内完成）：

  1. 在 Telegram 中搜索 @BotFather 并打开对话；
  2. 发送 /newbot，BotFather 会提示你输入 Bot 名称（如 MyClawdTranslator）；
  3. 再输入 Bot 的用户名（必须以 _bot 结尾，如 myclawdtranslator_bot）；
  4. BotFather 会返回一串形如 1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef 的 Token —— 请务必复制并保存好，它相当于机器人的密码，泄露即失控。

安全提醒：该 Token 仅用于配置，ClawdBot 本身不会将其上传至任何第三方服务器。你可在后续配置中随时更换。

3.2 配置 Telegram 通道（JSON 方式）

ClawdBot 推荐通过修改配置文件来设置 Telegram，因其更稳定、可版本化、且避免 UI 缓存问题。配置文件路径为 ~/.clawdbot/clawdbot.json，但 Docker 容器内映射到了 /app/clawdbot.json。我们直接编辑容器内的文件：

# 进入容器内部（方便直接编辑配置）
docker-compose exec gateway sh

# 使用 vi 编辑配置文件（如不熟悉 vi，可用 nano 替代：apk add nano && nano /app/clawdbot.json）
vi /app/clawdbot.json

在文件中找到 "channels" 字段（若不存在则新建），插入以下内容（请将 YOUR_BOT_TOKEN 替换为你从 BotFather 获取的真实 Token）：

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "YOUR_BOT_TOKEN",
    "dmPolicy": "pairing",
    "groupPolicy": "allowlist",
    "streamMode": "partial"
  }
}
  • dmPolicy: "pairing" 表示私聊消息默认允许处理；
  • groupPolicy: "allowlist" 表示群聊需手动添加白名单（更安全，防误触）；
  • streamMode: "partial" 表示对长消息分块处理，避免超时。

保存并退出编辑器（vi 中按 Esc → 输入 :wq → 回车）。

3.3 重启服务并验证通道状态

配置修改后，必须重启相关服务才能生效：

# 退出容器
exit

# 重启 gateway 服务（Telegram 通道由它驱动）
docker-compose restart gateway

# 等待 10 秒后，检查通道状态
clawdbot channels status

理想输出应包含：

- Telegram default: enabled, configured, mode:polling, token:config

若显示 not configured 或 disabled，请检查 JSON 语法是否正确（尤其引号、逗号）、Token 是否拼写错误、以及是否遗漏了外层大括号 {}。

3.4 实测：发送第一条翻译请求

现在，打开你的 Telegram App：

  • 私聊测试：搜索并关注你刚创建的 Bot（如 @myclawdtranslator_bot），发送任意一句话，例如 Hello, how are you?。
    成功表现：1–2 秒内收到回复 你好，你好吗？（自动识别英文并翻译为中文）。
  • 群聊测试（可选）：将 Bot 添加到一个群组，发送 @myclawdtranslator_bot Bonjour。
    成功表现：Bot 回复 你好，并在群内显示 （来自 @yourname 的翻译）。

🧪 小实验：尝试发送一段中文语音（iOS/Android 均支持），ClawdBot 会自动调用 Whisper tiny 进行本地转写，再翻译成英文；或发送一张含英文的截图，它会调用 PaddleOCR 识别文字后翻译。整个过程不经过任何外部服务器。

4. 模型替换与性能调优

ClawdBot 默认内置了轻量级模型（如 Qwen3-4B-Instruct），适合大多数场景。但如果你追求更高精度、更多语言支持或更强推理能力，可以轻松更换为其他 vLLM 兼容模型。

4.1 修改模型配置（JSON 方式）

模型配置位于 clawdbot.json 的 "models" 字段。我们以替换为 Qwen2.5-7B-Instruct 为例（需提前下载该模型）：

# 进入容器
docker-compose exec gateway sh

# 编辑配置
vi /app/clawdbot.json

将 "models" 部分修改为：

"models": {
  "mode": "merge",
  "providers": {
    "vllm": {
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": "sk-local",
      "api": "openai-responses",
      "models": [
        {
          "id": "Qwen2.5-7B-Instruct",
          "name": "Qwen2.5-7B-Instruct"
        }
      ]
    }
  }
},
"agents": {
  "defaults": {
    "model": {
      "primary": "vllm/Qwen2.5-7B-Instruct"
    }
  }
}

注意："primary" 字段必须与 "models" 中定义的 id 完全一致（包括前缀 vllm/）。

4.2 验证模型是否加载成功

保存配置后，重启服务并检查模型列表：

exit
docker-compose restart gateway
sleep 15
clawdbot models list

你应该能看到新模型出现在列表中：

Model                                      Input      Ctx      Local Auth  Tags
vllm/Qwen2.5-7B-Instruct                   text       32k      yes   yes   default

若只显示旧模型或报错，请检查：

  • 模型是否已实际下载到 ~/.clawdbot/models/ 目录（ClawdBot 不自动下载，需你手动放置）；
  • baseUrl 是否指向正确的 vLLM 服务地址（默认 http://localhost:8000/v1，即容器内 vLLM 服务）；
  • 模型 ID 是否与 Hugging Face 模型卡名称严格一致（区分大小写、连字符）。

4.3 性能与资源平衡建议

不同模型对硬件要求差异巨大。以下是实测经验总结：

模型尺寸CPU 内存需求GPU 显存需求适用场景响应速度（平均）
Qwen3-4B≥ 4GB无要求日常聊天、简单翻译< 1.2 秒
Qwen2.5-7B≥ 6GB≥ 8GB（RTX 3060）复杂逻辑、长文本摘要< 2.5 秒
Qwen2-14B≥ 12GB≥ 16GB（RTX 4090）专业文档、代码生成< 4.0 秒
  • 无 GPU 用户：坚持使用 4B 级别模型，ClawdBot 的 vLLM 优化使其在 CPU 上仍保持可用响应速度；
  • 树莓派用户：4B 模型是唯一推荐选项，实测 15 用户并发无压力；
  • 笔记本用户：7B 模型 + RTX 3050/4060 是性价比之选，兼顾速度与质量。

5. 实用技巧与常见问题速查

部署完成只是开始。以下是你在日常使用中大概率会遇到的问题及解决方案，全部基于真实用户反馈整理，无需翻阅冗长文档。

5.1 “为什么图片翻译没反应？”——OCR 配置检查

ClawdBot 的图片 OCR 功能依赖 PaddleOCR 轻量模型，默认已内置。若上传图片后无任何回复，请按顺序排查：

  1. 确认图片格式：仅支持 JPG、PNG、WEBP；BMP、GIF（动图）不支持；
  2. 确认图片清晰度：文字区域分辨率建议 ≥ 200×200 像素，模糊、反光、倾斜过大会导致识别失败；
  3. 检查日志：执行 docker-compose logs gateway | grep -i ocr，若出现 PaddleOCR not found，说明模型文件损坏，需重新拉取镜像；
  4. 强制重试：在 Telegram 中对该图片重复发送一次，ClawdBot 有缓存机制，首次失败后二次尝试常成功。

5.2 “语音转写结果不准”——Whisper 优化方案

Whisper tiny 模型在安静环境下准确率约 92%，但在嘈杂背景或口音较重时会下降。提升效果的三个免费方法：

  • 前端降噪：使用 Telegram 自带的“语音消息降噪”开关（iOS/Android 设置中开启）；
  • 语速控制：说话时比平时慢 20%，避免连读（如 “what’s up” → “what is up”）；
  • 后处理规则：在 clawdbot.json 的 "agents" → "defaults" 中添加自定义清洗规则：
    "postprocess": {
  "whisper": {
    "removePunctuation": true,
    "normalizeCase": "lower"
  }
}

5.3 “如何让群聊自动翻译所有消息？”——白名单管理

默认 groupPolicy: "allowlist" 是安全策略，但你可以轻松添加群组：

  1. 在 Telegram 群中发送 /start 给 Bot；
  2. Bot 会回复一条含 Group ID 的消息（形如 -1001234567890）；
  3. 将该 ID 添加到 clawdbot.json 的 telegram 配置中：
    "groupAllowlist": ["-1001234567890", "-1009876543210"]
  4. 重启 gateway 服务。

此后，该群内所有消息（无论是否 @Bot）都将被自动检测语言并翻译。

5.4 “如何彻底关闭数据存储？”——阅后即焚模式

ClawdBot 默认不存储消息，但为调试保留了 24 小时内存缓存。如需绝对零存储：

# 进入容器
docker-compose exec gateway sh

# 编辑配置
vi /app/clawdbot.json

在根对象中添加：

"privacy": {
  "ephemeral": true,
  "logRetentionHours": 0
}

重启服务后，所有消息处理完即刻从内存清除，无任何痕迹残留。

6. 总结：你的私人 AI 翻译中枢已就位

回顾整个部署过程，你实际上只做了四件关键的事：
1⃣ 拉起服务：用 docker-compose up -d 启动一个预集成的 AI 运行时；
2⃣ 开通控制台：通过 clawdbot devices approve 建立可信设备连接；
3⃣ 接入 Telegram：填入 Bot Token，配置通道策略，让机器人走进你的聊天窗口；
4⃣ 定制能力：按需更换模型、调整 OCR/Whisper 行为、设置群组白名单。

没有复杂的 Python 环境搭建，没有令人头疼的 CUDA 版本匹配，没有需要反复调试的 API 密钥轮换。ClawdBot 把“AI 助手”的门槛，真正降到了“会用命令行”的水平。

它不是一个玩具，而是一个可信赖的工作伙伴：当你在跨国会议中收到一张满是德文的技术图纸，它能瞬间提取文字并译成中文；当海外客户发来一段 30 秒语音询价，它能在你回复前就准备好双语报价单；当团队群聊因语言混杂而效率低下，它默默成为那个让信息自由流动的隐形桥梁。

技术的价值，从来不在参数有多炫目，而在于它是否真正消除了你生活中的摩擦点。ClawdBot 做到了这一点——而且，它完全属于你。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

# 语音转写
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

我用 NVIDIA SkillSpector 纯静态扫了一遍 GitHub 最火的 agent skills：能挖出多少注入？0 个

avatar 龙虾开发者社区
cover

周榜换血九成，Agent Skills 星数翻倍

avatar 龙虾开发者社区

写给 TypeScript 工程师的 OpenClaw.NET 上手指南：用你熟悉的 TS 思维，跑起一个生产级 AI Agent

读代码层：TS 和 C# 本来就是「远房亲戚」——asyncawait??、接口、泛型、严格空检查，你的心智模型几乎无缝平移。真正要适应的只有两件事：类型是具名而非结构化的（多一句显式声明），以及 NativeAOT 下的「禁反射」约束。写扩展层：你甚至可以不怎么碰 C#——Node.js 插件桥意味着你的 TypeScript 插件就是一等公民，而且能在生产 aot 车道跑。内核给你 .NET

avatar 龙虾开发者社区