首次配置

完成下面三项配置后，就可以创建实例并开始工作：连接节点、准备环境、配置模型。

1. 检查本机节点

服务器完整安装或桌面应用通常会自动接入本机节点。打开“设置 → 节点”，确认节点状态为“在线”。如果本机节点没有显示，使用“添加本地节点”重新同步。

接入远程节点

1. 打开“设置 → 节点”。
2. 选择“添加节点”，按向导判断远程节点能否访问当前控制面板。
3. 优先复制界面生成的完整安装命令。
4. 在远程 Debian/Ubuntu 主机上以管理员权限执行该命令。
5. 返回控制面板，等待向导显示“节点已连接”。

界面生成的命令会包含一次性加入令牌和与当前控制面板匹配的软件版本。令牌不要发送到公开聊天或写入仓库。

2. 准备运行环境

打开“设置 → 镜像”。TaskHandoff 将镜像分为两类：

• “镜像市场”：系统提供的只读镜像目录；
• “自定义镜像”：由管理员添加的镜像引用。

创建 Docker 实例前，目标节点必须已经安装并启动 Docker。创建向导会检查 Docker daemon，并提示当前镜像是已就绪还是需要拉取。

你也可以把已配置好的 Docker 实例保存为“环境模板”。模板包含容器可写层中的软件和工具，但不包含 /workspace、/data、/home/agent、其他挂载、内存或运行中的进程。

3. 配置模型 Provider

1. 打开“设置 → 模型”。
2. 新增模型 Provider。
3. 选择应用类型，主要使用 Codex 或 OpenCode。
4. 填写服务端点、API 密钥和模型名称。
5. 使用测试功能验证连接，再保存配置。

Codex 主要使用 openai-responses，OpenCode 主要使用 openai-chat-completions。模型可以保存在控制平面或指定节点。API 密钥属于敏感信息，不要把它写入文档、提示词或项目文件。

实例创建后，还可以在“实例设置 → 模型”中调整该实例可使用的 Provider 及优先顺序。默认使用第一个兼容 Provider 的第一个模型。

两种 Agent 的完整差异和配置步骤见 Codex 与 OpenCode。

可选：添加项目

打开“设置 → 项目”可以预先登记 Git 仓库。创建实例时也能直接选择“添加仓库”，因此这一步不是必需的。

私有仓库建议先在“设置 → Git 凭据”添加 HTTPS Token 或 SSH 凭据，再创建实例。详情见设置与安全。