跳转到主要内容
本文用于集中记录常见故障的排查路径。当前先覆盖 Docker 部署时容易遇到的问题，后续可以继续补充模型、机器人适配器、MCP、Skill 等章节。 以下命令默认在 LangBot/docker 目录执行。

​
Docker 部署

​
启动前快速确认

需要使用沙箱、stdio MCP 托管、Skill 添加/编辑等能力时，请使用 all profile 启动： 
docker compose --profile all up -d
确认服务状态： 
docker compose --profile all ps
正常情况下应看到：
  • langbot：WebUI 和后端服务，默认映射 5300 和 2280-2285。
  • langbot_plugin_runtime：插件运行时，默认映射 5401。
  • langbot_box：Box Runtime 控制面，用于创建沙箱容器。
如果只运行 docker compose up，不会启动 langbot_box，stdio MCP、Skill 添加/编辑和部分沙箱能力将不可用。

​
端口被占用

​
症状

  • docker compose up 报端口绑定失败。
  • WebUI 无法访问 http://127.0.0.1:5300。
  • 日志中出现 port is already allocated、bind: address already in use 等信息。

​
处理方式

先确认占用端口的进程。Linux/macOS： 
lsof -i :5300
lsof -i :5401
Windows PowerShell： 
Get-NetTCPConnection -LocalPort 5300,5401 | Select-Object LocalPort,OwningProcess
Get-Process -Id <PID>
如果确认是旧的 LangBot、插件运行时或测试进程，可以停止该进程后重新启动： 
docker compose --profile all up -d
如果不能停止占用进程，请修改 docker-compose.yaml 中对应端口映射，避免与现有服务冲突。

​
Box Runtime 未启动或不可用

​
症状

  • 页面或日志提示 No sandbox backend (Docker/nsjail/E2B) is ready。
  • stdio 模式 MCP 一直不可用。
  • Skill 无法安装、激活或编辑。

​
常见原因

  • 没有使用 --profile all 或 --profile box 启动。
  • langbot_box 没有运行。
  • 当前用户或 Docker Desktop 无法访问 Docker。
  • Linux 主机上当前用户没有 Docker socket 权限。

​
处理方式

确认 langbot_box 已启动： 
docker compose --profile all ps
docker logs langbot_box --tail 100
确认 Docker 可用： 
docker info
Linux 上如果当前用户不能访问 Docker，可加入 docker 用户组后重新登录： 
sudo usermod -aG docker $USER
newgrp docker
docker info
之后重新创建容器： 
docker compose --profile all up -d --force-recreate

​
Box 根目录挂载失败

​
症状

  • 日志中出现 host_path is outside allowed_mount_roots。
  • 日志中出现 host_path must point to an existing directory on the host。
  • Docker Desktop 环境中，Box 根目录被解析为 /run/desktop/... 后被拒绝。
  • stdio MCP 或 Skill 相关沙箱容器无法创建。

​
原因

langbot_box 会通过宿主机 Docker socket 创建沙箱容器。沙箱容器看到的是宿主机路径，因此 Box 根目录的“宿主机路径”和“容器内路径”必须保持一致，并且该路径必须位于 allowed_mount_roots 内。

​
处理方式

在 LangBot/docker/.env 中设置一个 Docker 能挂载、且不会被 Box 安全规则拒绝的绝对路径： 
LANGBOT_BOX_ROOT=/var/lib/langbot/box
Windows Docker Desktop 可以使用 Docker VM 可识别的路径，例如： 
LANGBOT_BOX_ROOT=/host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
确保目录存在后重建容器： 
docker compose --profile all up -d --force-recreate
如果之前已经手动修改过 docker/data/config.yaml，请同步检查： 
box:
  local:
    host_root: /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
    allowed_mount_roots:
      - /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box

​
大量 stdio MCP 启动失败或长时间 connecting

​
症状

  • MCP 状态停留在 connecting 或变为 error。
  • docker logs langbot_box 中出现 Cannot fork。
  • 同时安装较多 stdio 模式 MCP 后，原本可用的 MCP 也开始启动失败。

​
原因

stdio MCP 会运行在 Box 沙箱中。默认 Box profile 的 PID 限制较低，同时启动多个 npx、uvx MCP 时可能达到沙箱进程数限制。

​
处理方式

在 docker/data/config.yaml 中把 Box profile 调整为资源更高的内置 profile： 
box:
  local:
    profile: network_extended
然后停止 LangBot 和 Box，删除旧共享沙箱，让新配置生效。 Linux/macOS： 
docker compose --profile all stop langbot langbot_box
docker rm -f $(docker ps -aq --filter "name=langbot-box-mcp-shared")
docker compose --profile all up -d --force-recreate
Windows PowerShell： 
docker compose --profile all stop langbot langbot_box
docker ps -a --filter "name=langbot-box-mcp-shared" --format "{{.Names}}" | ForEach-Object { docker rm -f $_ }
docker compose --profile all up -d --force-recreate
等待 MCP 冷启动完成后，在 MCP 管理页面确认状态为 connected，并检查工具数量是否大于 0。

​
MCP 已安装但没有工具或无法连接

​
症状

  • MCP 已出现在列表中，但状态是 error 或长期 connecting。
  • 工具数量为 0。
  • 远程 MCP 日志中出现 401 Unauthorized、连接超时或握手失败。

​
常见原因

  • 远程 MCP 需要 API Key 或 OAuth 授权，但未配置。
  • MCP 包首次通过 npx 或 uvx 冷启动，依赖下载时间较长。
  • 当前 Docker 网络无法访问对应 MCP 服务或包仓库。
  • stdio MCP 沙箱资源不足。

​
处理方式

优先在 LangBot Space 中选择无需密钥或已正确配置密钥的 MCP。对于需要密钥的 MCP，请在安装配置中补齐环境变量、请求头或 URL 参数。 查看运行时日志： 
docker logs langbot --tail 200
docker logs langbot_box --tail 200
如果确认某个 MCP 无法在当前环境连接，请在 MCP 管理页面禁用或删除它，避免影响排查结果。

​
镜像标签或镜像源不一致

​
症状

  • docker compose ps 显示服务仍在使用旧镜像。
  • 修改了镜像源或标签后，重启仍未生效。
  • langbot、langbot_plugin_runtime、langbot_box 使用了不同镜像标签。

​
处理方式

保持三个 LangBot 服务的镜像标签一致，然后重新拉取并重建： 
docker pull rockchin/langbot:latest
docker compose --profile all up -d --force-recreate
如果你明确需要部署其他标签，请确保 docker-compose.yaml 中 langbot、langbot_plugin_runtime、langbot_box 三处镜像同时修改。

​
部署后验证

完成修复后建议做一次完整检查： 
docker compose --profile all ps
docker inspect langbot langbot_plugin_runtime langbot_box --format '{{.Name}} {{.Config.Image}} {{.State.Status}}'
确认 WebUI 可访问： 
curl -I http://127.0.0.1:5300/
在页面中继续确认：
  • 可以正常登录。
  • Box / 沙箱能力可用。
  • MCP 列表中的目标 MCP 状态为 connected。
  • stdio MCP 的工具数量正常显示。