ClawdBot 部署指南与功能解析

一、ClawdBot 核心定义

ClawdBot 本质是一款可本地部署的 AI 助手网关工具，核心依托 Gateway 进程实现多维度功能串联，堪称一款 7x24 小时不间断运行的智能化虚拟助手。其核心能力涵盖四大模块：

• 跨平台通信对接：兼容 Telegram、WhatsApp、Discord、iMessage 等主流即时通讯工具；

• 多模型调用适配：支持 Claude、GPT 等在线模型，同时兼容各类本地部署的 AI 模型；

• 系统级操作权限：可执行终端命令、读写本地文件、操控浏览器等基础运维动作；

• 自动化任务管控：具备定时任务调度、流程自动化触发等主动运维能力。

与普通 AI 工具相比，ClawdBot 具备上下文记忆能力、硬件操控权限及主动执行属性。据 Mashable 报道，该工具的火爆曾间接导致 Mac mini 断货，不少用户专门采购小型主机用于本地部署，但从性价比角度，一台月费几十元的云服务器即可满足需求，且无需担心本地设备故障风险。

二、ClawdBot 核心应用场景

完成基础部署后，可实现以下实用功能，大幅提升运维效率：

• 跨端远程操控：通过手机向 Bot 发送指令即可秒获响应，外出时也能远程管理服务器；

• 服务器状态监控：指令触发 htop 命令、Docker 容器检查等操作，结果截图同步至手机；

• 定制化定时推送：例如每日早 7 点自动生成并发送服务器健康报告；

• 代码调试辅助：上传报错信息后，Bot 可直接修改对应文件并优化代码。

进阶玩法需搭配额外 Skills 及第三方集成，社区常见场景包括：

• 邮件智能运维：每 15 分钟巡检收件箱，自动归档垃圾邮件、推送重要邮件摘要，支持模拟用户口吻起草回复；

• 笔记自动化整理：对接 Obsidian 工具，自动更新每日笔记、从会议记录中提取待办事项，生成周度回顾报告；

• 夜间自动化开发：提交 Bug 需求后，Bot 持续执行调试、代码提交、测试流程，次日即可生成 PR；

• 智能家居联动：通过手机指令让 Bot 调节灯光、查询天气、设置闹钟等。

本文聚焦基础部署流程，完成后可实现聊天交互与基础命令执行功能，进阶玩法可后续按需拓展。

三、部署前准备工作

3.1 必备资源清单

所需项目	具体说明
运行设备	云服务器（推荐 Ubuntu 24.04）、Mac mini、闲置电脑、树莓派均可，优先选择境外节点规避网络限制
通讯账号	Telegram 账号（用于创建专属 Bot）
AI 接口	Claude/GPT 官方 API 或兼容格式的中转 API，后续将详细说明配置要点

3.2 设备选择建议

不同设备各有优劣，结合使用场景推荐如下：

• 云服务器（新手首选）：优势在于成本低、容错率高、可 7x24 小时稳定运行，仅需基础 Linux 操作能力；劣势为功能拓展受限于服务器配置。

• Mac mini：优势是性能强劲、功耗较低，支持 iMessage 等 macOS 专属功能；劣势为起步价较高（4000 元以上），高权限部署存在安全隐患。

建议新手先通过 VPS 熟悉部署流程，待操作熟练后再考虑采购专用设备。若使用 Mac mini，务必避免用日常工作设备部署，防止配置失误或密钥泄露导致数据风险。

四、部署安装流程

ClawdBot 提供多种安装方式，按推荐优先级排序如下，本文重点演示手动安装流程，帮助理解底层逻辑，便于故障排查。

4.1 两种安装方式对比

• 一键部署脚本（推荐）：官方提供的自动化命令，可自动处理依赖安装、权限配置等问题，适合快速部署。
  `# Linux / macOS 系统执行
  curl -fsSL https://get.clawd.bot | bash

安装完成后启动引导向导

clawdbot onboard --install-daemon`
该脚本会自动检测系统环境、安装 Node.js 22+ 版本、配置 npm 权限，并全局部署 ClawdBot。

• 手动 npm 安装：适用于已安装 Node.js 22+ 的环境，执行命令 npm install -g clawdbot@latest 即可完成安装。

4.2 手动安装详细步骤

步骤 1：安装 Node.js 22+ 版本

ClawdBot 对 Node.js 版本有严格要求，需手动安装指定版本，避免使用系统自带的旧版本。

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
# 执行安装命令
apt-get install -y nodejs
# 验证版本是否达标
node -v

若输出结果为 v22.x.x 则说明安装成功。

注意事项：切勿直接执行 apt install nodejs 命令，系统默认安装版本通常为 v12 或 v18，会引发兼容性错误。

步骤 2：全局安装 ClawdBot

npm install -g clawdbot@latest
# 安装完成后验证版本
clawdbot --version

权限问题解决：若出现 EACCES 权限报错，需配置 npm 全局目录权限：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

步骤 3：创建 Telegram Bot 并获取 Token

1. 打开 Telegram 客户端，搜索 @BotFather 账号并发起对话；

2. 发送 /newbot 指令，按提示完成两项配置：设置 Bot 显示名称、设置以 bot 结尾的用户名（例如 my_clawd_bot）；

3. 配置完成后，@BotFather 会生成一串 Token（格式如 1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ1234567890），务必妥善保存，后续配置需用到。

步骤 4：AI API 准备（核心避坑点）

API 配置是部署关键环节，支持官方 API 与中转 API 两种方式，需满足对应要求：

• 官方 API 配置：前往 console.anthropic.com 注册账号，创建以 sk-ant- 开头的 API Key，充值适量余额即可使用；

• 中转 API 配置：需满足三项条件——支持 OpenAI 兼容格式、具备工具调用（function calling）能力、无分组使用限制。

实操参考：可采用 CLI Proxy API 开源项目搭建中转通道，本文选用 gemini-3-flash 模型，运行稳定性较好。

步骤 5：配置文件编写

先创建配置目录，再编写 JSON 配置文件，根据 API 类型选择对应模板：

# 创建配置目录
mkdir -p ~/.clawdbot
# 编辑配置文件
nano ~/.clawdbot/clawdbot.json

模板 A：Anthropic 官方 API 配置

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-你的密钥"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5-20261022"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "你的 Bot Token",
      "dmPolicy": "pairing"
    }
  }
}

模板 B：OpenAI 兼容中转 API 配置

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "gemini/gemini-3-flash"
      },
      "elevatedDefault": "full",
      "workspace": "/wangwang",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "gemini": {
        "baseUrl": "https://你的中转站 API/v1",
        "apiKey": "test",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-3-flash",
            "name": "gemini-3-flash"
          }
        ]
      }
    }
  },
  "channels": {
    "telegram": {
      "botToken": "你的 TG Token"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

核心避坑点：

1. api 字段必须填写 openai-completions，填写 openai-chat 会导致启动失败；

2. models 数组不可省略，否则会触发必填项报错，且需与 agents 中的模型名保持一致。

步骤 6：启动与测试

clawdbot gateway --verbose

若终端输出以下两行信息，说明启动成功：

[gateway] listening on ws://127.0.0.1:18789
[telegram] [default] starting provider (@你的 Bot 名字)

步骤 7：账号配对（安全验证）

1. 首次向 Telegram Bot 发送消息，Bot 会回复配对码（格式如 Pairing code: X9MKTQ2P）及用户 ID；

2. 在服务器执行配对命令：clawdbot pairing approve telegram X9MKTQ2P；

3. 配对完成后，仅该 Telegram 账号可与 Bot 交互，同时记录用户 ID，用于后续权限配置。

配对成功后，可直接通过 Telegram 向 Bot 发送指令，例如让其集成 exa 搜索功能，实现个性化拓展。

五、开机自启配置

为避免 SSH 断开后 Bot 停止运行，推荐使用 systemd 配置开机自启，实现故障自动恢复：

cat > /etc/systemd/system/clawdbot.service << 'EOF'
[Unit]
Description=ClawdBot Gateway
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/bin/clawdbot gateway --verbose
Restart=always
RestartSec=5
Environment=HOME=/root

[Install]
WantedBy=multi-user.target
EOF

# 刷新配置并启动服务
systemctl daemon-reload
systemctl enable clawdbot
systemctl start clawdbot

配置完成后，ClawdBot 会随服务器开机自动启动，异常停止后 5 秒内自动重启。

六、日常运维与进阶配置

6.1 常用运维命令

# 查看服务运行状态
systemctl status clawdbot
# 实时查看运行日志
journalctl -u clawdbot -f
# 重启服务
systemctl restart clawdbot
# 健康检查
clawdbot doctor
# 查看全量状态信息
clawdbot status --all

6.2 命令白名单配置

为避免高频命令重复审批，可将常用命令加入白名单，实现自动执行：

# 允许所有 docker 相关命令
clawdbot approvals allowlist add --agent "*" "docker *"
# 允许 systemctl 命令
clawdbot approvals allowlist add --agent "*" "systemctl *"
# 允许执行 /usr/bin 目录下的所有程序
clawdbot approvals allowlist add --agent "*" "/usr/bin/*"
# 查看当前白名单
clawdbot approvals allowlist list

6.3 定时任务配置

依托内置 Cron 功能，可实现定时任务自动化，例如每日早 7 点推送服务器状态简报：

clawdbot cron add --schedule "0 7 * * *" \
  --timezone "Asia/Shanghai" \
  --message "检查服务器状态，生成简报并发送" \
  --deliver telegram \
  --to "你的 TG 用户 ID"

也可将定时任务写入配置文件，便于统一管理：

{
  "cron": {
    "jobs": [
      {
        "id": "daily-report",
        "schedule": {
          "cron": "0 7 * * *",
          "timezone": "Asia/Shanghai"
        },
        "sessionTarget": "isolated",
        "payload": {
          "agentTurn": {
            "message": "检查服务器状态，生成简报并发送"
          }
        },
        "deliver": {
          "channel": "telegram",
          "to": "你的 TG 用户 ID"
        }
      }
    ]
  }
}

七、常见问题排查

• clawdbot: command not found：npm 路径配置异常，执行以下命令修复：
  npm config get prefix echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc source ~/.bashrc

• 端口被占用：默认端口 18789 冲突，先查询占用进程，再更换端口启动：
  lsof -i :18789 # 查询占用进程 clawdbot gateway --port 18790 --verbose # 更换为18790端口启动

• Bot 收消息不回复：按以下顺序排查：① 检查 Gateway 运行状态（clawdbot status）；② 确认账号已配对（clawdbot pairing list telegram）；③ 验证 API 余额；④ 查看日志定位问题（journalctl -u clawdbot -f）。

• all models failed 报错：API 配置错误，需检查：① 密钥正确性；② baseUrl 格式（是否包含 /v1 后缀）；③ 模型 ID 匹配度；④ 执行 clawdbot doctor 进行健康检查。

• 工具调用失败：API 不支持 function calling 功能，更换支持工具调用的 API 即可解决。

八、完整配置示例（开箱即用）

以下配置包含模型降级、权限管控、安全防护等功能，适配多数使用场景：

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-compat/claude-sonnet-4-5-20261022",
        "fallback": ["openai-compat/claude-haiku-3-5-20241022"]
      },
      "elevatedDefault": "full",
      "thinking": "medium"
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "openai-compat": {
        "baseUrl": "https://你的 API 地址/v1",
        "apiKey": "你的密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-sonnet-4-5-20261022",
            "name": "Claude Sonnet 4.5"
          },
          {
            "id": "claude-haiku-3-5-20241022",
            "name": "Claude Haiku 3.5"
          }
        ]
      }
    }
  },
  "tools": {
    "exec": {
      "backgroundMs": 10000,
      "timeoutSec": 1800,
      "cleanupMs": 1800000,
      "notifyOnExit": true
    },
    "elevated": {
      "enabled": true,
      "allowFrom": {
        "telegram": ["你的 TG 用户 ID"]
      }
    },
    "allow": ["exec", "process", "read", "write", "edit", "web_search", "web_fetch", "cron"]
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "你的 Bot Token",
      "dmPolicy": "pairing",
      "allowFrom": ["你的 TG 用户 ID"],
      "groupPolicy": "disabled"
    }
  },
  "cron": {
    "jobs": []
  }
}

配置亮点：① 主模型故障时自动切换至备用模型；② 启用中等深度思考模式提升指令执行精度；③ 禁用群聊响应，仅支持私聊，搭配双重白名单强化安全；④ 开放常用工具权限，平衡功能性与安全性。

九、总结

ClawdBot 部署的核心难点集中在配置文件调试与 API 兼容性适配，多数耗时用于排查格式错误与权限问题。掌握以下关键点可大幅提升部署效率：

1. Node.js 版本严格控制在 22+，避免兼容性故障；

2. 优先选择无限制的 API 服务，规避工具调用限制；

3. 配置文件需注意 api 字段、models 数组等必填项，严格遵循 JSON 格式；

4. 采用 systemd 管理服务，替代 nohup 实现稳定运行；

5. 安全层面需配置命令白名单与访问权限，定期查看运行日志。

ClawdBot 的核心价值在于“可控性”与“自动化”，适合具备基础技术能力的用户用于服务器运维、流程自动化等场景。若仅需基础聊天交互，直接使用 AI 官方平台即可，无需额外部署。