workbuddy 官方镜像在 docker 模式下不提供 /health 接口，健康检查依赖 get / 返回 200；需用 curl -i http://localhost:8080/ 验证，同时检查日志是否输出 “claw server started on :8080”，并确保配置卷挂载正确、claw_token 环境变量生效且无残留配置文件。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
docker-compose up 后服务无响应，health 接口返回 404
WorkBuddy 官方镜像默认不暴露 /health 路径，该端点仅在二进制直装或 Kubernetes 部署中启用。Docker 容器模式下健康检查依赖的是 GET /（根路径），返回 200 即表示服务就绪。
常见误操作是直接 curl http://localhost:8080/health 并据此判断失败。正确验证方式应为：
- 执行
curl -I http://localhost:8080/，确认响应头含HTTP/1.1 200 OK - 检查容器日志：
docker logs workbuddy-service，重点看是否输出Claw server started on :8080 - 若日志卡在
waiting for config volume mount，说明/app/config挂载失败，需确认宿主机目录存在且有读写权限
CLAW_TOKEN 不生效，Claw Settings 页面显示“未授权”
Token 生效前提是容器启动时已通过环境变量注入，且配置卷中不存在已有 claw_config.yaml。一旦该文件被创建（哪怕为空），WorkBuddy 就会优先读取它，忽略 CLAW_TOKEN 环境变量。
解决步骤：
- 停用容器：
docker-compose down - 清空宿主机挂载的配置目录（如
./config），确保不含claw_config.yaml或token类文件 - 在
docker-compose.yml的environment区块中显式声明：CLAW_TOKEN: "your_actual_token_here"，不要用${CLAW_TOKEN}引用 shell 变量（compose v2 默认不展开） - 重启：
docker-compose up -d，首次启动时会自动生成合规的配置文件
macOS 上 docker run 报错 “port is already allocated”
WorkBuddy 默认监听 0.0.0.0:8080，但 macOS 的 Docker Desktop 底层使用 HyperKit 虚拟机，其网络栈与宿主机共享端口。如果本地已运行 WorkBuddy 桌面版（后台服务默认也占 8080），就会冲突。
两种解法，按优先级排序：
- 关闭桌面版后台服务：打开 WorkBuddy → 右上角头像 → Claw Settings → 关闭
Enable Background Service - 改容器端口映射：在
docker-compose.yml中把"8080:8080"改成"8081:8080"，后续所有请求改用http://localhost:8081/claw - 不推荐方案：强行 kill 占用进程（
lsof -i :8080 | grep LISTEN），因桌面版进程受 macOS SIP 保护，常无法终止
容器内无法访问本地文件系统（如 ~/Downloads）
Docker 容器默认隔离宿主机文件系统。WorkBuddy 的 Skills（如文件整理、PPT 生成）需读写真实路径，必须显式挂载。仅靠 /app/config 挂载远远不够。
关键操作：
- 在
docker-compose.yml的volumes下增加对应路径映射，例如：
volumes:
- "${HOME}/Downloads:/host/Downloads:rw"
- "${HOME}/Documents:/host/Documents:rw"
然后在 Claw Settings 页面或技能配置中，把目标路径从 ~/Downloads 改为 /host/Downloads —— 容器内看到的只有挂载后的路径。
注意：${HOME} 在 compose 文件中不会自动展开，需提前在 shell 中导出（export HOME=/Users/xxx）或直接写死绝对路径。
最容易被忽略的一点：Claw Token 和挂载路径必须同步更新。改了 token 却没清空旧配置，或挂载了 Downloads 却还在技能里填 ~/Downloads，都会导致“看似部署成功，实则功能瘫痪”。
