Clawdbot Docker 部署与运维实战教程(2026版）

人工智能研究

Clawdbot Docker 部署与运维实战教程(2026版）

發布人 Brave 2026-01-27 04:06

1. 课程导读：为什么选择 Clawdbot
1.1 什么是 Clawdbot？
1.2 为什么使用 Docker 部署？
2. 核心概念：理解 Clawdbot 架构
2.1 Gateway（网关）
2.2 Skills（技能）
2.3 Agent 配置文件
3. 环境准备：部署前的必要条件
3.1 硬件要求
3.2 软件要求
3.3 必备账户
4. Docker Compose 配置详解
4.1 关键配置解读
5. 完整部署流程
5.1 第一步：创建项目目录
5.2 第二步：创建配置文件
5.3 第三步：启动服务
5.4 第四步：首次初始化（onboard）
5.5 第五步：访问 Web 界面
6. Skills 系统：扩展你的 AI 助手
6.1 Skills 的存储位置与优先级
6.2 添加 Skills 的三种方法
6.3 SKILL.md 文件格式规范
6.4 调用 Skills
7. Agent 人设配置：打造专属 AI 角色
7.1 配置文件位置
7.2 SOUL.md 配置示例
7.3 IDENTITY.md 配置示例
8. 安全配置：沙箱与权限管理
8.1 Clawdbot 的安全设计哲学
8.2 沙箱模式配置
8.3 高风险工具管理
9. 日常运维命令手册
9.1 容器管理
9.2 Gateway 管理
9.3 终端直接对话
9.4 日志与诊断
9.5 版本更新
9.6 Skills 管理
9.7 完全重置
10. 故障排查指南
10.1 远程无法访问
10.2 npm 警告信息
11. 进阶资源与社区
11.1 官方资源
11.2 重要文档入口
📋 命令速查表

适用版本：Clawdbot 2026.1.24+
部署环境：Dockge / Portainer / Docker Compose
难度等级：⭐⭐ 入门级
预计阅读时间：15 分钟

1. 课程导读：为什么选择 Clawdbot

1.1 什么是 Clawdbot？

Clawdbot 是一款开源的、自托管的个人 AI 助手，它的设计理念可以用官方的 slogan 来概括：

"Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞"

与 ChatGPT、Claude 等云端 AI 服务不同，Clawdbot 运行在你自己的设备上——无论是 Mac mini、树莓派、NAS 还是云服务器。这意味着你的所有对话、文件和自动化工作流都完全由你掌控，不会上传到第三方服务器。

根据 Medium 上的深度评测，Clawdbot 正在成为 2026 年个人生产力工具领域的革命性产品。它能够：

🔗 连接多种聊天平台（Telegram、WhatsApp、Discord、Slack、iMessage 等）
🧠 调用顶级 LLM（Claude、GPT、Gemini）或本地模型（Ollama）
🖥️ 控制你的浏览器和文件系统
⚡ 通过 Skills 系统无限扩展能力
🔒 数据本地化，隐私完全自主

1.2 为什么使用 Docker 部署？

虽然 Clawdbot 支持多种安装方式（npm 全局安装、源码编译等），但 Docker 部署具有以下显著优势：

优势	说明
🔒 环境隔离	不污染宿主机系统，依赖问题完全隔离
📦 一键部署	通过 docker-compose.yml 一条命令启动全部服务
🔄 便于迁移	配置和数据目录挂载到宿主机，迁移只需复制文件夹
🛠️ 易于维护	升级、回滚、重置都非常简单
📁 配合 FileBrowser	可视化管理 Skills 和配置文件，降低使用门槛

本教程的核心价值在于：我们将 Clawdbot 与 FileBrowser 集成部署，让你可以通过 Web 界面直接上传和编辑 SKILL.md 文件，而无需每次都通过终端操作。这对于非技术背景的用户来说是一个巨大的便利。

2. 核心概念：理解 Clawdbot 架构

在开始部署之前，理解 Clawdbot 的核心架构对后续的配置和维护至关重要。

2.1 Gateway（网关）

Gateway 是 Clawdbot 的核心控制中枢。 它是一个持续运行的后台服务，负责：

监听来自各个聊天渠道的消息
调度 LLM 处理用户请求
管理 Skills 和 Tools 的调用
提供 Web 控制界面

Gateway 默认监听端口 18789，通过 WebSocket 协议与客户端通信。

2.2 Skills（技能）

Skills 是 Clawdbot 的"能力扩展包"。 每个 Skill 是一个包含 SKILL.md 文件的目录，定义了 Clawdbot 在特定场景下应该如何行动。

Skills 与普通的 Slash Commands（斜杠命令）有本质区别：

特性	Slash Commands	Skills
调用方式	必须手动输入 /命令	AI 可自动判断调用
文件结构	单个 .md 文件	目录 + SKILL.md + 支持文件
适用场景	固定的快捷操作	复杂的多步骤工作流
上下文感知	较弱	可包含模板、脚本等辅助文件

2.3 Agent 配置文件

Clawdbot 使用一组 Markdown 文件来定义 AI 的"人格"和"记忆"：

文件	职责
SOUL.md	🎭 定义角色人设、语气风格、行为边界
AGENTS.md	📋 操作指令和长期记忆
IDENTITY.md	🏷️ Agent 的名字、氛围、代表 emoji
USER.md	👤 用户的个人资料和称呼偏好
BOOTSTRAP.md	🚀 首次运行的初始化脚本（执行后自动删除）

这套配置系统的设计哲学是"关注点分离"——将不同类型的配置分散到不同文件中，便于维护和版本管理。

3. 环境准备：部署前的必要条件

3.1 硬件要求

配置项	最低要求	推荐配置
CPU	1 核	2 核+
内存	1 GB	2 GB+
存储	5 GB	20 GB+（取决于日志和文件量）
网络	能访问外网	稳定的网络连接

💡 适用设备示例：Mac mini、树莓派 4B+、群晖 NAS、任意 VPS（如 Hetzner、DigitalOcean）

3.2 软件要求

✅ Docker Engine 24.0+ 或 Docker Desktop
✅ Docker Compose v2（已集成在新版 Docker 中）
✅ SSH 客户端（用于远程服务器管理）

3.3 必备账户

✅ LLM API Key：Anthropic（推荐）、OpenAI、OpenRouter 或其他支持的提供商

⚠️ 重要提示：根据 Clawdbot 官方安全文档的建议，推荐使用 Anthropic Claude Opus 4.5 模型，因为它在识别 prompt injection（提示词注入攻击）方面表现更加出色。

4. Docker Compose 配置详解

以下是经过实际部署验证的完整配置文件。每一行配置都附有详细注释，帮助你理解其作用。

version: "3.8"
services:
  clawdbot-gateway:
    image: node:22-slim
    container_name: clawdbot-gateway
    tty: true
    stdin_open: true
    volumes:
      - ./data:/work
      - ./clawdbot-config:/root/.clawdbot
      - clawdbot-modules:/usr/local/lib/node_modules  # 持久化已安装的包，避免重复安装
    working_dir: /work
    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
    ports:
      - 18789:18789
    entrypoint: ["/bin/bash", "-c"]
    command:
      - |
        # 只在首次运行时安装（避免 ENOTEMPTY 错误）
        if ! command -v clawdbot &> /dev/null; then
          apt-get update && apt-get install -y curl git ca-certificates
          npm install -g clawdbot@latest
        fi
        
        # 初始化配置（注意：bind 必须使用关键字，不能用 IP 地址）
        mkdir -p /root/.clawdbot
        if [ ! -f /root/.clawdbot/clawdbot.json ]; then
          echo '{"gateway":{"bind":"lan","port":18789,"controlUi":{"allowInsecureAuth":true}}}' > /root/.clawdbot/clawdbot.json
        fi
        
        # 直接启动 gateway 进程（Docker 环境不支持 systemd）
        echo "🦞 Starting Clawdbot Gateway..."
        cd /usr/local/lib/node_modules/clawdbot
        exec node dist/index.js gateway --bind lan --port 18789
    restart: unless-stopped

  filebrowser:
    image: filebrowser/filebrowser:latest
    container_name: filebrowser-clawdbot
    user: 0:0
    volumes:
      - ./data:/srv
      - ./clawdbot-config:/srv/.clawdbot
      - ./filebrowser-config:/database
    command:
      - --database
      - /database/filebrowser.db
      - --root
      - /srv
    ports:
      - 2081:80
    restart: unless-stopped

volumes:
  clawdbot-modules:  # 持久化 node_modules，避免每次重启都重新安装

networks: {}

4.1 关键配置解读

🔑 `--bind` 参数说明

--bind 参数决定了 Gateway 监听的网络接口：

值	实际绑定	说明	适用场景
`loopback`	127.0.0.1	仅本机访问	本地开发测试
`lan`	0.0.0.0	所有网络接口	局域网内多设备访问（推荐）✅
`tailnet`	Tailscale IP	绑定 Tailscale 网络	通过 Tailscale VPN 访问
`auto`	自动选择	优先 loopback，失败则 lan	自动判断
`custom`	自定义 IP	高级场景	特殊网络配置

⚠️ 重要：--bind 参数只接受上述关键字，不能直接写 IP 地址如 0.0.0.0 或 127.0.0.1，否则会报 gateway.bind: Invalid input 错误。

🔑 `allowInsecureAuth: true` 的作用

根据 Clawdbot v2026.1.21 版本更新说明，Control UI 现在默认拒绝不安全的 HTTP 连接。如果你没有配置 HTTPS（如通过 Tailscale Serve），就必须设置 allowInsecureAuth: true 才能正常访问 Web 界面。

🔑 `clawdbot-modules` Volume 的作用

这个持久化 Volume 解决了一个常见问题：每次容器重启都重新安装 clawdbot 导致的 npm ENOTEMPTY 错误。通过持久化 node_modules 目录，只有首次启动时才需要安装。

🔑 为什么使用 `node dist/index.js gateway`

Docker 容器默认没有 systemd 作为 init 系统，因此：

❌ clawdbot gateway 命令会尝试使用 systemd 管理服务，会报错
✅ node dist/index.js gateway 直接运行 Node.js 进程，无需 systemd

5. 完整部署流程

5.1 第一步：创建项目目录

# 创建项目主目录
mkdir -p ~/clawdbot

# 进入目录
cd ~/clawdbot

# 创建子目录结构
mkdir -p data clawdbot-config filebrowser-config

目录结构说明：

~/clawdbot/
├── docker-compose.yml      # Docker Compose 配置文件
├── data/                   # 工作目录（可存放项目文件）
│   └── skills/             # 工作区 Skills（最高优先级）
├── clawdbot-config/        # Clawdbot 配置持久化
│   ├── clawdbot.json       # 主配置文件
│   ├── skills/             # 用户 Skills
│   └── agents/             # Agent 人设配置
└── filebrowser-config/     # FileBrowser 数据库
    └── filebrowser.db

5.2 第二步：创建配置文件

将前文的 docker-compose.yml 内容保存到 ~/clawdbot/docker-compose.yml。

5.3 第三步：启动服务

# 启动所有服务（后台运行）
docker compose up -d

# 查看启动日志
docker logs -f clawdbot-gateway

等待看到以下输出，表示启动成功：

🦞 Clawdbot 2026.1.24-3 (885167d)
   
[gateway] listening on ws://0.0.0.0:18789
[hooks] loaded 3 internal hook handlers

5.4 第四步：首次初始化（onboard）

Clawdbot 首次运行需要进行初始化配置：

# 进入容器
docker exec -it clawdbot-gateway bash

# 运行初始化向导
clawdbot onboard

向导会引导你完成以下配置：

选择 API Provider：推荐选择 Anthropic 或 OpenRouter
输入 API Key：填入你的 LLM API 密钥
选择默认模型：推荐 Claude Opus 4.5（更擅长防御 prompt injection）
Gateway 绑定：选择 LAN 以允许远程访问
其他选项：按需配置

完成后退出容器并重启服务：

exit
docker restart clawdbot-gateway

5.5 第五步：访问 Web 界面

服务	访问地址	用途
🦞 Clawdbot	`http://你的IP:18789`	AI 助手主界面
📁 FileBrowser	`http://你的IP:2081`	文件管理（默认账号：admin/admin）

6. Skills 系统：扩展你的 AI 助手

6.1 Skills 的存储位置与优先级

Clawdbot 会从多个位置加载 Skills，优先级从高到低如下：

优先级	容器内路径	宿主机路径	说明
🥇 最高	/work/skills/	./data/skills/	工作区 Skills，仅当前项目可用
🥈 中	/root/.clawdbot/skills/	./clawdbot-config/skills/	用户 Skills，所有项目共享
🥉 低	内置	-	Clawdbot 自带的 bundled Skills
⬇️ 最低	extraDirs 配置	自定义	通过配置文件添加的额外目录

💡 实践建议：将常用的通用 Skills 放在 clawdbot-config/skills/，将项目相关的 Skills 放在 data/skills/。

6.2 添加 Skills 的三种方法

方法一：通过 FileBrowser 上传（推荐新手）

这是最直观的方式，完全不需要使用终端：

打开 http://你的IP:2081
使用默认账号登录（admin/admin，请及时修改密码）
进入 .clawdbot/skills/ 目录
点击"新建文件夹"，创建一个以 Skill 名称命名的目录（如 my-assistant）
进入该目录，上传你的 SKILL.md 文件

方法二：通过 SCP 远程上传

适合从本地电脑上传文件到远程服务器：

# 第一步：在服务器上创建 Skill 目录
docker exec -it clawdbot-gateway mkdir -p /root/.clawdbot/skills/my-skill

# 第二步：从本地上传 SKILL.md（在本地终端执行）
scp ~/Downloads/SKILL.md 用户名@服务器IP:~/clawdbot/clawdbot-config/skills/my-skill/

方法三：通过 ClawdHub 安装社区 Skills

ClawdHub 是 Clawdbot 的官方公共 Skills 注册表，你可以从中发现、安装和更新社区贡献的 Skills：

# 进入容器
docker exec -it clawdbot-gateway bash

# 同步所有可用 Skills
clawdhub sync --all

# 安装特定 Skill
clawdhub install <skill-name>

6.3 SKILL.md 文件格式规范

每个 Skill 必须包含一个 SKILL.md 文件，其格式如下：

---
# Skill 名称（将成为 /skill-name 斜杠命令）
name: my-skill

# 描述（AI 根据此描述判断何时自动调用该 Skill）
description: 这是一个帮助用户进行代码审查的 Skill

# 是否允许用户通过 /命令 手动调用（默认 true）
user-invocable: true

# 是否禁止 AI 自动调用（默认 false）
disable-model-invocation: false
---

# My Skill

## 你的角色

你是一个专业的代码审查助手，擅长发现代码中的潜在问题。

## 工作流程

1. 首先阅读用户提供的代码
2. 从安全性、性能、可读性三个维度进行分析
3. 给出具体的改进建议

## 输出格式

使用 Markdown 格式输出，包含：
- 问题摘要
- 详细分析
- 修改建议

⚠️ 注意：根据官方文档，Clawdbot 的 YAML frontmatter 解析器仅支持单行键值对，不要使用多行值或复杂的 YAML 结构。

6.4 调用 Skills

手动调用：在对话框中输入 /skill名称

/my-skill

自动调用：直接描述你的需求，如果你的 Skill 描述写得清晰，Clawdbot 会自动判断并加载对应的 Skill。

7. Agent 人设配置：打造专属 AI 角色

7.1 配置文件位置

Agent 配置文件位于：

clawdbot-config/
└── agents/
    └── main/
        └── agent/
            ├── SOUL.md        # 角色人设
            ├── AGENTS.md      # 操作指令
            ├── IDENTITY.md    # 身份标识
            ├── USER.md        # 用户资料
            └── TOOLS.md       # 工具使用说明

7.2 SOUL.md 配置示例

SOUL.md 是最重要的人设配置文件，它定义了 AI 的"灵魂"：

# Persona（角色设定）

你是「小龙虾」，一个专业、高效且略带幽默感的技术助手。你的特点是：
- 回答简洁有力，不说废话
- 遇到复杂问题会主动拆解步骤
- 适当使用 emoji 增加亲和力，但不过度

## Boundaries（行为边界）

- 始终使用中文回复，除非用户要求使用其他语言
- 涉及敏感话题时保持中立，不发表个人观点
- 不编造不存在的事实，遇到不确定的信息会明确告知

## Tone（语气风格）

专业但不刻板，简洁但不敷衍。像一个靠谱的技术朋友，而不是冷冰冰的机器。

## Capabilities（能力边界）

- 可以帮助编程、写作、翻译、数据分析
- 可以操作文件系统和浏览器（在授权范围内）
- 无法访问用户的私人账户或进行金融操作

7.3 IDENTITY.md 配置示例

# Identity

- **Name**: 小龙虾
- **Emoji**: 🦞
- **Vibe**: 专业、高效、略带幽默

8. 安全配置：沙箱与权限管理

⚠️ 重要警告：根据 SOCRadar 的安全分析报告，Clawdbot 作为一个拥有系统级权限的 AI 助手，必须谨慎配置安全策略。以下是官方推荐的安全最佳实践。

8.1 Clawdbot 的安全设计哲学

根据 Clawdbot 官方安全文档，其安全策略遵循以下原则：

"Identity first: 先确定谁能与 bot 对话（DM 配对/白名单）
Scope next: 再确定 bot 能在哪里操作（群组白名单、工具权限、沙箱、设备权限）
Model last: 假设模型可能被操纵，设计时确保操纵的影响范围有限"

8.2 沙箱模式配置

沙箱模式可以将 Skill 的执行隔离在 Docker 容器中，限制其对宿主系统的影响：

在 clawdbot.json 中添加：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

sandbox.mode 可选值：

值	说明
`off`	关闭沙箱（默认）
`non-main`	非主会话（群组/频道）在沙箱中运行
`all`	所有会话都在沙箱中运行

8.3 高风险工具管理

官方文档建议限制以下高风险工具的使用：

exec（命令执行）
browser（浏览器控制）
web_fetch / web_search（网络请求）

推荐做法：

使用小型模型时，启用沙箱并禁用网络相关工具
对于生产环境，使用白名单机制限制可执行的命令
敏感操作前，配置 approval gates（审批门控）

9. 日常运维命令手册

以下是你在日常维护中最常用的命令，建议收藏备用。

9.1 容器管理

# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 查看运行状态
docker compose ps

# 查看实时日志
docker logs -f clawdbot-gateway

9.2 Gateway 管理

⚠️ Docker 环境特别说明：由于 Docker 容器没有 systemd，clawdbot gateway restart/stop/start 等命令无法在容器中使用，会报 systemctl --user unavailable 错误。请使用 docker restart 替代。

# 查看 Gateway 状态
docker exec -it clawdbot-gateway clawdbot gateway status

# 重启 Gateway（Docker 环境正确方式）
docker restart clawdbot-gateway

# 查看日志
docker logs -f clawdbot-gateway

9.3 终端直接对话

在 Docker 环境中，可以使用 --local 参数直接在终端与 AI 对话：

# 进入容器
docker exec -it clawdbot-gateway bash

# 发送消息（本地模式，不需要 systemd）
clawdbot agent --message "你好" --local

# 带思考模式
clawdbot agent --message "帮我分析这个问题" --thinking high --local

9.4 日志与诊断

# 运行健康检查
docker exec -it clawdbot-gateway clawdbot doctor

# 检查通道状态
docker exec -it clawdbot-gateway clawdbot channels status --probe

9.5 版本更新

根据 Clawdbot v2026.1.21 更新说明，新版本引入了交互式更新向导：

# 方法一：重建容器（推荐，确保干净更新）
docker compose down -v
docker compose up -d

# 方法二：进入容器手动更新
docker exec -it clawdbot-gateway bash
npm install -g clawdbot@latest
exit
docker restart clawdbot-gateway

9.6 Skills 管理

# 创建新 Skill 目录
docker exec -it clawdbot-gateway mkdir -p /root/.clawdbot/skills/新skill名称

# 列出已安装的 Skills
docker exec -it clawdbot-gateway ls -la /root/.clawdbot/skills/

# 从 ClawdHub 同步 Skills
docker exec -it clawdbot-gateway clawdhub sync --all

9.7 完全重置

⚠️ 危险操作：以下命令会删除所有配置和数据！

# 停止并删除容器和 Volume
docker compose down -v

# 删除所有配置（不可恢复！）
rm -rf clawdbot-config/*

# 重新启动
docker compose up -d

# 重新初始化
docker exec -it clawdbot-gateway clawdbot onboard

10. 故障排查指南

10.1 远程无法访问

排查清单：

☐ 确认 --bind lan 已设置
☐ 确认 allowInsecureAuth: true 已配置
☐ 检查服务器防火墙是否放行 18789 端口
☐ 确认 docker-compose.yml 中端口映射正确（18789:18789）
☐ 确认日志中显示 listening on ws://0.0.0.0:18789 而非 127.0.0.1

一键修复网络绑定：

docker exec clawdbot-gateway sed -i 's/"bind":[^,}]*/"bind": "lan"/g' /root/.clawdbot/clawdbot.json && docker restart clawdbot-gateway

10.2 npm 警告信息

警告信息：

npm warn deprecated gauge@4.0.4: This package is no longer supported.
npm warn deprecated tar@6.2.1: Old versions of tar are not supported...

处理方式：这些是依赖包的版本警告，不影响使用，可以忽略。

11. 进阶资源与社区

11.1 官方资源

资源	链接	说明
🏠 官网	clawd.bot	官方主页
📚 文档	docs.clawd.bot	完整技术文档
💻 GitHub	github.com/clawdbot/clawdbot	源代码仓库
📦 Skills 仓库	github.com/clawdbot/skills	官方 Skills 集合
🏪 ClawdHub	clawdhub.com	社区 Skills 注册表

11.2 重要文档入口

📋 命令速查表

操作	命令
启动服务	`docker compose up -d`
停止服务	`docker compose down`
重启服务	`docker compose restart`
查看日志	`docker logs -f clawdbot-gateway`
进入容器	`docker exec -it clawdbot-gateway bash`
初始化配置	`docker exec -it clawdbot-gateway clawdbot onboard`
查看状态	`docker exec -it clawdbot-gateway clawdbot gateway status`
重启 Gateway	`docker restart clawdbot-gateway` ⚠️
健康检查	`docker exec -it clawdbot-gateway clawdbot doctor`
更新版本	`docker compose down -v && docker compose up -d`
创建 Skill	`docker exec -it clawdbot-gateway mkdir -p /root/.clawdbot/skills/名称`
同步 Skills	`docker exec -it clawdbot-gateway clawdhub sync --all`
终端直接对话	`docker exec -it clawdbot-gateway clawdbot agent --message "你好" --local`

⚠️ 注意：Docker 环境中 clawdbot gateway restart 无法使用，请用 docker restart clawdbot-gateway 替代

课程更新日期：2026 年 1 月 27 日
基于版本：Clawdbot 2026.1.24-3
作者验证环境：ARM64 架构 / Debian 12 / Docker 24.0+
修订说明：根据实际部署调试修正了 bind 参数、systemd 兼容性、npm 安装等问题

Brave 回复 4 days, 10 hours ago 1 成員 · 0 回复

0 回复

歡迎留言回复交流。

登入後即可回复

人工智能研究

組織者: