Clawdbot 完整部署和使用教程：从零打造你的专属全能 AI 助理
掌握 Clawdbot 完整部署和使用教程，从零开始搭建你的个人 AI 助手网关。本指南涵盖详细安装、配置、安全策略、生产环境部署及实战案例，助你提升工作效率，实现智能自动化。
第一部分：Clawdbot 是什么？为何选择它？
Clawdbot，顾名思义，它是一个“智能爪子机器人”，能够抓取、连接并执行各种任务。从技术角度看，它是一个开源的、基于 Node.js 构建的 AI 助手网关。它扮演着一个枢纽的角色，将你选择的 AI 大模型（如 Claude、GPT、Gemini 甚至本地模型）与你日常使用的通讯工具（如 Telegram、WhatsApp、Discord）无缝连接起来。这意味着你不再需要频繁切换应用，只需在熟悉的聊天界面中，便能直接调用 AI 的强大能力，并让它与你的本地环境进行深度交互。
1.1 Clawdbot 的核心概念与价值
本地化与隐私保护： Clawdbot 强调本地部署，这意味着你的数据和 AI 交互过程可以更好地掌握在自己手中，降低了对第三方云服务的依赖，增强了隐私安全性。
平台无关性： 无论你是 Windows、Linux 还是 macOS 用户，Clawdbot 都能在相应环境中运行。它支持多种通讯渠道接入，让你的 AI 助手可以活跃在不同的社交或工作平台。
强大的扩展能力： Clawdbot 提供了“技能（Skills）”和“钩子（Hooks）”系统，这就像是 AI 的“应用商店”。通过安装不同的技能，可以赋予 AI 更多特定任务处理能力，例如日历同步、邮件管理、文件操作等。
自动化与控制： 它不仅仅是聊天，更是一个任务执行者。Clawdbot 能够执行系统命令、读写文件、控制浏览器，配合 AI 的理解与决策能力，实现各种复杂的自动化流程。
1.2 为什么我们需要一个本地 AI 网关？
你可能会问，市面上这么多在线 AI 服务，为什么还要费力搭建一个本地网关呢？这主要基于以下几点考量：
数据主权与安全性： 将敏感数据上传到第三方云服务总是有潜在风险。本地部署让你对数据拥有完全控制权，尤其适合处理个人隐私、商业机密或需要高度安全保障的任务。
定制化与深度集成： 在线服务通常提供标准化功能，难以满足个性化需求。Clawdbot 允许你深度定制 AI 模型、接入策略、工具权限，甚至编写自己的技能，真正打造一个“懂你”的助手。
突破功能限制： 许多在线 AI 助手无法直接访问你的本地文件系统或执行本地命令。Clawdbot 作为网关，则能弥补这一空白，让 AI 拥有“手脚”，执行更实际的操作。
应对 API 波动与审查： 有时候，API 访问受限或服务不稳定会影响体验。本地部署可以在一定程度上缓解这些问题，并允许你灵活切换不同的 AI 模型提供商或中转服务。
1.3 Clawdbot 的主要功能与应用场景
Clawdbot 上线后，社区的创意简直收不住。以下是一些激动人心的应用场景：
个人生产力提升：
代码开发与调试： 将报错信息发给它，AI 能直接帮你分析错误、修改代码文件，甚至完成小功能的编写。一位开发者曾用它自动调试并提交代码，早上起来发现 Bug 已修复，省去了熬夜的烦恼。
信息收集与整理： 每天早上定时为你收集最新的 AI 行业资讯，整理成简报发送到你的 Telegram；或监控特定话题，实时推送相关讨论和动态。
邮件自动化： 每隔15分钟检查收件箱，自动将垃圾邮件归档，提取重要邮件摘要并推送到手机，甚至能用你的口吻起草回复。
远程控制与自动化运维：
服务器管理： 手机上给 Bot 发消息，让它运行 htop 查看服务器负载，或者检查 Docker 容器状态，并将截图发给你。即使出门在外，也能随时掌握服务器动态。
批量操作： 自动化重复性工作，比如文件整理、数据录入，或者在特定条件下触发某个脚本。
智能家居： 结合定制技能，用聊天命令控制家里的智能设备，例如“帮我调暗客厅灯光”、“查询今天天气”。
第二部分：部署前置条件与安全考量
在开始 Clawdbot 的部署之前，充分的准备工作至关重要，特别是对硬件、软件环境的理解和对安全风险的认识。Clawdbot 功能强大，能够深入系统操作，因此安全考量绝不能掉以轻心。
2.1 硬件要求
虽然 Clawdbot 可以运行在各种设备上，但为了获得良好的体验，以下是推荐的最低和理想硬件配置：
网络： 稳定的互联网连接是必须的。由于部分依赖项或 AI 模型 API 需要访问国外服务，科学上网环境可能会有所帮助。
存储： 至少 10GB 可用空间。这用于存放 Clawdbot 自身的依赖、AI 模型文件（如果是本地部署模型，如 Ollama）以及长期的数据持久化。推荐 20GB+，以备不时之需。
内存（RAM）： 基础运行需要 8GB，但如果你计划本地运行较大的 AI 模型，或者同时处理大量并发任务，强烈推荐 16GB 或更高内存。内存不足是导致安装失败或运行缓慢的常见原因。
CPU： 至少 4 核心。如果需要运行本地 AI 模型或处理复杂的计算任务，推荐 8 核心以上。
2.2 软件环境
Clawdbot 主要基于 Node.js 构建，因此 Node.js 环境是核心要求。
操作系统：
Linux： 推荐 Ubuntu 20.04+，这也是大多数服务器环境的首选。
macOS： Intel 和 Apple Silicon 芯片的 Mac 均支持。
Windows： 必须在 WSL2 (Windows Subsystem for Linux 2) 环境下运行，不推荐原生 Windows 环境，因为 WSL2 提供了更稳定的 Linux 兼容性。
Node.js： Clawdbot 要求 Node.js 22.0.0 或更高版本。这是非常关键的一点，很多新手在安装时遇到的问题都与 Node.js 版本过低有关。我们将使用 NVM (Node Version Manager) 来管理 Node.js 版本，确保环境纯净。
包管理器： npm 或 pnpm。推荐 pnpm，它在安装速度和磁盘空间占用方面通常表现更好。
2.3 重要安全警告与隔离部署建议
Clawdbot 被设计为“完全奔放版本的 Claude Code”，它能够打破软件壁垒，甚至拥有本地电脑的完整操作权限。这种强大能力同时也带来了潜在的安全风险。想象一下，如果一个恶意指令被执行，可能会导致数据泄露或系统损坏。因此，部署环境的安全性是重中之重。
强烈建议在以下隔离环境中部署 Clawdbot：
Docker 容器中： 这是最推荐的生产环境部署方式。Docker 提供了良好的沙箱机制，将 Clawdbot 及其操作限制在一个独立的容器内，即使出现问题也不会影响宿主机系统。
专用的低配设备： 例如一台二手的 Mac mini、树莓派或旧电脑。让它专门运行 Clawdbot，即使发生安全事件，风险也局限于这台设备。
独立的云服务器 (VPS) 或虚拟机 (VMware, VirtualBox, Parallels 等)： 将 Clawdbot 部署在一个与你日常工作环境完全隔离的远程服务器或虚拟机中。这是我在实践中常用的方式，便宜且易于管理。
切记： 生产环境必须配置严格的安全策略和权限边界。永远不要在你日常使用的、存储重要数据的电脑上直接运行一个拥有高度系统权限的 AI 助手，除非你完全理解并能控制所有潜在风险。
2.4 API Key 准备：官方与中转站
Clawdbot 的核心是 AI 模型。你需要准备相应的 API Key 来连接这些模型。
官方 API Key：
Anthropic (Claude)： 前往 Anthropic Console 注册并获取。
OpenAI (GPT)： 前往 OpenAI Platform 注册并获取。
Google (Gemini)： 前往 Google AI Studio 获取。
注意： 官方 API 通常需要绑定信用卡并充值，并且可能存在地域访问限制。
中转站 API Key：
许多第三方服务提供 AI 模型的中转 API，它们通常解决了官方 API 的访问限制问题，或者提供了更灵活的计费方式。
选择中转站时请注意：
必须支持工具调用 (Function Calling)： 这是 Clawdbot 执行命令的核心能力。
API 兼容性： 有些中转站兼容 OpenAI 格式，有些则直接支持 Anthropic 格式。配置时需留意 api 字段的设置。
稳定性与安全性： 选择信誉良好、稳定的中转服务。
我的个人建议： 新手可以先从官方 API 小额充值开始体验。如果遇到访问问题或寻求更经济的选择，再考虑中转站服务。
第三部分：Clawdbot 完整安装指南
现在，我们准备开始 Clawdbot 的安装过程。为了确保每一步都清晰明了，我们将详细介绍 Node.js 的安装与管理，以及 Clawdbot 命令行工具的两种安装方式。
3.1 第一步：安装 Node.js 22+ (推荐使用 NVM 管理)
Clawdbot 严格要求 Node.js 22.0.0 或更高版本。直接使用操作系统的包管理器安装的 Node.js 版本可能过旧，导致后续安装失败。NVM (Node Version Manager) 是管理多个 Node.js 版本的利器。
安装 NVM： 打开你的终端 (Terminal) 或 WSL2 命令行工具，执行以下命令：
国内用户推荐使用 gitee 镜像源，速度更快
curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash国外用户或没有网络问题的用户
# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash安装完成后，关闭并重新打开终端，或者执行 source ~/.bashrc (Linux) / source ~/.zshrc (macOS) 来加载 NVM 环境变量。
安装 Node.js 22：
nvm install 22 # 安装 Node.js 22 最新版本
nvm use 22 # 切换到 Node.js 22
nvm alias default 22 # 设置 Node.js 22 为默认版本，每次启动终端自动使用验证 Node.js 版本：
node -v # 应该显示 v22.x.x
npm -v # 检查 npm 版本【踩坑提示】 如果 NVM 安装后 nvm 命令找不到，可能是环境变量未正确加载。尝试重启终端或手动 source 对应的配置文件 (.bashrc, .zshrc)。
3.2 第二步：Clawdbot CLI 安装与验证
Clawdbot 提供了两种主要的安装方式：官方一键安装脚本和全局包管理器安装。
3.2.1 方式一：官方一键安装脚本 (推荐新手)
这是最快、最简单的安装方式，脚本会自动处理 Node.js 版本检测、依赖安装和 PATH 配置。
# macOS 或 Linux
curl -fsSL https://clawd.bot/install.sh | bash
# Windows PowerShell (在 WSL2 内无需此命令，直接使用 Linux 命令)
# iwr -useb https://clawd.bot/install.ps1 | iex注意事项：
安装过程可能需要几分钟，请耐心等待。
确保网络连接稳定，部分依赖可能需要访问国外服务。
脚本可能需要 sudo 权限 (macOS/Linux) 或管理员权限 (Windows)。
如果你的服务器内存较小 (如 1GB-2GB)，可能会在安装过程中遇到 OOM (Out Of Memory) 错误。建议提前配置 Swap 交换空间，例如：
sudo fallocate -l 4G /swapfile # 创建一个 4GB 的 swap 文件
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab # 设置开机自动挂载3.2.2 方式二：全局包管理器安装 (推荐开发者)
如果你已经有 Node.js 22+ 环境，或者更喜欢手动控制安装过程，可以使用 npm 或 pnpm。
使用 npm
npm install -g clawdbot@latest或使用 pnpm (推荐，更快的安装速度)
pnpm add -g clawdbot@latest【踩坑提示】 如果 npm install -g clawdbot 出现 EACCES 权限错误，通常是 npm 全局安装目录的权限问题。解决方法如下：
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc # 如果是 zsh 则改为 ~/.zshrc
source ~/.bashrc # 重新加载环境变量然后再次尝试 npm install -g clawdbot@latest。
3.3 第三步：验证 Clawdbot 安装与快速启动
安装完成后，我们需要验证 Clawdbot CLI 是否正常运行。
检查版本和帮助信息：
clawdbot --help
clawdbot --version如果能看到版本号和帮助信息，说明 CLI 安装成功。
启动快速设置模式 (QuickStart)： 第一次使用 Clawdbot，可以启动快速设置向导，它会引导你完成最基础的配置。
clawdbot onboard --flow quickstart向导会一步步提示你：
接受风险提示： 输入 yes 确认你理解 Clawdbot 的强大权限和潜在风险。
选择 AI 模型： 初学者推荐选择 Claude（如果能访问），或根据你的 API 密钥选择 OpenAI 或其他兼容模型。
输入 API Key： 根据所选模型，粘贴对应的 API Key。
连接通讯渠道： 推荐先从 WhatsApp 或 Telegram 开始，它们配置相对简单。WhatsApp 仅需扫码，Telegram 则需要 Bot Token。
安装技能和 Hooks： 新手建议选择默认配置，后续再根据需求安装。
开始使用与测试： 向导完成后，你将获得一个本地聊天界面访问地址（通常是 http://127.0.0.1:18789/）和已连接的聊天平台联系人。 在连接的通讯平台（如 WhatsApp 或 Telegram）中找到你的 Clawdbot 助手，发送一条简单的消息进行测试：
hello 帮我做一下自我介绍
如果 Clawdbot 成功回复，恭喜你，你的专属 AI 助手已初步上线！
第四部分：核心配置详解：网关、模型与渠道
Clawdbot 的强大之处在于其高度可定制性。深入理解其配置文件是掌握 Clawdbot 的关键。我们将重点讲解网关、AI 模型和通讯渠道的配置细节。
4.1 Clawdbot 网关配置 (gateway.yaml 或 clawdbot.json) 详解
Clawdbot 的核心配置文件通常是 ~/.config/Clawdbot/gateway.yaml (Linux/WSL2) 或 ~/Library/Application Support/Clawdbot/gateway.yaml (macOS)，或者在某些情况下，你可以使用 ~/.clawdbot/clawdbot.json。推荐使用 clawdbot.json 进行统一配置，它提供更全面的选项。
配置文件位置：
Linux/WSL2: ~/.config/Clawdbot/gateway.yaml 或 ~/.clawdbot/clawdbot.json
macOS: ~/Library/Application Support/Clawdbot/gateway.yaml 或 ~/.clawdbot/clawdbot.json 如果 clawdbot.json 文件不存在，可以手动创建 mkdir -p ~/.clawdbot 然后 nano ~/.clawdbot/clawdbot.json 进行编辑。
核心配置项示例 (JSON 格式)：
{
"gateway": {
"port": 18789, // 服务端口
"host": "127.0.0.1", // 绑定地址，"0.0.0.0" 允许外部访问
"mode": "local", // 网关模式
"auth": {
"mode": "token" // 认证模式，token 或 none
}
},
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-5", // 默认主模型
"fallback": ["openai/gpt-3.5-turbo"] // 备用模型
},
"elevatedDefault": "full", // 默认提升权限
"thinking": "medium", // AI思考深度
"workspace": "/data/clawdbot-workspace" // AI工作空间目录
}
},
"security": {
"requirePairing": true, // DM 需要配对
"allowedUsers": [], // 白名单用户，例如 ["telegram:user123456"]
"adminUsers": [] // 管理员用户
},
"channels": {
// 渠道配置将在 4.3 节详细介绍
},
"models": {
// 模型配置将在 4.2 节详细介绍
},
"tools": {
// 工具权限配置将在 第五部分 详细介绍
},
"cron": {
// 定时任务配置将在 第五部分 详细介绍
}
}gateway.port 和 gateway.host：定义 Clawdbot Web UI 和 API 服务监听的地址和端口。如果希望外部网络能访问你的 Clawdbot，请将 host 设置为 "0.0.0.0"，但这会增加安全风险，请务必做好防火墙设置。
agents.defaults.model.primary：指定你的默认 AI 模型。
agents.defaults.workspace：AI 在执行文件操作时的工作目录，确保这个目录存在且有相应权限。
4.2 AI 模型配置：官方与中转站 API 的灵活接入
Clawdbot 支持接入多种 AI 模型，无论是官方 API 还是第三方中转站。核心在于 models 部分的配置。
4.2.1 Anthropic 官方 API 配置示例
如果你直接使用 Claude 官方 API Key：
{
"models": {
"providers": {
"anthropic": {
"baseUrl": "https://api.anthropic.com",
"apiKey": "${ANTHROPIC_API_KEY}", // 推荐使用环境变量
"api": "anthropic-messages",
"models": [
{"id": "claude-opus-20240229", "name": "Claude Opus"},
{"id": "claude-sonnet-20240229", "name": "Claude Sonnet"},
{"id": "claude-haiku-20240307", "name": "Claude Haiku"}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-20240229"
}
}
}
}注意： 将 "${ANTHROPIC_API_KEY}" 替换为你的实际 API Key，或者更好地，在启动 Clawdbot 的环境中设置环境变量 export ANTHROPIC_API_KEY="sk-ant-..."。
4.2.2 OpenAI 兼容中转站 API 配置示例
许多中转站提供兼容 OpenAI API 接口的服务，这让你可以接入 GPT、Gemini 等模型。以下是一个集成 gemini-3-flash 模型的例子（参考自 SERP 结果）：
{
"models": {
"mode": "merge",
"providers": {
"my-openai-compat": { // 自定义一个 provider 名称
"baseUrl": "https://你的中转站API地址/v1", // 注意路径，有些中转站需要 /v1 后缀
"apiKey": "你的API密钥",
"api": "openai-completions", // 关键：指定为 openai-completions 兼容模式
"models": [
{"id": "gemini/gemini-3-flash", "name": "Gemini 3 Flash"},
{"id": "gpt-4o", "name": "GPT-4o"} // 也可以添加其他模型
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "my-openai-compat/gemini/gemini-3-flash" // 引用你的自定义 provider
}
}
}
}【踩坑提示】
baseUrl：务必核对中转站提供的 API 地址，确保 /v1 或 /v1beta 后缀正确。
api 字段：openai-completions 是关键，不要误写成 openai-chat。
models 数组：必须包含，即使只有一个模型也要列出来。
primary 模型路径：格式是 provider_name/model_id，例如 my-openai-compat/gemini/gemini-3-flash。
4.2.3 Claude Code 中转 API 配置示例 (带 User-Agent)
某些特殊的中转站可能需要特定的 User-Agent 头部来验证请求。Clawdbot 允许你在模型配置中添加自定义头部。
{
"models": {
"providers": {
"code-claude-opus": {
"baseUrl": "https://code.claude-opus.top/api", // 中转站地址
"apiKey": "cr_你的API密钥",
"api": "anthropic-messages",
"models": [
{
"id": "claude-opus-4-20250514",
"name": "Claude Opus 4",
"headers": { // 关键：在这里添加 User-Agent
"User-Agent": "Claude-Code/1.0.0"
}
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "code-claude-opus/claude-opus-4-20250514"
}
}
}
}此配置允许你针对特定模型发送自定义 HTTP 头部，以满足中转站的特殊验证要求。
4.3 通讯渠道接入配置
Clawdbot 支持 Telegram、WhatsApp、Discord 等多种通讯平台，让你的 AI 助手触手可及。
4.3.1 Telegram 渠道 (推荐入门)
Telegram 机器人功能强大，配置相对直接。
创建 Bot Token：
在 Telegram 中搜索 @BotFather。
向 @BotFather 发送 /newbot 命令。
按照提示设置你的 Bot 名称（显示名称）和用户名（必须以 bot 结尾，如 my_clawdbot_assistant）。
成功后，@BotFather 会给你一串类似 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 的 Bot Token。务必妥善保管好这个 Token。
配置 Clawdbot 接入 Telegram： 在 clawdbot.json 的 channels 部分添加：
"channels": {
"telegram": {
"enabled": true,
"botToken": "你的Telegram Bot Token", // 替换为你在 @BotFather 获取的 Token
"dmPolicy": "pairing", // 私聊需要配对
"groupPolicy": "disabled", // 默认不进入群聊，可改为 "allowlist" 或 "all"
"requireMention": true // 在群聊中是否需要 @Bot 才能响应
}
}或者使用 CLI 命令：
clawdbot config set channels.telegram.enabled true
clawdbot config set channels.telegram.botToken "你的Telegram Bot Token"
clawdbot config set channels.telegram.dmPolicy pairing
# 更多配置...
clawdbot gateway restart # 重启网关使配置生效验证连接与配对：
在 Telegram 中搜索你的 Bot 用户名。
向 Bot 发送任何消息，它会回复一个配对码 (Pairing code: XXXXXXXX) 和你的 Telegram User ID。
在服务器终端执行：clawdbot pairing approve telegram 你的配对码。
配对成功后，你的 Telegram 账号就能与 Clawdbot 正常对话了。你可以将你的 Telegram User ID 添加到 security.allowedUsers 白名单中，以增强安全性。
4.3.2 WhatsApp 渠道 (生产推荐，配置最简单)
WhatsApp 渠道配置相对简单，尤其适合作为个人助手。
登录 WhatsApp：
clawdbot channels login whatsapp执行此命令后，终端会显示一个二维码。用你的手机 WhatsApp 扫描这个二维码，即可完成登录连接。
检查连接状态：
clawdbot channels status whatsapp如果显示 connected，说明连接成功。
4.3.3 Discord 渠道
Discord 渠道更适合团队协作或社区使用。
创建 Discord 应用和 Bot：
前往 Discord Developer Portal 创建一个新的应用。
在应用页面左侧菜单中选择 Bot，点击 Add Bot。
复制你的 Bot Token。
在 OAuth2 → URL Generator 中，勾选 bot 作用域，并选择机器人所需的权限（例如 Send Messages, Read Message History 等）。生成邀请链接，邀请机器人加入你的服务器。
配置 Clawdbot 接入 Discord：
clawdbot channels login discord
# 按提示输入你的 Discord Bot Token 和服务器邀请链接
4.4 启动与验证网关
配置完成后，保存文件并重启 Clawdbot 网关。
clawdbot gateway restart # 推荐使用此命令重启
# 或者：
# clawdbot gateway --verbose # 前台启动，便于调试，Ctrl+C 关闭检查网关状态：
clawdbot gateway status # 查看网关是否正在运行
clawdbot status # 查看所有组件的健康状态
clawdbot health # 运行更详细的健康检查访问控制台： 在浏览器中打开 http://127.0.0.1:18789/ (如果 host 是 127.0.0.1)，你将看到 Clawdbot 的 Web 控制面板。如果配置了 Token 认证，还需要在 URL 后添加 ?token=your-token。
第五部分：高级功能：安全策略、自动化与技能扩展
Clawdbot 不仅易于部署，更在安全性和功能扩展方面提供了丰富的选项。本节将深入探讨这些高级配置，帮助你打造一个既强大又安全的 AI 助手。
5.1 安全策略精讲
安全是部署 Clawdbot 最核心的考量之一。Clawdbot 提供多层安全机制来保护你的系统。
5.1.1 DM 配对机制 (默认启用)
为了防止陌生人滥用你的 AI 助手，Clawdbot 默认启用了 DM (Direct Message) 配对机制。当有新用户首次给你的 Bot 发消息时，Bot 不会直接回复，而是发送一个配对码。只有 Bot 拥有者在服务器上批准配对后，该用户才能与 Bot 交互。
查看待配对请求：
clawdbot pairing list telegram这会显示所有等待批准的 Telegram 用户及其配对码。
批准配对：
clawdbot pairing approve telegram <配对码>拒绝配对：
clawdbot pairing deny telegram <配对码>专家提示： 批准配对后，建议将该用户的 ID 添加到 security.allowedUsers 白名单中，以提供更明确的权限控制。
5.1.2 工具权限控制
Clawdbot 的核心能力在于通过“工具”执行命令，例如 exec (执行 shell 命令), read (读取文件), write (写入文件), browser (控制浏览器) 等。这些工具的权限必须严格管理。
在 clawdbot.json (或 gateway.yaml) 的 tools 部分进行配置：
"tools": {
// 禁用高风险工具，例如 "exec" (执行任意命令) 和 "browser" (控制浏览器)
"deny": ["exec", "browser"],
// 仅允许特定工具，优先级高于 deny
"allow": ["web_fetch", "read", "write"],
// elevated 权限允许用户手动批准高风险命令
"elevated": {
"enabled": true,
"allowFrom": {
"telegram": ["你的TG用户ID"] // 只有这些用户可以请求 elevated 权限
}
},
// 按 provider 限制工具使用
"providers": {
"openai": ["web_fetch", "read"], // OpenAI 模型只能使用 web_fetch 和 read
"local": ["exec", "browser"] // 本地模型可以使用 exec 和 browser
}
}我的个人建议： 在非生产环境中可以尝试 exec 工具，但生产环境或敏感数据环境，强烈建议禁用 exec 和 browser 等高风险工具，除非你完全明白其风险并有能力控制。
5.1.3 用户权限管理 (白名单与管理员)
通过 security 配置项，你可以定义哪些用户可以与 Bot 交互，哪些用户拥有管理员权限。
"security": {
"requirePairing": true,
"allowedUsers": [ // 白名单用户，优先级最高，可以绕过配对策略
"telegram:你的TG用户ID",
"whatsapp:+86138xxxxxxxx"
],
"adminUsers": [ // 管理员用户拥有更多权限，例如可以修改配置、管理其他用户
"telegram:你的TG用户ID"
]
}提示： 用户 ID 的格式为 channel_name:user_id，例如 telegram:123456789。
5.2 生产环境部署：后台服务与远程访问
为了让 Clawdbot 7x24 小时稳定运行，并能从外部网络访问，我们需要配置后台服务和远程访问。
5.2.1 后台服务配置 (Systemd / Launchd)
clawdbot onboard --install-daemon 命令可以帮助你自动安装后台服务。
Linux (systemd)： Systemd 是 Linux 系统中管理服务的标准方式。
# 安装 systemd 服务 (向导会自动处理)
# clawdbot gateway install --service-type systemd
# 启动并启用服务 (确保开机自启)
sudo systemctl start clawdbot-gateway
sudo systemctl enable clawdbot-gateway
# 查看服务状态和日志
sudo systemctl status clawdbot-gateway
journalctl -u clawdbot-gateway -f # 实时查看日志macOS (launchd)： launchd 是 macOS 的服务管理系统。
# 向导会自动创建 launchd 服务
# clawdbot gateway install --service-type launchd
# 启动服务
launchctl load ~/Library/LaunchAgents/com.clawdbot.gateway.plist
# 查看状态
launchctl list | grep clawdbot
5.2.2 远程访问方案
默认情况下，Clawdbot 网关绑定在 127.0.0.1 (localhost)，外部无法直接访问。
SSH 隧道 (推荐临时或调试使用)： 在本地机器上建立一个 SSH 隧道，将远程服务器的端口映射到本地。
ssh -N -L 18789:127.0.0.1:18789 user@remote-server然后，你可以在本地浏览器访问 http://127.0.0.1:18789/，实际上访问的是远程服务器上的 Clawdbot。
Tailscale / ZeroTier (长期推荐，安全简便)： 这些工具创建了一个虚拟私有网络 (VPN)，让你在任何设备上都能安全地访问你的 Clawdbot，就像它们在同一个局域网中一样。
在服务器上安装 Tailscale： (请参考 Tailscale 官方文档)
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up # 连接到你的 Tailscale 网络配置网关监听所有接口： 在 clawdbot.json 中将 gateway.host 设置为 "0.0.0.0"，并确保防火墙只允许 Tailscale 网络的流量通过。
专家提示： Tailscale 是一个非常优雅的解决方案，它省去了复杂的端口转发和公网暴露风险，强烈推荐长期使用。
5.3 定时任务 (Cron 功能配置)
Clawdbot 内置了强大的 Cron 功能，可以让你轻松设置定时任务，实现各种自动化。
在 clawdbot.json 的 cron 部分添加：
"cron": {
"jobs": [
{
"id": "daily-server-report",
"schedule": {
"cron": "0 7 * * *", // 每天早上7点
"timezone": "Asia/Shanghai" // 指定时区
},
"sessionTarget": "isolated", // 独立会话运行任务
"payload": {
"agentTurn": {
"message": "检查服务器状态，生成一份简报，包括CPU、内存、磁盘使用情况。"
}
},
"deliver": {
"channel": "telegram",
"to": "你的TG用户ID" // 将简报发送到你的 Telegram
}
}
]
}命令行添加定时任务：
clawdbot cron add --schedule "0 7 * * *" \
--timezone "Asia/Shanghai" \
--message "检查服务器状态，给我发个简报" \
--deliver telegram \
--to "你的TG用户ID"5.4 技能与 Hooks 生态 (AI 的“小程序”)
Clawdbot 支持 Claude Skill 和 Hooks 系统，这些是为 AI 扩展功能的“小程序”。你可以安装它们来让 AI 拥有更多专业能力。
查看可用技能：
clawdbot skills list安装特定技能： 例如，安装一个日历同步技能或邮件管理器。
clawdbot skills install calendar-sync
clawdbot skills install email-organizer配置 Hooks： Hooks 允许你在特定事件发生时触发自定义操作。
clawdbot hooks configure通过这些扩展，Clawdbot 的能力边界可以无限延伸，成为真正意义上的全能助手。
第六部分：常见问题排查与优化
在部署和使用 Clawdbot 的过程中，你可能会遇到各种问题。本节将总结常见问题及其解决方案，并提供一些优化建议，帮助你顺利排障并提升使用体验。
6.1 安装问题
问题1：npm install -g clawdbot 权限不足 (EACCES 错误)
原因： npm 尝试将包安装到全局目录，但当前用户没有写入权限。
解决方案：
使用 NVM (Node Version Manager) 管理 Node.js 版本，NVM 会将全局包安装到用户目录，避免权限问题。
如果已安装 NVM 但仍有问题，或者不想用 NVM，请按照本教程第三部分 3.2.2 节中的 mkdir -p ~/.npm-global 方案，将 npm 全局路径修改为用户目录。
问题2：Node.js 版本过低
原因： Clawdbot 要求 Node.js 22.0.0 或更高版本，而系统自带或通过 apt install nodejs 安装的版本可能过旧。
解决方案： 使用 NVM (参考本教程第三部分 3.1 节) 安装并切换到 Node.js 22 版本。这是最可靠的方法。
问题3：安装脚本执行失败或卡住 (特别是网络问题或内存不足)
原因：
网络连接不稳定，导致依赖包下载失败。
服务器内存 (RAM) 不足，尤其是在编译某些依赖时。
解决方案：
网络问题： 确保服务器网络稳定，部分海外依赖可能需要科学上网环境。尝试更换下载源或等待网络状况改善。
内存不足 (OOM)： 检查服务器内存，如果小于 4GB 且没有 Swap，很可能会失败。按照本教程第三部分 3.2.1 节的说明，增加 Swap 交换空间。通常 4GB 或 8GB 的 Swap 文件可以有效缓解内存压力。
6.2 网关与渠道问题
问题1：端口被占用 (Error: listen EADDRINUSE)
原因： Clawdbot 默认端口 18789 已被其他进程占用。
解决方案：
查找占用端口的进程：
Linux/macOS: sudo lsof -i:18789
Windows (WSL2 内同样用 Linux 命令): netstat -ano | findstr 18789 (在原生 Windows CMD/PowerShell)
修改 Clawdbot 端口： 在 clawdbot.json 或 gateway.yaml 中修改 gateway.port 为其他可用端口 (如 18790)，然后重启 Clawdbot 网关。
终止占用进程： 如果确认该进程不重要，可以使用 sudo kill
问题2：Bot 收到消息但不回复
原因： 常见的有 API 密钥错误、模型额度耗尽、渠道未配对、网络不通、配置文件错误。
解决方案：
检查 Clawdbot 日志： journalctl -u clawdbot-gateway -f (Linux) 或 clawdbot logs --follow，查看是否有错误信息。
检查 API 额度： 登录你的 AI 模型提供商 (Anthropic, OpenAI 等) 平台，查看 API 余额是否充足。
检查配对状态： 对于 Telegram/WhatsApp，确保已完成配对 (clawdbot pairing list telegram 查看)。
检查网络连接： 尝试在服务器上 ping 或 curl 你的 AI 模型 API 地址，确认网络畅通。例如：curl -I https://api.anthropic.com。
重新登录渠道： 尝试登出再重新登录渠道，例如：clawdbot channels logout telegram 后再 clawdbot channels login telegram。
问题3：all models failed 或 AI 模型响应缓慢
原因：
AI 模型配置错误 (模型 ID、baseUrl、apiKey、api 类型)。
API 不支持工具调用 (Function Calling)，这会导致 AI 无法执行命令。
AI 模型本身响应速度慢或网络延迟。
服务器资源 (CPU/内存) 不足。
解决方案：
运行健康检查： clawdbot doctor 可以快速诊断常见配置问题。
核对模型配置： 仔细检查 clawdbot.json 中 models.providers 和 agents.defaults.model.primary 的配置，特别是 baseUrl、apiKey、api 字段以及模型 ID 是否与中转站要求一致。
确认工具调用支持： 如果你使用的是第三方中转站，请确认其支持工具调用。这是 Clawdbot 执行命令的关键。
优化模型选择： 考虑使用响应更快的模型 (如 Haiku, Gemini Flash) 或部署本地模型 (如 Ollama)。
监控资源： 使用 top -p $(pgrep clawdbot) 或 htop 实时查看 Clawdbot 进程的 CPU 和内存使用情况。如果资源长期占用过高，可能需要升级硬件或优化配置。
6.3 性能优化建议
选择合适的 AI 模型： 对于日常对话和轻量任务，使用更轻量、响应速度更快的模型（如 Claude Haiku, Gemini Flash, GPT-3.5 Turbo）可以显著提升体验并降低成本。
本地模型部署： 如果有足够的硬件资源，可以考虑使用 Ollama 等工具在本地部署开源大模型。这不仅能提供更快的响应，还能实现真正的离线使用，但对硬件要求较高。
优化 thinking 深度： 在 agents.defaults.thinking 配置中，可以调整 AI 的思考深度。"low" 会更快但可能不够“聪明”，"high" 会更深入思考但会增加延迟和成本。根据你的需求进行调整。
合理设置 maxConcurrent： 在 agents.defaults.maxConcurrent 中限制并发执行任务的数量，避免资源耗尽。
日志管理： 适当调整日志级别 (logging.level)，减少不必要的日志输出，可以降低磁盘 I/O 负担。配置日志轮转 (logging.rotation) 以防止日志文件过大。
通过仔细排查这些常见问题并进行优化，你的 Clawdbot 助手将能够更加稳定、高效地运行，成为你数字生活中不可或缺的一部分。
第七部分：实战案例与个人经验分享
部署 Clawdbot 并非终点，而是开启无限可能的新起点。以下是我个人在实践中积累的一些经验，以及社区中令人惊叹的实战用例，希望能给你带来启发。
7.1 案例1：我的私人代码调试与优化助手
作为一名开发者，我经常遇到代码 Bug 或需要优化现有逻辑。传统的做法是手动排查、搜索资料。但自从我部署了 Clawdbot 并接入了支持工具调用的 GPT-4o 模型后，我的工作流程发生了质的变化。
个人经历： 有一次，我的一个 Python 脚本在特定环境下总是报错，日志信息很长且难以定位。我直接将报错信息粘贴到 Telegram Bot 中，并附加了一句：“我的 Python 脚本有这个问题，帮我看看是哪里的问题，并提出修改建议。” Clawdbot 不仅迅速分析了日志，指出了可能的依赖版本冲突，甚至在我的允许下，直接在 /data/clawdbot-workspace 目录下创建了一个测试文件，编写了一段模拟代码进行验证。 在几次迭代沟通后，它直接给我提供了修改后的代码片段，并解释了每个改动的原因。我只需复制粘贴，问题迎刃而解。更让我惊喜的是，当我问它“能否帮我优化一下这个函数的性能？”时，它能结合我的代码，提出使用 functools.lru_cache 进行结果缓存的建议，并直接修改了文件，省去了我手动操作的麻烦。
这个案例让我深刻体会到，Clawdbot 不仅仅是提供答案，它真正具备了“动手”解决问题的能力，将 AI 的智能与系统操作权限完美结合。
7.2 案例2：企业级信息聚合与简报
一个朋友的公司内部团队通过 Clawdbot 实现了一个高效的信息聚合与简报系统。
社区用例： 他们将 Clawdbot 部署在一个独立的 VPS 上，并将其接入到内部的 Slack 频道。Clawdbot 配置了多个“技能”：
新闻抓取技能： 每天定时从指定科技媒体、行业报告网站抓取最新的 AI、云计算、大数据相关资讯。
内部文档摘要技能： 定期扫描指定 SharePoint 文件夹中的最新文档，提取核心内容。
会议纪要整理技能： 接入日历，在会议结束后自动获取会议录音转录文本，生成结构化的会议纪要和待办事项。
每天早上 8 点，Clawdbot 会自动生成一份综合简报，发送到 Slack 的“每日洞察”频道。这份简报不仅包含行业新闻摘要，还有内部最新进展的快速概览，大大节省了团队成员获取信息的时间，提升了决策效率。团队成员甚至可以直接在 Slack 中向 Clawdbot 提问，获取更详细的报告或数据分析。
7.3 案例3：智能家居控制与日程管理
一位海外用户将 Clawdbot 变成了一个真正的“智能管家”。
社区用例： 他家里的智能家居系统（如 Home Assistant）与 Clawdbot 打通。通过 WhatsApp 消息，他可以：
“Clawdbot，帮我把客厅灯光调到 50%。”
“Clawdbot，查一下今天下午有没有降雨的可能？”
“Clawdbot，提醒我明天早上 8 点给妈妈打电话。”
Clawdbot 还能结合其 Cron 定时任务功能，实现更复杂的自动化：
每天晚上 10 点，自动检查所有门窗是否关闭，如果未关闭则发送提醒。
根据天气预报，早上自动调节卧室空调温度。
定期同步他的 Google Calendar，并提前一天通过 WhatsApp 提醒他重要的日程安排。
这些案例清晰地展示了 Clawdbot 强大的集成能力和自动化潜力，它不再仅仅是一个技术玩具，而是一个能切实提升生活质量和工作效率的生产力工具。
7.4 提升生产力的秘诀：如何最大化 Clawdbot 的价值
从简单任务开始： 不要一开始就尝试过于复杂的自动化。从简单的信息查询、文本生成、文件操作开始，逐步熟悉 Clawdbot 的能力边界。
善用工具与技能： 定期查看 Clawdbot 的工具列表 (clawdbot tools list) 和技能市场 (clawdbot skills list)。很多你想要的功能可能已经有现成的工具或技能支持。
精确的提示词 (Prompt Engineering)： AI 的表现取决于你给出的指令。学习如何编写清晰、具体、有上下文的提示词，能让 Clawdbot 更准确地理解你的意图。
安全先行： 再次强调，始终将安全放在首位。严格控制工具权限、配置白名单用户、定期审查日志。
持续学习与社区交流： Clawdbot 是一个活跃的开源项目，社区里总有新的玩法和解决方案。积极参与社区讨论，学习他人的经验。
个性化定制： 别害怕修改配置文件。Clawdbot 提供了极高的自由度，你可以根据自己的需求调整模型、渠道、自动化流程，让它真正成为你的“专属”AI。
通过不断实践和探索，你会发现 Clawdbot 能够帮助你释放出巨大的生产力，将重复性工作交给 AI，让你有更多精力投入到更具创造性和策略性的任务中。
立即行动： 还在等什么？现在就跟随本教程，开始你的 Clawdbot 部署之旅吧！如果你在过程中有任何疑问，或者成功打造了有趣的用例，欢迎在评论区分享你的经验！
结论：打造你的数字生活指挥中心
至此，我们已经详尽地探讨了 Clawdbot 的完整部署和使用教程。从理解 Clawdbot 的核心价值、进行周密的部署前准备，到手把手完成安装和核心配置，再到深入探索高级安全功能、生产环境部署、自动化任务设置，以及最终的故障排查与实战用例分享，我们力求为你提供一个全面、实用且富有洞察力的指南。
Clawdbot 不仅仅是一个技术产品，它更代表了一种新的生活和工作方式——将强大的 AI 能力本地化、个人化，并与我们日常使用的通讯平台深度融合。它赋予了你前所未有的控制权和定制自由，让 AI 真正成为你的延伸，一个能够打破数字边界、主动执行任务的智能助手。
当然，强大的能力也伴随着相应的责任。我们反复强调了安全考量的重要性，包括隔离部署、严格的权限管理、用户白名单等。在享受 Clawdbot 带来的便利时，请务必保持警惕，确保你的 AI 助手在受控环境中运行。
展望未来，随着 AI 技术的不断进步和 Clawdbot 社区的持续发展，我们有理由相信，这个开源项目将解锁更多令人惊叹的功能和应用场景。它不仅仅是帮你查询信息、生成内容的工具，更是一个能帮你连接世界、自动化生活的数字指挥中心。
希望这份教程能帮助你成功部署并充分利用 Clawdbot，开启你的智能新篇章。现在，就大胆尝试，让 Clawdbot 成为你提升生产力、享受数字生活的得力助手吧！
[行动号召]： 如果你已经成功部署了 Clawdbot，或者在部署过程中遇到了有趣的问题并解决了，欢迎在评论区分享你的经验和用例！让我们一起构建一个更智能、更高效的未来！
常见问题 (FAQs)
Q1：Clawdbot 是什么？它主要能做什么？ A1：Clawdbot 是一个开源的本地个人 AI 助手网关，它能够将各种 AI 大模型（如 Claude、GPT、Gemini 等）与你的日常通讯工具（如 Telegram、WhatsApp、Discord）无缝连接。它不仅能进行智能对话和内容生成，更重要的是，Clawdbot 具备强大的工具调用能力，可以执行本地系统命令、读写文件、控制浏览器、设置定时任务等，从而实现复杂的自动化流程，将 AI 的智能转化为实际操作，提升个人和团队的生产力。
Q2：部署 Clawdbot 需要什么样的硬件和软件环境？ A2：硬件方面，建议至少 8GB 内存（16GB+ 推荐），4 核 CPU（8 核+ 推荐），以及 10GB 以上的存储空间，并确保有稳定的互联网连接。软件方面，Clawdbot 运行在 Linux、macOS 或 Windows (WSL2) 系统上，核心要求是 Node.js 22.0.0 或更高版本。推荐使用 NVM (Node Version Manager) 来管理 Node.js 版本，并使用 npm 或 pnpm 作为包管理器。
Q3：如何将 Clawdbot 连接到 Telegram 或 WhatsApp？ A3：连接 Telegram 需要先在 Telegram 中通过 @BotFather 创建一个机器人并获取 Bot Token。然后将此 Token 配置到 Clawdbot 的 channels.telegram 设置中，并通过 clawdbot channels login telegram 命令进行登录，最后在终端批准配对。连接 WhatsApp 则更为简单，只需运行 clawdbot channels login whatsapp 命令，然后用手机 WhatsApp 扫描终端上显示的二维码即可完成登录连接。
Q4：使用官方 AI 模型 API Key 和第三方中转站 API 有什么区别？我应该如何选择？ A4：官方 API Key 是直接从 Anthropic、OpenAI 等官方平台获取的，通常需要信用卡绑定和充值，可能受地域限制。第三方中转站 API 则通过代理服务，解决了官方 API 的访问限制问题，并可能提供更灵活的计费方式。选择时，如果能稳定访问官方 API 且对安全性要求极高，可优先选择官方。如果官方 API 访问受限或寻求更经济的方案，可考虑信誉良好的中转站，但务必确认中转站支持工具调用且 API 兼容 Clawdbot 的配置要求。
Q5：如何确保 Clawdbot 在服务器重启后能自动启动并持续运行？ A5：为了让 Clawdbot 持续稳定运行并开机自启，你需要将其配置为后台服务。在 Linux 系统上，推荐使用 systemd 服务管理器。在 macOS 上则使用 launchd。Clawdbot 提供了 clawdbot onboard --install-daemon 命令来帮助你自动安装和配置这些后台服务。安装后，你可以使用 sudo systemctl enable clawdbot-gateway (Linux) 启用开机自启，并用 sudo systemctl start clawdbot-gateway 启动服务。
Q6：部署 Clawdbot 时，主要的安全性考量有哪些？ A6：由于 Clawdbot 具备深度系统操作权限，安全性至关重要。主要考量包括：
隔离部署： 强烈建议在 Docker 容器、独立的 VPS、虚拟机或专用低配设备中部署，避免在日常工作或存储敏感数据的机器上直接运行。
工具权限控制： 严格限制 AI 可以调用的工具，例如禁用 exec (执行任意命令) 和 browser (控制浏览器) 等高风险工具，只允许必要的工具。
用户白名单与配对机制： 启用 DM 配对，并配置 allowedUsers 白名单，确保只有授权用户才能与 Bot 交互。
API Key 保护： 避免将 API Key 明文写入配置文件，推荐使用环境变量。
定期审查日志： 及时发现异常行为。
Q7：Clawdbot 可以集成本地的工具或脚本吗？ A7：是的，Clawdbot 的强大之处就在于其对本地工具和脚本的集成能力。通过配置工具权限，AI 可以调用 exec 工具执行任意的 shell 命令，这意味着你可以让 AI 运行你服务器上的任何自定义脚本或应用程序。例如，让 AI 调用一个本地的图片处理脚本、数据分析工具，或者与你的智能家居系统进行交互。这种能力大大扩展了 AI 的实用性和自动化潜力。