zcode-webui

语言 / Language：中文 | English

在浏览器里完整运行官方 ZCode 桌面端界面，后端复用你机器上的官方运行时（zcode-server + GLM Agent）。它是对官方桌面端的补充：部署一次之后，手机、平板、瘦终端、任何有浏览器的设备都能随时打开同一个 ZCode，进行任务派发与会话推进——代码、会话和凭据始终留在你自己的服务器上。

🖥️ 官方界面原样呈现：聊天、任务、文件树等能力与桌面端一致；官方界面升级只需重新执行一次下载脚本
🤝 与 code-server 天然协同：挂在 /proxy/<port>/ 即可，共用其登录鉴权；WebSocket 被拦截时自动降级 HTTP 长轮询
⏳ 任务与标签页解耦：关闭标签页/断网不中断任务；空闲的后台会话按三重条件自动回收，运行中的永不回收
🔑 登录灵活：内置 OAuth 登录，或从已登录的桌面端导出凭据导入；与官方客户端共用同一凭据库
🔍 Ctrl+滚轮 / 双指捏合应用级缩放（50%–200%）：以捏合点为锚点平滑缩放、随手平移，页面永不脱离视口（边缘保护，缩小方向逐帧直接提交，无白边）
🧭 zcode-webui setup 一键部署：渲染层、官方运行时、配置、启动全自动
📦 不打包、不修改、不分发任何官方代码；核心只有几个源文件

快速开始

前提：Linux x64/arm64 · Node.js ≥ 18 · curl、dpkg-deb、tar · 磁盘 ≥ 2GB · 能访问 cdn-zcode.z.ai（下载）与 zcode.z.ai（登录）。

npm install -g @aixyzstudio/zcode-webui   # 需要 Node.js ≥ 18
zcode-webui setup --yes                   # 全自动：渲染层下载 → 官方运行时安装 → 写配置 → 启动 → 健康检查

完成后浏览器打开 http://<服务器>:3102/。未登录时先访问 /login 完成 OAuth（服务器无法直连 zcode.z.ai/api/v1 时用 setup --oauth-proxy <代理> 或见 FAQ）。

git 部署方式见手动部署；想省事也可以只跑 zcode-webui setup 进入交互式向导。

与官方的关系：我们只做了中间层

环节	谁来实现
界面（renderer）	官方客户端原样，由部署者通过本项目脚本从官方 CDN 下载，不进入本仓库、不二次分发
Agent / 模型调用 / 会话存储	官方运行时 `zcode-server.cjs` 与 GLM Agent，未做任何修改
登录认证	官方 CLI 的 OAuth 流程，凭据写入官方库 `~/.zcode/v2/credentials.json`（与官方客户端共用）
本项目的中间层	托管官方界面并注入启动配置；`window.zcode` 浏览器适配层；MessagePort ↔ WebSocket 桥；拉起官方运行时进程并转发消息

免责声明：社区项目，与智谱 / Z.ai 无隶属关系；不含任何官方代码。请遵守官方服务条款，模型调用费用按你的订阅计费。

手动部署（git clone）

git clone https://github.com/windviki/zcode-webui.git
cd zcode-webui && npm install          # 运行时依赖只有 ws

npm run fetch-renderer                 # 从官方 CDN 下载安装包并提取界面
                                       # （默认 3.9.2，可用 ZCODE_VERSION=… ZCODE_ARCH=x64 覆盖）

cp config.example.json config.json     # 可选；常用字段 workspace / oauthProxy / hostProxy

npm start                              # 等价于 node src/server.mjs，默认 http://0.0.0.0:3102/

长期运行建议用上面的 zcode-webui setup --systemd，或手写系统级单元：

[Unit]
Description=zcode-webui
After=network-online.target

[Service]
User=你的用户名
WorkingDirectory=/opt/zcode-webui
ExecStart=/usr/bin/node src/server.mjs
Restart=on-failure

[Install]
WantedBy=multi-user.target

与 code-server 协同（推荐）

以根路径模式启动（不要设置 basePath）：node src/server.mjs --port 3102。之后无需任何额外配置——公网入口就是 https://<域名>/proxy/3102/：

资源路径、API、WebSocket、登录页都按页面 URL 自动推导；缺斜杠的 /proxy/3102 自动补全重定向；
WebSocket 不通时前端自动降级为 HTTP 长轮询桥；
共用 code-server 的登录鉴权，无需 nginx。

自有反代的子路径部署：ZCODE_WEBUI_BASE_PATH=/zcode npm start（裸 /zcode 会 302 补斜杠）； nginx 保留前缀转发即可（proxy_pass http://127.0.0.1:3102; 不带 URI + 常规 Upgrade 头）。

登录与凭据（三种方式任选）

A · 直接在 WebUI 里 OAuth 登录（最简单，需要服务器能访问 zcode.z.ai） 打开 <服务地址>/login 点「开始登录」，在授权链接里完成 Z.ai OAuth，凭据自动写入服务器的 ~/.zcode/v2/credentials.json。

B · 从已登录的桌面端导出凭据导入（无需服务器出网） 在桌面电脑上打开 <服务地址>/export-credentials.html（纯浏览器本地运行），选择该机的 ~/.zcode/v2/credentials.json 并填入 platform/主目录/用户名解密，把输出 JSON 粘贴到 WebUI 的 /login「导入凭据」框。

C · 服务器上本来就登录过官方 CLI / 桌面端 ~/.zcode 已就绪，直接使用。

任务生命周期（重要，30 秒读完）

同一账号只有一个正在运行的宿主进程，所有设备的页面都作为它的视图接入：

多设备同时实况：任何设备打开页面即接入同一进程——历史与实时输出全部可见、持续推送；换设备、多设备同时开着看，互不干扰、互不刷新；
关闭标签页不结束任务：最后一个页面离开后，进程转入后台继续执行直到完成或等待输入（空闲默认 30 分钟回收；执行中/等待输入的永不回收）；
注意：若另一台设备的任务还在执行就发新指令，两个代理仍会并发操作同一批文件—— 请等任务完成，或明确需要并行时再发；
重启 zcode-webui 服务进程会中断后台任务（与桌面端重启一致）。

配置参考

优先级：命令行参数 ≈ 环境变量 > config.json > 默认值。

环境变量 / 参数	config.json	默认	说明
`ZCODE_WEBUI_PORT` / `--port`	`port`	`3102`	监听端口
`ZCODE_WEBUI_BASE_PATH` / `--base-path`	`basePath`	空（根路径）	URL 前缀，如 `/zcode`（code-server 代理模式不要设置）
`ZCODE_WEBUI_WORKSPACE` / `--workspace`	`workspace`	`$HOME`	初始工作区目录
`ZCODE_WEBUI_LOCALE`	`locale`	`zh-CN`	界面语言
`ZCODE_WEBUI_OAUTH_PROXY` / `--oauth-proxy`	`oauthProxy`	空	OAuth 登录用的 HTTP 代理（服务器直连 `zcode.z.ai/api/v1` 不通时）
`ZCODE_WEBUI_HOST_PROXY` / `--host-proxy`	`hostProxy`	空	运行时/Agent 访问云与模型 API 的 HTTP 代理（`api.z.ai`、`open.bigmodel.cn` 不通时）
`ZCODE_SERVER_RUNTIME_ROOT`	`serverRoot`	`~/.zcode/server`	官方运行时目录（通常无需修改）
`ZCODE_HOME`	—	`~/.zcode`	官方数据/凭据目录（与官方 CLI 共用）
`ZCODE_WEBUI_HOME`	—	见右	本服务数据目录（config、渲染层、设备标识、日志）；npm 安装默认 `~/.zcode-webui`，git 部署且项目根已有 `config.json` 或 `vendor/renderer` 时沿用项目目录
`ZCODE_VERSION` / `ZCODE_ARCH`	—	`3.9.2` / `x64`	`fetch-renderer` 的下载版本与架构
`ZCODE_WEBUI_DETACHED_TTL_MS`	—	`1800000`	后台会话脱离超过该时长且无任务运行、无帧活动时回收；`0` = 永不回收
`ZCODE_WEBUI_FRAME_QUIET_MS`	—	`600000`	回收条件之一：最近该时长内无 host→浏览器帧
`ZCODE_WEBUI_RUNNING_TASK_STALE_MS`	—	`7200000`	回收的全局保险：索引里有窗口内的 running 任务时不回收任何会话
`ZCODE_WEBUI_DEBUG_RPC`	—	关	设 `1` 在日志打印协议消息预览（联调用）

命令行参考（npm 包）

命令	作用
`zcode-webui setup`	一键部署向导：目标版本解析 → 环境检查 → 官方运行时自动安装（缺失时，来自官方组件通道）→ 凭据检查 → 渲染层下载 → 写 `config.json`（0600）→ 可选 systemd 用户单元 → 启动并等健康检查通过。`--yes` 非交互全默认并启动（配 `--no-start` 只装不启）；其它参数 `--port/--workspace/--locale/--base-path/--oauth-proxy/--host-proxy/--server-root/--version/--arch/--fetch/--no-fetch/--systemd/--no-systemd`
`zcode-webui start`	前台启动（Ctrl-C 停止；参数透传给 server.mjs）
`zcode-webui stop`	停止后台实例或 systemd 服务（前台进程请 Ctrl-C）
`zcode-webui upgrade`	一键升级官方渲染层 + 官方运行时（见下节）
`zcode-webui fetch-renderer`	仅下载/更新渲染层（`ZCODE_VERSION`/`ZCODE_ARCH` 覆盖）
`zcode-webui doctor [--net]`	就绪检查：node/curl/dpkg-deb、运行时+agent 入口、凭据、渲染层、渲染层↔运行时版本对齐、服务状态；`--net` 附带连通性检查
`zcode-webui status`	打印健康 JSON（未运行返回非 0）
`zcode-webui version` / `help`	版本 / 帮助

所有可变数据存放在数据目录（~/.zcode-webui，可 ZCODE_WEBUI_HOME 覆盖；git 部署沿用项目目录），包目录保持只读。

一键升级

zcode-webui upgrade                    # 自动探测官网最新版，同步升级渲染层 + 官方运行时
zcode-webui upgrade --yes --restart    # 非交互，并在前后自动停/启服务

流程：从更新日志取最新版本号 → 重提取渲染层 → 下载官方组件清单中的运行时组件（逐一 SHA256 校验）在新目录组装后原子替换 （旧目录备份为 ~/.zcode/server.bak-<版本>-<时间戳>，仅留最近一份）。服务运行中默认询问是否先停（--yes 跳过询问但不停止）。其它参数：--version X.Y.Z（指定版本）、--arch x64|arm64、 --renderer-only / --server-only、--force（同版本强制重装）、--no-backup。注意：upgrade 只升官方组件；zcode-webui 自身用 npm update -g @aixyzstudio/zcode-webui 升级。

官方 CLI 直连（可选）

WebUI 服务本身不需要 CLI 配置。若想在终端里 headless 使用官方 CLI（与 WebUI 共用凭据与会话库）：

cp cli-config.example.json ~/.zcode/cli/config.json && chmod 600 ~/.zcode/cli/config.json
# 把 provider.bigmodel.options.apiKey 换成你的 Coding Plan API Key（或直接 zcode login 生成）

~/.zcode/server/node ~/.zcode/server/agents/glm/zcode.cjs \
  --cwd /path/to/workspace --prompt '列出当前目录的文件' --max-turns 1
# 续跑某个会话：加 --resume sess_xxx --prompt '继续'

密钥文件保持 0600 且在仓库之外；需要代理时设 ZCODE_HTTP_PROXY/ZCODE_NO_PROXY。

HTTP API

GET <base>/api/health — 服务状态（版本 / renderer / 运行时 / 登录态 / 会话数 / 回收开关）
POST <base>/api/sessions/terminate — 立即终止全部会话（含后台运行中的，慎用）
POST <base>/api/login/start · GET /api/login/status · POST /api/login/cancel — OAuth 登录流
POST <base>/api/login/import — 导入凭据 JSON（写入官方凭据库）
GET <base>/api/fs/list?path=<dir> — Web 目录选择器的目录列表
POST <base>/bridge/open · GET /bridge/poll · POST /bridge/send · POST /bridge/close — HTTP 长轮询桥
WS <base>/ws?token=<每次启动随机> — 前端协议桥

安全须知

服务默认监听 0.0.0.0 且自身不做用户鉴权（本地信任模型）：任何能访问端口的人都能以服务器上的 ZCode 账号身份运行 Agent。务必放在反代/网关之后（code-server 登录、SSO、basic auth 等），不要直接暴露公网。
/api/fs/list、/api/login/import、/api/sessions/terminate 能读文件系统/写凭据库/终止任务，同样依赖外层鉴权。
凭据写入 ~/.zcode/v2/credentials.json（0600）；config.json 不入库，不要提交含密钥的配置。
WS token 只是防误连其他 WS 服务，不是鉴权手段。

常见问题（FAQ）

Q：关闭标签页后任务还会继续吗？ 会，后台持续执行到完成或等待输入；重开页面自动查看进度（见「任务生命周期」）。空闲后台会话默认 30 分钟回收， ZCODE_WEBUI_DETACHED_TTL_MS=0 关闭回收，POST /api/sessions/terminate 立即清空。

Q：界面缩放？ Ctrl+滚轮或双指捏合（50%–200%，按浏览器记忆）；Ctrl/⌘ +/- 是浏览器整页缩放，两者并存。

Q：发送消息提示「当前没有可用的模型供应商和模型」？ 先确认 /login 已登录；再跑 zcode-webui doctor 看渲染层与运行时的版本对齐是否 ok（不一致就 zcode-webui upgrade 对齐）；仍报错说明是旧版本项目代码，请更新。

Q：OAuth 一直卡在「等待端点响应」？模型调用不通但登录正常？ 前者设置 oauthProxy、后者设置 hostProxy（环境变量或 config.json，二者可同用），指向出口可达的 HTTP 代理后重启服务。

Q：「添加项目 → 打开文件夹」没反应？ 允许本站弹窗即可；目录选择器是内置 Web 页面。

Q：经 code-server 打开白屏？ 用带尾斜杠的 /proxy/3102/（会自动重定向）；WS 不通会自动降级长轮询；可开 <base>/debug 自检页看桥接状态。

Q：点击会话提示 "ZCode agent server command is not configured"？ 官方运行时找不到 agent 入口。新版本启动 host 时已自动注入定位环境变量，出现该报错先跑 zcode-webui doctor（看 agent server 是否 ok），然后重启服务让新代码生效；自定义路径可用 ZCODE_AGENT_SERVER_COMMAND / ZCODE_AGENT_SERVER_ARGS_JSON 覆盖。

Q：官方界面怎么升级？ 直接 zcode-webui upgrade（见「一键升级」）。

Q：切到其他 App 再回来，页面重连/要求手动重连？ 这是手机浏览器在后台冻结页面并回收网络连接所致（并非服务端超时）。新版对此透明：后台掉线不再刷新页面，恢复时通过热重连直接接管同一个运行中的宿主——离线期间任务产生的输出会在恢复瞬间补投，全程无感、无需任何点击。页面回前台即自动恢复；仅当宿主进程本身退出（如服务重启）才需要一次自动刷新。服务端另加了 30 秒 ping/pong 保活，僵死连接会被及时清理、宿主干净转入后台。

Q：服务器休眠/断网后，进行中的任务停了？ 分两种情况：

其实还在跑（常见）：任何设备重新打开页面都会作为视图接入同一宿主——实时进度无缝续看，且多台设备可同时观看、互不刷新。只有「同时发任务指令」才可能双代理并发，请避免。
真的断了：挂起/断网掐断流式连接会让该回合以失败告终（服务日志可见 process stall of ~Ns）。可用官方 CLI 无头续跑： ~/.zcode/server/node ~/.zcode/server/agents/glm/zcode.cjs --cwd <工作区> --resume <会话ID> --prompt '继续'；刷新页面即加载最新落库状态。长任务期间请避免让服务器休眠。

Q：定时/闲时任务能跑吗？ 该调度器属官方桌面端专属；可在服务器上用系统 cron 调官方 CLI 的 --prompt/--resume 实现，按订阅规则计费。

测试

