DeepSeek Harness Web UI 打不开怎么排查？

浏览器显示“无法连接”，或页面能打开但模型、工作区和执行按钮全部不可用。

本周建议动作：不要先重装。先确认 dsh web 进程是否仍在运行、终端是否打印访问地址，再依次检查浏览器地址、远程访问通道、模型凭据、工作区选择和操作审批。远程 Mac 必须先通过安全通道验证，不能把默认本地监听地址直接暴露到公网。 DeepSeek 官方当前文档显示，dsh web 默认启动本地 Web UI，默认地址为 http://127.0.0.1:3080；该项目仍处于开发预览阶段，升级可能带来兼容性变化。(官方启动说明)

这篇内容适合 3 类人：首次启动 DeepSeek Harness Web UI 但浏览器无法访问的个人开发者；页面打开后模型或工作区不可用的 AI Agent 工程师；以及负责远程 Mac 开发节点与访问链路的运维人员。

最后更新于 2026 年 8 月 18 日，核实自 DeepSeek Harness 官方 README、Web UI 指南、模型配置指南、CLI 文档，以及 DeepSeek API 错误码和限流文档。开发预览版本的命令、默认值和配置路径可能继续调整。

不要把所有空白页、连接失败和任务无响应都归为“服务挂了”。在 macOS 上，启动链路通常至少存在以下几种不同问题：

• 命令未找到：终端直接提示命令不存在，说明 Node.js、npx 或当前安装路径没有准备好。
• 命令启动失败：进程瞬间退出，终端通常会留下参数、依赖、配置或权限错误。
• 端口被占用：新进程无法绑定监听地址，但旧进程、其他开发服务或残留实例可能仍然存在。
• 浏览器地址错误：服务实际运行在远程 Mac 或另一个端口，本机浏览器却访问了 127.0.0.1。

先在启动命令所在的终端执行：

npx @deepseek-ai/dsh web

然后观察 3 个信号：

1. 命令是否仍然占据终端，而不是立即返回 Shell；
2. 终端是否打印访问地址；
3. 访问地址中的主机名、端口，是否与浏览器输入的一致。

如果终端已经返回提示符，优先保存完整输出，不要立刻重复执行几十次。可以用以下命令确认本机是否仍有监听进程：

ps aux | grep -E '[d]sh|[n]ode'
lsof -nP -iTCP:3080 -sTCP:LISTEN

3080 只适用于官方当前默认配置；如果终端明确打印了其他端口，应以终端输出为准，而不是机械套用默认地址。CLI 文档也说明，dsh web 是 Web profile 的启动入口，应用参数应放在启动器参数之后，例如 dsh --profile web --help。(CLI 文档)

恢复标准：终端中的进程没有异常退出，监听检查能看到对应端口，并且在同一台 Mac 上访问终端打印的地址可以返回页面。只有满足这 3 项，才进入下一层排查。

本机访问和跨设备访问不是同一个问题。官方默认地址是 127.0.0.1，它代表服务只绑定在运行进程的 Mac 本机回环接口上；远程电脑即使能登录同一账号，也不能直接通过自己的 127.0.0.1 访问远程节点。(官方 Web UI 指南)

远程 Mac 的核验顺序建议如下：

1. 先通过 SSH 登录远程 Mac；
2. 在远程节点执行 curl -I http://127.0.0.1:3080；
3. 如果远程本机能返回 HTTP 响应，再建立经过认证和访问控制的端口转发；
4. 在本地浏览器访问转发后的本地地址；
5. 最后才评估是否需要更复杂的反向代理、身份认证和网络边界。

例如，端口转发应由团队现有的安全策略决定，不应把未认证的开发 Web UI 直接绑定到公网网卡。远程节点还要注意用户身份差异：通过 SSH 启动的进程，工作区、凭据和 $DSH_HOME 可能属于 SSH 用户；通过后台服务启动时，实际运行用户可能完全不同。

如果远程 Mac 本机的 curl 都失败，问题在启动链路；如果远程 Mac 本机成功、SSH 转发后失败，问题在访问链路；如果浏览器能打开但页面功能异常，才进入应用配置层。按这个分界处理，比反复修改防火墙规则更省时间。

如何安全访问远程 Mac 上的 DeepSeek Harness Web UI？
建议采用“远程本机验证 → 受控端口转发 → 浏览器本地访问”的顺序，并保留 SSH 用户、启动目录、监听地址和转发命令记录。除非已经配置身份认证、访问控制和日志审计，否则不建议把 Web UI 改成公网可访问服务。

对于需要临时开发节点的团队，可以先查看 JEXCLOUD 的远程 Mac 方案，重点核对远程登录方式、节点交付记录和是否能保留自己的启动环境，而不是只比较裸机价格。

页面能加载，不等于模型路由已经可用。官方 Web UI 指南要求在“设置 → 模型”中保存 DeepSeek API 密钥；模型配置指南说明，保存后下一次请求即可生效，不必因为保存密钥而重启服务。(模型配置指南)

保存 API Key 后模型仍不可用怎么办？可以按下面的观察信号处理：

• 模型选择器为空：先确认密钥是否真正保存，再确认当前页面是否使用了正确的 $DSH_HOME。
• 选择器有模型但发送时报凭据缺失：重点检查凭据引用的环境变量、运行用户和保存凭据的用户是否一致。
• 显示 MISSING_CREDENTIAL：重新在模型页面保存凭据，或补齐配置引用的环境变量。
• 显示 UNKNOWN_MODEL：模型名称没有出现在当前提供方目录中，需要选择已配置模型，或在自定义提供方中手动添加模型。
• 获取模型目录时返回 401：通常是认证失败，或者该兼容接口没有正确实现 GET /models；官方文档允许在这种情况下手动填写模型。
• 请求返回 429：优先判断限流，不要把它误判成 Web UI 崩溃。DeepSeek API 文档将 429 定义为请求过快或超出并发限制；401 表示认证失败，503 表示服务过载。(官方错误码说明)

自定义提供方还要同时核对 Provider ID、Base URL、协议类型、凭据和模型 ID。只填 API Key 而没有匹配的地址或模型目录，页面可能看起来配置完成，实际请求仍然无法路由。

新 Web UI 不会自动把启动目录当成已选择的工作区。官方指南明确区分了两件事：dsh 启动时所在目录会作为默认文件系统位置，但全新的 Web UI 仍然需要先添加并选择工作区；在选择完成前，会话输入区域可能保持不可用。(中文 Web UI 指南)

请按以下顺序核验：

pwd
ls -ld /项目/实际路径
whoami

然后在 Web UI 中执行：

1. 打开工作区选择器；
2. 添加远程节点上真实存在的项目目录；
3. 选择刚添加的目录；
4. 确认页面显示的工作区名称与 pwd 或实际项目路径一致；
5. 再创建新会话，不要直接复用一个已经绑定旧路径的会话。

远程 Mac 最容易出现“本机路径认知错误”：本地电脑上的 /Users/某用户/project，不等于远程 Mac 上同名路径；即使目录名称相同，用户、挂载卷、权限和 Git 工作树也可能不同。若 ls -ld 显示当前运行用户没有读取或执行权限，先修正目录权限或改用正确的运行用户。

恢复标准：工作区能够被添加和选中，页面可以显示仓库文件，且最小读取任务能返回文件名或目录结构；仅仅看到输入框解除禁用，还不能算完全恢复。

任务一直转圈，并不一定代表进程停止。DeepSeek Harness Web UI 可能正在等待以下任一条件：

• 等待用户批准读取、写入或执行操作；
• 等待 DeepSeek API 返回；
• 请求被限流或上游服务暂时过载；
• 会话状态与当前模型、工作区或凭据不一致；
• 浏览器连接断开，但远程进程仍在继续工作。

先查看页面是否出现批准提示，再查看终端是否有新的请求或错误输出。对于 API 侧，保留 HTTP 状态码、发生时间、模型 ID 和最小复现任务；不要只记录“页面没反应”。官方限流文档说明，超过账号并发限制会收到 429，请求可能在模型响应完成前持续保持连接；因此，单纯等待页面变化不能证明服务已经崩溃。(官方限流与并发说明)

建议用无副作用任务复现：

读取当前工作区根目录，只返回一级文件和目录名称，不修改任何文件，也不要运行外部命令。

如果这个任务能完成，而复杂任务卡住，问题更可能出在审批、工具调用、仓库规模或上游响应，而不是 Web UI 本身。若连只读任务都失败，再回到模型配置、工作区权限和会话状态检查。

恢复后不要马上提交有副作用的代码修改。建议按下面的顺序做一次验收，并把结果写入远程 Mac 的交付记录：

• ✅ 页面访问：本机或受控远程通道可以稳定打开 Web UI；
• ✅ 模型选择：模型选择器中有明确的可用模型；
• ✅ 仓库读取：能读取工作区根目录和一个指定文件；
• ✅ 无副作用命令：仅执行版本查询或目录查看；
• ✅ 会话持久化：刷新页面或重新连接后，能够识别当前会话状态；
• ✅ 错误留痕：保留启动时间、运行用户、工作区路径、模型 ID 和异常状态码。

在升级或修改配置前，先备份 $DSH_HOME 下的凭据引用、模型设置和工作区记录，但不要把真实 API Key 直接复制到工单或聊天窗口。模型配置指南指出，凭据和设置分别承担不同作用，运行用户变化可能导致同一台 Mac 读取到不同配置。(配置字段与凭据说明)

如果出现以下任一情况，应回退到已验证环境，而不是继续叠加修改：

• 升级后命令语法、默认端口或配置路径发生变化；
• 本地最小任务成功，但远程节点持续失败；
• 模型配置被改动后，旧会话无法恢复；
• 任务涉及写文件或执行命令，但审批链路尚未验证；
• 远程节点没有可回滚的环境快照或交付记录。

对临时使用来说，直接维护一台长期在线的本地 Mac，往往还会额外承担系统更新、网络穿透、权限隔离和故障复现成本；普通云主机则可能缺少稳定的 macOS 工作区、远程桌面体验和开发工具链一致性。若当前问题来自远程节点本身，使用 JEXCLOUD 的 Mac 环境可以减少自行准备硬件、配置远程访问和重复恢复系统的工作，但长期稳定重负载、需要物理接口或必须完全掌控硬件的场景，仍然更适合自购 Mac。开始前可先查看 JEXCLOUD 的 Mac 节点选项，并要求保留一份可回滚的环境快照或交付记录，避免下一次升级只能靠重装恢复。