# 部署说明

## 1. 部署前提

Ubuntu 主机需要满足：

- Ubuntu 22.04 或 24.04，x86_64 或 ARM64
- 已安装 Docker Engine 和 Docker Compose Plugin
- 能访问各 CLI 的官网、npm Registry 和模型接口
- 当前用户有运行 Docker 的权限
- 建议至少 4 核 CPU、8 GB 内存和 15 GB 可用磁盘

这些 CLI 通常调用云端模型，本容器不在本机加载大模型权重，因此一般不需要 GPU。

## 2. 放置部署文件

建议把本目录放到 Ubuntu：

```text
/opt/ai-toolbox
```

项目统一放到：

```text
/srv/projects
```

创建项目目录：

```bash
sudo mkdir -p /srv/projects
sudo chown -R "$(id -u):$(id -g)" /srv/projects
```

## 3. 准备配置

```bash
cd /opt/ai-toolbox
cp .env.example .env
chmod +x scripts/ai
id -u
id -g
```

把 `id -u` 和 `id -g` 的结果填写进 `.env`：

```dotenv
WORKSPACE_PATH=/srv/projects
AI_HOME_PATH=/opt/ai-toolbox/data
AI_UID=1000
AI_GID=1000
AI_CONTAINER_NAME=ai-tools
TZ=Asia/Shanghai
```

不要把 API Key 写进 Dockerfile。`.env` 也不要提交到 Git。

## 4. 构建并启动

```bash
docker compose build
docker compose up -d
docker compose ps
docker compose exec ai-tools ai-tools-check
```

检查结果中以下命令都应显示 `OK`：

```text
codex claude codebuddy kimi opencode qwen dsh cc-switch multica
```

## 5. 首次登录

每个工具需要分别登录一次：

```bash
./scripts/ai codex .
./scripts/ai claude .
./scripts/ai codebuddy .
./scripts/ai kimi .
./scripts/ai opencode .
./scripts/ai qwen .
```

按照终端显示的链接或验证码，在 Windows 浏览器中完成登录。Kimi 进入界面后使用 `/login`。

远程服务器上，浏览器自动打开通常不会成功，这是正常的。优先使用工具提供的设备验证码登录；如果某个工具只支持浏览器回调，可以改用它支持的 API Key，或者为回调端口建立 SSH 隧道。

登录信息和会话文件保存在 `.env` 的 `AI_HOME_PATH` 目录中，不会因为重新构建镜像而丢失。

## 6. 初始化 CC Switch

打开网页的“设置 -> Provider”，点击“打开 CC Switch TUI”。先为 Claude、Codex 和 OpenCode 导入或创建 Provider，并确认三个 CLI 都有当前 Provider。

也可以在 SSH 中操作：

```bash
ai cc-switch
ai cc-switch --app codex provider list
```

配置完成后，在网页启用“CC Switch 配置接管”。启用后，AgentDock 不再向 Claude、Codex 和 OpenCode 会话注入网页账号页保存的旧 API Key，避免环境变量覆盖 CC Switch 配置。CodeBuddy、Kimi、Qwen 和 DeepSeek 仍由 AgentDock 管理。

## 7. 初始化 Multica Runtime

打开网页的“设置 -> Runtime”，填写现有自托管 Multica 的 Server URL 和 App URL，然后点击“初始化 Runtime”。授权只在独立终端中进行，完成后 Supervisor 会自动启动前台 daemon。

也可以在 SSH 中检查：

```bash
ai multica config show
ai multica daemon status --output json
docker compose logs --tail=100 ai-tools
```

Multica 当前公开支持 Claude、Codex、CodeBuddy、Kimi 和 OpenCode。Qwen 与 DeepSeek 会显示为“已安装，待验证支持”。本部署仅安装 Multica 客户端 Runtime，不包含也不替换用户现有的自托管服务端。

如果网页终端中的 OAuth 回调无法从 Windows 返回容器，可在 NAS SSH 中运行一次临时初始化。将两个示例 URL 替换为实际地址：

```bash
docker run --rm -it \
  --network host \
  --user 1000:1001 \
  -e HOME=/home/ai \
  -v /vol1/1000/docker/ai-toools/data:/home/ai \
  local/ai-toolbox:0.2.0 \
  multica-setup \
  --server-url https://multica-api.example.com \
  --app-url https://multica.example.com \
  --callback-host 192.168.200.36
```

该容器只在授权期间使用宿主机网络，完成后自动退出。正式 Multica daemon 仍由 `ai-tools` 内的 Supervisor 管理，不使用 host 网络。

## 8. DeepSeek Harness

DeepSeek Harness 的命令是 `dsh`，当前属于 developer preview，官方提示未来可能出现不兼容更新。

无界面执行一次任务：

```bash
./scripts/ai dsh my-project --profile headless "检查项目并运行测试"
```

查看当前版本支持的参数：

```bash
docker compose exec ai-tools dsh --help
```

当前 npm 包只提供 `headless` 与 `web` profile，没有可安装的原生 TUI。AgentDock 使用 `headless`，每次提交一个任务，完成后进程自动退出。`web` profile 不纳入 Compose，也不额外暴露端口。

## 9. OpenClaw 和 Cursor

- 不修改 Ubuntu 主机现有的 OpenClaw。
- 不占用 OpenClaw 的 Gateway 端口。
- Cursor 桌面版保留在 Windows。
- Cursor 使用 Remote SSH 打开 `/srv/projects/项目名`。
- AI 容器通过 `/workspace/项目名` 访问同一批文件。