npm run smoke                            # 静态服务 + base path + WS/HTTP 双桥全链路冒烟
bash scripts/docker/verify.sh            # Docker 真机全链路：npm 包 → 自动安装 → 服务 → 冒烟 → 真实模型调用
ZCODE_VERIFY_FRESH_RUNTIME=1 bash scripts/docker/verify.sh   # 更严苛：容器里只有凭据、无官方运行时，
                                                             # 验证 setup 从零自动安装（CDN 组件下载 + SHA256 校验）

Docker 验证会把本机 ~/.zcode 复制进临时沙箱注入容器，用完即删；镜像层与仓库不含任何凭据。可用 ZCODE_VERIFY_SOURCE/PROXY/NETWORK/KEEP/SKIP_FETCH 覆盖默认行为。scripts/dev/ 下另有一组 Playwright 端到端脚本（真实登录态驱动官方界面的回归），可用 ZCODE_WEBUI_TEST_URL/TEST_DIR 指向自己的服务。

已知限制

不支持 SSH/WSL/Docker 远程工作区创建（服务本身就运行在你的工作区机器上）
手机 Remote Control、系统托盘、自动更新等桌面专属通道不可用（Browser Use 可走服务器无头 Chrome）
定时/闲时任务依赖桌面端调度器（见 FAQ）
服务进程重启会中断后台任务；HTTP 长轮询模式下重开页面不能无缝接管会话（结果仍可在任务面板看到）
官方界面随版本演进，个别新 UI 可能暂时兼容性问题；渲染层与运行时务必同版本

目录结构

src/server.mjs             HTTP 静态服务 + base path + WS 桥 + 登录 API + 会话管理
src/cli.mjs                zcode-webui 命令行（setup / start / stop / upgrade / doctor / status）
src/dirs.mjs               数据目录解析（ZCODE_WEBUI_HOME / 仓库模式）
src/frame.mjs              stdio 帧编解码（与官方运行时互通）
src/host.mjs               官方运行时进程拉起与握手
src/upgrade.mjs            版本探测 + 渲染层/官方运行时组件下载校验与原子替换
src/login.mjs              官方 CLI OAuth 登录子进程管理
src/rpclog.mjs             诊断日志（DEBUG_RPC 时使用）
web/bootstrap.js           浏览器侧：URL 参数、MessagePort↔WebSocket 桥、长轮询降级
web/zcode-bridge.js        window.zcode 浏览器适配层
web/{login,picker,debug}.html 等   登录页 / 目录选择器 / 自检页 / 凭据导出工具
config.example.json        服务配置模板（脱敏）
cli-config.example.json    官方 CLI 模型配置模板（脱敏）
scripts/fetch-renderer.sh  从官方 CDN 下载客户端并提取渲染层（vendor/renderer，不入库）
scripts/smoke-test.mjs     冒烟测试
scripts/docker/            Docker 真机全链路验证（verify.sh + container-verify.sh）
scripts/dev/*.mjs          Playwright 端到端联调脚本

许可证与声明

代码以 MIT 开源；
官方 ZCode 名称、商标与客户端版权归其权利方所有；本项目不包含、不分发任何官方客户端文件；
参考：ZCode 官方文档 · 智谱开放平台 · GLM Coding Plan。

Name		Name	Last commit message	Last commit date
scripts		scripts
src		src
web		web
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
cli-config.example.json		cli-config.example.json
config.example.json		config.example.json
package-lock.json		package-lock.json
package.json		package.json
zcode-service.sh		zcode-service.sh

Navigation Menu

Repository files navigation

zcode-webui

快速开始

与官方的关系：我们只做了中间层

手动部署（git clone）

与 code-server 协同（推荐）

登录与凭据（三种方式任选）

任务生命周期（重要，30 秒读完）

配置参考

命令行参考（npm 包）

一键升级

官方 CLI 直连（可选）

HTTP API

安全须知

常见问题（FAQ）

测试

已知限制

目录结构

许可证与声明

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

zcode-webui

快速开始

与官方的关系：我们只做了中间层

手动部署（git clone）

与 code-server 协同（推荐）

登录与凭据（三种方式任选）

任务生命周期（重要，30 秒读完）

配置参考

命令行参考（npm 包）

一键升级

官方 CLI 直连（可选）

HTTP API

安全须知

常见问题（FAQ）

测试

已知限制

目录结构

许可证与声明

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages