常见故障

1. 命令不存在

docker compose exec ai-tools ai-tools-check
docker compose build --no-cache
docker compose up -d

如果只缺少一个命令，查看构建日志中对应 npm 包的安装错误。

2. 项目目录没有权限

在 Ubuntu 主机执行：

grep -E '^(AI_UID|AI_GID)=' .env
id -u
id -g
sudo chown -R "$(id -u):$(id -g)" /srv/projects

.env 中的 UID/GID 应与操作项目文件的 Ubuntu 用户一致。修改后重新构建容器。

3. 登录完成后重建容器又要求登录

检查持久化目录：

docker compose config
grep '^AI_HOME_PATH=' .env
ls -ld "$(grep '^AI_HOME_PATH=' .env | cut -d= -f2-)"

确认 Compose 仍把 AI_HOME_PATH 挂载到了 /home/ai，并且目录没有被手动删除。

4. Windows 运行脚本后界面显示异常

使用 Windows Terminal，并确保 SSH 分配终端：

ssh -tt mobai@192.168.1.100 "docker exec -it ai-tools codex"

本部署包的 remote-ai.ps1 已经使用 ssh -tt。

5. 登录链接跳回 localhost 后失败

原因是网页在 Windows 打开，但登录回调服务在 Ubuntu 容器里。优先选择设备验证码登录或 API Key。只有在工具明确显示回调端口时，才建立对应的 SSH 端口转发。

不要直接把随机回调端口开放到公网。

6. 无法访问模型接口或 npm

在容器内检查 DNS 和 HTTPS：

docker compose exec ai-tools getent hosts registry.npmjs.org
docker compose exec ai-tools curl -I https://registry.npmjs.org/

如果 Ubuntu 主机需要代理，应把代理地址配置到 Docker daemon 或 Compose 环境中。代理凭证不要写入会提交的文件。

7. DeepSeek Harness 更新后参数变化

它目前是 developer preview。先查看当前帮助：

docker compose exec ai-tools dsh --help
docker compose exec ai-tools dsh web --help

确认工作后，把 .env 的 DSH_VERSION 从 latest 改为当前版本号并重新构建。

8. OpenClaw 受到影响

本 Compose 文件没有安装 OpenClaw、没有映射 OpenClaw 端口，也没有挂载 OpenClaw 配置目录。若现有 OpenClaw 出现问题，应单独检查它原来的服务，不要删除 AI 工具箱的 data 目录试图修复。

9. CC Switch 切换后没有生效

先检查冲突环境变量和当前 Provider：

ai cc-switch env check --app codex
ai cc-switch --app codex provider current

确认网页“设置 -> Provider”中的“CC Switch 配置接管”已启用，并重新创建 CLI 会话。已经运行中的会话不会自动切换 Provider。

10. Multica daemon 离线

ai multica config show
ai multica daemon status --output json
docker compose logs --tail=150 ai-tools

若 workspace_id 未设置，回到网页 Runtime 页面重新初始化。若配置完整但 daemon 未上线，执行 docker compose restart ai-tools，Supervisor 会重新拉起它。不要在容器内额外运行后台 daemon，否则会与 Supervisor 管理的前台进程重复。

若授权页面最终跳回无法访问的本地回调地址，使用部署文档“初始化 Multica Runtime”中的一次性 host 网络命令。它只负责写入 /home/ai/.multica，不会改变正式 Compose 的网络边界。

3.2 KiB Raw Blame History Unescape Escape