Web UI

CodeBuddy Code 提供内置的 Web UI，在浏览器中提供完整的交互界面。当您以 serve 模式启动或开启远程控制时，Web UI 自动可用。

概述

Web UI 提供与终端界面相同的核心能力，并针对浏览器进行了可视化布局优化：

• 对话：发送消息、查看对话、实时监控工具执行
• 编辑器：支持最多 4 个分组，可在分组间拖动文件或将终端停靠到编辑区
• 终端：内嵌终端，支持分屏布局（最多 4 个面板）和从资源管理器拖入文件路径
• Workers：管理 CLI Worker 进程和 Daemon 守护进程
• 日志：独立日志查看器，支持多种日志类型和关键词搜索
• 远程控制：连接微信和企业微信渠道
• 监控：系统资源指标和各 Worker 进程级内存/运行时间指标
• 任务：浏览任务模版，创建、编辑、暂停或恢复定时任务，并查看执行记录
• 插件：管理插件安装和插件市场
• 设置：配置主题、语言、模型、权限模式和主 Agent（标准 / PTC / 极简 / 创造）
• 文档：浏览 CLI 文档，支持全文搜索
• API 文档：查看交互式 Swagger UI，方便 HTTP API 探索

访问 Web UI

方式一：Serve 模式

使用 --serve 参数启动 CodeBuddy Code：

codebuddy --serve --port 7890
# 新对话盖章进程默认（不写 settings.json）：
codebuddy --serve --agent ptc --permission-mode bypassPermissions

然后在浏览器中打开：

http://127.0.0.1:7890

标准模式请显式传 --agent cli，不要指望 lastUsed 或默认 chip。minimal 不要配 --permission-mode plan。

方式二：远程控制

在已有的 CodeBuddy Code 会话中启动 Gateway：

/gateway

终端会显示二维码和 URL。用手机扫码或在浏览器中打开 URL。详见远程控制文档。

Serve 启动：模式与权限

进程默认，不写 settings。--agent 压过 chip lastUsed，以及续接会话上的 leftover 四模式 / cli 站立键。不抢自定义 @agent。

codebuddy --serve --agent <模式> --permission-mode <权限>

本机调试常见写法（--auth none 只给本机 / CI，不要对公网这么开）：

codebuddy --serve --agent ptc --permission-mode bypassPermissions --auth none --open

--agent 四种 shipped

值	界面	对话层	说明
cli	标准模式	原生全工具（Bash / Read / Grep…）	什么都不加时的默认；要标准模式请显式传它
ptc	PTC	只有 REPL，沙箱里全量	Code Mode
minimal	极简	只有 REPL，沙箱 Bash / Edit / Skill（无 MCP）	无 Read / Glob / MCP；prompt 与注入不教这些工具
create	创造模式	与标准同一套工具	多写自定义 agent 的提示

也可以是自定义 id（.codebuddy/agents/<name>.md 的 name）。

multitask 不是 --serve / Web UI 的启动值：入口守卫会拒，进程非 0。协调器在会话内用 /multitask（交互 TUI）或 session/set_config_option（configId=multitask）。

--permission-mode

help 写的是前 6 个；运行时还认 fullAccess。

值	含义
default	默认：按规则问
acceptEdits	编辑自动过，其它仍问
bypassPermissions	跳过权限确认
plan	Plan 模式。minimal + plan 会 400，不要这么配
dontAsk	不问，该拒就拒
auto	自动分类
fullAccess	运行时允许，help 里没列；语义接近 bypassPermissions

相关（一般不用）：

--permission-mode-before-plan <mode>   退出 plan 回到哪个权限
--subagent-permission-mode <mode>      子代理/队友权限，不继承主会话

完整语义见 权限模式。

四模式 × 常用权限

# 标准 + 默认权限
codebuddy --serve --agent cli --permission-mode default --auth none --open

# 标准 + 跳过权限
codebuddy --serve --agent cli --permission-mode bypassPermissions --auth none --open

# PTC + 跳过权限
codebuddy --serve --agent ptc --permission-mode bypassPermissions --auth none --open

# PTC + 默认权限
codebuddy --serve --agent ptc --permission-mode default --auth none --open

# 极简 + 跳过权限（不要加 --permission-mode plan）
codebuddy --serve --agent minimal --permission-mode bypassPermissions --auth none --open

# 创造 + 跳过权限
codebuddy --serve --agent create --permission-mode bypassPermissions --auth none --open

同条上的其它开关

旗标	取值	说明
--serve	无参	HTTP + Web UI
--open	无参	ACP 起来后再开浏览器
--auth	password（默认）/ none	本机调试用 none
--base-path	如 /cnb-5gg-1k09dqp5v-001	把 Web UI / API 挂到固定 path 下。也可用 CODEBUDDY_GATEWAY_BASE_PATH
--host	默认 127.0.0.1	绑全接口再显式 --host 0.0.0.0
--port	数字	不写则自动选

设置 --base-path 后，浏览器请打开带前缀的地址（启动日志里的 Web UI 行），例如 http://127.0.0.1:8321/cnb-5gg-1k09dqp5v-001/。此时 PWA 会关闭，避免 Service Worker 仍按站点根缓存。

认证方式

Web UI 支持两种认证模式：

模式	设置	说明
密码认证（默认）	--auth password / CODEBUDDY_GATEWAY_AUTH=password	--serve 的默认行为，启动时终端打印密码和带密码的可点链接
免认证	--auth none / CODEBUDDY_GATEWAY_AUTH=none	显式关闭，启动时打印警告。同机任意进程可经此服务执行命令、读写文件，仅建议在隔离环境或 CI 中使用

认证方式（以下任一方式均可）：

• URL 参数：?password=xxx — 打开 Web UI 首页时自动登录并下发 Cookie（仅首页有效，对 /api/v1/* 端点无效）
• 登录页面：输入终端显示的密码
• Bearer Token：Authorization: Bearer <password>，用于 API 访问
• Cookie：gateway_session，浏览器登录后自动携带，有效期 30 天

在 ~/.codebuddy/settings.json 中配置：

{
  "gateway.auth": "none"
}

功能详解

对话视图

默认视图，用于与 Agent 交互。核心功能：

• 富文本消息渲染：Markdown、语法高亮代码块、表格、图片、Mermaid 图（流程图 / 时序图 / 状态图等，主题跟随浅色深色；流式输出时先按代码块展示，围栏闭合后自动替换成图；图上可复制源码或导出 SVG）
• 媒体预览：对话中的本地 SVG 图片会直接渲染，MP4、WebM、M4V、MOV、OGV、AVI 和 MKV 文件提供内联视频播放器。远程工作区的文件通过鉴权接口加载，仍在本地浏览器中预览。
• 嵌套围栏示例预览：标注 markdown 的代码块里再包一层围栏时（演示 markdown 片段），外层按示例展示：普通文本原样保留、内层围栏按自己的语言语法高亮，复制仍取整段原文
• 复制与导出：模型输出、用户消息、频道来信、代码块、工具调用的参数与结果都提供一键复制；Markdown 表格可复制为 Markdown 或 TSV，Mermaid 图可复制源码或导出 SVG；右上角支持整轮对话导出为 Markdown / JSON（JSON 保留完整时间线）。输入 /export 可下载当前会话的 ZIP 归档，包含对话记录及可用的会话日志；共享工作区日志只收录含当前会话 ID 的行。归档可能包含提示词、本地路径和敏感信息，分享前请检查。复制类按钮在触屏与窄屏下常驻显示。
• 工具执行展示：内联查看工具调用、参数和结果
• 权限管理：在浏览器中直接批准或拒绝工具权限
• 问答面板：回答 Agent 的多选问题
• 任务进度：实时监控后台任务和 Team 进度
• 完成与待处理通知：回合完成、后台任务结束或 Agent 等待权限与问题回答时，可通过桌面系统通知提醒；连接远程工作区时通知仍发送到当前桌面。权限按钮和复制请求 ID 按钮提供悬停提示。
• 会话管理：新建对话、浏览历史、切换会话
• 工作目录管理：添加/移除附加工作目录，扩展 Agent 的文件访问范围。工作目录与智能体模式统一显示在输入卡片顶部；新会话可选择，会话开始后显示只读状态。
• 主 Agent：空白会话可切换 cli / ptc / minimal / create 或自定义智能体。chip 选择写入 codebuddy.mainAgent.lastUsed，不改 default。进程 --agent 压过 lastUsed。已有历史的会话锁定当前 Agent。TUI 对等入口是 /agent-mode；选择会记住；开聊后锁定。WorkBuddy 不展示、不解析。
• 右侧工作台：资源管理器、文件搜索、源代码管理、文件编辑和终端使用独立工具标签，可一键全屏并拖拽调整宽度；窄面板会自动切换文件树与编辑区布局，并隐藏编辑器 minimap。对话中的文件路径支持跳转到指定行或行号范围；普通点击 URL 会在工作台安全预览，Cmd/Ctrl 点击会在浏览器新标签打开；本地 HTML 文件可在源码与安全预览之间切换。编辑器、预览和文件树可以把当前文件下载到本地。
• 目标：输入 /goal 或从输入框进入目标模式，可设置进行中目标。暂停会立刻卸掉续跑并掐当前回合，目标条保留为已暂停；继续后按同一条件重新启动。垃圾桶清除目标并收起目标条。

编辑器视图

Web IDE 编辑区支持多分组工作流：

• 分组布局：将文件或终端标签拖到编辑区边缘，可横向或纵向拆分，最多创建 4 个分组
• 跨组拖拽：文件标签可在不同分组间移动并重新排序
• 终端停靠：终端标签可在底部面板与编辑器分组之间拖动，迁移时保留当前 PTY 会话
• 布局恢复：刷新页面后恢复分组结构、激活标签和分隔比例

终端视图

基于 xterm.js 的内嵌终端：

• 分屏布局：支持水平和垂直分屏，最多 4 个面板
• 独立会话：每个面板有独立的 PTY 会话
• 持久连接：终端会话在页面刷新后保持
• 自适应调整：窗口大小变化时面板自动调整
• 文件路径拖放：将资源管理器中的文件拖入终端，可按当前系统的 shell 规则自动转义并粘贴路径

文档视图

在 Web UI 中直接浏览 CLI 文档：

• 全文搜索：基于 MiniSearch 搜索所有文档
• 多语言：自动跟随 UI 语言设置（中文/英文）
• 目录导航：根据文档标题自动生成，带滚动追踪
• 内部跳转：文档链接在查看器内导航（SPA 模式）
• API 文档：快速链接到 /api/docs 的交互式 Swagger UI

实例管理

管理多个 CodeBuddy Code 实例：

• 实例列表：查看所有运行中的实例及其工作目录和状态
• 快速切换：一键切换实例
• 手动添加：通过 URL 添加远程实例
• 隧道支持：通过 Cloudflare Tunnel 访问实例

AI 同事通讯录

Web UI 的侧栏只有一个工作台：AI 同事通讯录，不再提供「单干 / 组队」模式切换。

• 默认 CodeBuddy：通讯录顶部的默认 CodeBuddy 打开的就是主对话 Session，和以前的普通对话是同一份历史。
• AI 同事：每个同事名下有自己的 Job / Session 历史，彼此独立；无主 Job 照常列在通讯录里。
• 自主组队开关：设置页「AI 同事 → 允许 Agent 自主组队」（codebuddy.agentHome.orchestration）只控制 Agent 能否自主创建和联系同事、使用频道任务板、唤醒成员。关闭后通讯录与已有同事、频道、Job 都保留；频道页会提示「同事不会被唤醒、任务板只能查看」并提供去设置开启的入口。被环境变量锁定时开关置灰并说明原因。
• 回退：Agent Home 被总闸或运维回滚键关闭、或连接的是不支持该接口的旧后端时，侧栏回落为普通会话 / Job 列表。
• 入口边界：组队工具与上下文只给 Web UI 发出的轮次和 AI 同事的 Job。终端里起的会话拿不到；在 Web UI 聊过的 Session 回到同一个终端继续时，终端发出的那一轮同样拿不到（关掉浏览器也一样），Web UI 再次发话时恢复。WorkBuddy、IDE ACP、-p 与 SDK stream-json 不受影响。

后台会话

Web UI 的 Agent View 直接使用 /api/v1/jobs 管理后台 agent；外部 worker 由独立的 Workers 视图管理，不混入 jobs 列表。

• 项目列表：按工作目录分组，支持置顶、项目分组、搜索和完成通知；运行中的 job 用动态指示，等待输入的 job 显示需要输入提示。
• 派发新会话：可选择主 Agent（与对话栏同一份目录：内置四种模式 + 自定义）、模型、思考强度、启动权限、启动目录、自定义名称和 shell 模式，并支持图片与文件附件。请求体字段：agent、model、effort、permissionMode、sourceSessionId（继承受限上下文）、bgIsolation（none / worktree，省略时跟随全局设置）。GET /api/v1/jobs/dispatch-context 返回 defaultAgentName、agents、permissionMode（进程 --permission-mode）。minimal 不能与 permissionMode=plan 同用。
• 右键操作：停止、重启、置顶/取消置顶、重命名、移出项目、复制会话 ID、复制工作目录和删除。
• 会话恢复：重启 job 会恢复其 session；浏览器重新打开时，主 Web UI 使用持久化的 session ID 加载历史，失败后才回退到 continue 选择。打开已有子智能体时保持当前画面和输入框，不整页刷新；历史回放完成前继续显示上一屏。地址栏带会话 ID 时，短暂的 load 失败会重试，不会另开新会话。子智能体运行中改模型会记在该实例上，重启后沿用，不改主对话默认模型。
• 内嵌对话：父网关同源 iframe 池化打开后台 agent。页面由父网关出 SPA，ACP / 目标 / internal API 经 /api/v1/jobs/:id/frame/ 反代到该 job 的 loopback；storage、auth、jobs 仍由父网关处理。iframe src 不携带网关密码。各页输入框独立；恢复时只在卸帧瞬间搬草稿，不共用一份输入。
• 频道与私信：频道回执按频道认，不画成「消息来自 user」；1:1 输入框 @ 只做补全。用户在频道发言后，被叫醒的人头像马上显示在忙；默认 Agent 不进花名册、不吃 @所有人 未读。
• 对话数据：GET /api/v1/jobs/:id/transcript 一次性返回最近最多 1000 行 ACP replay updates；GET /api/v1/jobs/:id/stream 先回放 transcript 尾部，再通过 SSE 尾随新输出。
• 生命周期：支持 reply、stop、respawn 和 delete。删除可能因前台持有或 worktree 守卫返回 { deleted: false, reason }，UI 会保留该 job 并提示原因。
• 实时更新：列表通过 /api/v1/jobs/events 接收 snapshot、added、changed、removed 和 keepalive 事件，无需手动刷新。

完整端点、字段、错误码和 curl 示例见 HTTP API — Jobs。

设置

• 主题：浅色、深色或跟随系统（自动检测）
• 语言：中文、英文或跟随系统（自动检测）
• 模型：从可用选项中选择 AI 模型
• 权限模式：默认、接受编辑、跳过权限或规划模式
• 主 Agent：总闸 codebuddy.mainAgent.enabled（缺省开）；「允许未声明宿主」allowUnopted（缺省关，WorkBuddy 保持原生 cli）；管理页可设 default、用 AI 创建自定义智能体。chip / TUI /agent-mode 选择只写 lastUsed。

中继 Web 访问（浏览器 / 手机直接打开）

主机管理页「中继隧道」除了打通内网设备之间的 SSH，还可以把本机 Web UI 绑定到中继网关的固定子路径，在任何能访问网关的浏览器或手机上直接打开，不需要访问端安装任何东西。iOA 账号默认使用内置网关 http://frp.devcloud.woa.com。

1. 在网关卡片的「Web 访问」点「新建绑定」，在弹窗里填写子路径（留空随机生成 10 位，输入时实时检查是否被占用）、选择访问方式、按需开启访问密钥、填写允许访问的其他 iOA 账号（可选），点「绑定」。弹窗在手机上铺满全屏。
2. 弹窗里直接给出最终地址 http://frp.devcloud.woa.com/w/<子路径>/，可复制或扫码；列表每行也有复制、二维码和「设置」（打开同一个弹窗修改访问方式、密钥和名单，子路径只读）。
3. 浏览器打开后按访问方式校验：
   • iOA 登录（默认）：用 iOA 账号登录（复用 CodeBuddy 登录页）。能访问的是绑定所有者（同一个 iOA 身份）和白名单里的 iOA 账号，其他人登录后看到「没有访问权限」。
   • 仅凭密钥：免登录，访问密钥强制开启。打开带密钥的完整链接直接进入页面；没带密钥只看到密钥输入页。拿到完整链接的人都能打开，请妥善保管；白名单在这种方式下不生效。

规则：

• 子路径：3-48 位小写字母、数字或连字符，在网关上全局唯一；输入时会实时检查，已被占用（包括别人的绑定）时无法绑定，api、admin、console 等保留字不可用。
• 白名单（可选，默认仅本人，仅 iOA 登录方式生效）：绑定时或在「设置」里填写允许访问的其他 iOA 英文名（如 runpeihe，逗号分隔，最多 50 个）。对方用自己的 iOA 登录即可，不需要开通中继账号；开启访问密钥时对方同样需要密钥。移出名单后立即失效。同账号的任一设备都可以修改名单。
• 访问密钥（可选）：开启后需要密钥才能打开。「复制完整链接」给出带 ?relay_key=<密钥> 的地址；已登录时网关直接校验密钥并进入页面（不会先出现密钥输入页），同时把密钥按子路径存进该浏览器的 localStorage、从地址栏清掉，之后不带 query 也能直接访问。可随时关闭或「换密钥」（已保存旧密钥的浏览器需要重新打开完整链接）。密钥原文只保存在创建它的设备上，网关只存哈希。
• 鉴权分工：iOA 登录、所有者 / 白名单、访问密钥都由网关校验；网关转发时带上本机生成的 relay token，本机据此识别来自网关的请求、免去 Web UI 密码，并以 /w/<子路径> 作为页面前缀。直连网关上的中继端口会被拒绝，只能经 /w/<子路径>/ 访问。
• 在线状态：绑定跟随本机 CodeBuddy Code 进程，重启后自动恢复；本机未运行时访问者看到「设备离线」页并自动重试。解除绑定后地址立即失效、子路径被释放。
• 同一网关账号下其他设备创建的绑定会显示为「其他设备」，可以复制链接、修改访问名单或解除绑定，但不能修改其访问密钥。

网关的管理员可在 http://frp.devcloud.woa.com/console 查看服务状态并管理全部账号、隧道、Web 绑定与浏览器会话。

API 文档

HTTP 服务运行时，可在以下地址访问交互式 API 探索器：

http://127.0.0.1:{PORT}/api/docs

Swagger UI 提供以下功能：

• 浏览所有可用的 REST API 端点
• 查看请求/响应 Schema
• 直接在浏览器中测试 API 调用
• 在 /api/openapi.json 下载 OpenAPI 3.1 规范

完整的 API 参考请见 HTTP API 文档。

移动端支持

Web UI 完全响应式，支持移动设备：

• 侧边栏：小屏幕上折叠为滑出式抽屉
• PWA 支持：添加到主屏幕获得类原生应用体验
• 触控优化：所有交互针对触摸操作优化
• 扫码访问：终端扫码即可在手机上打开
• 中继 Web 访问：经中继网关的 /w/<子路径>/ 在手机上打开本机 Web UI，见中继 Web 访问

快捷键

快捷键	操作
Enter	发送消息
Shift+Enter	输入换行
Escape	停止运行中的 Agent

技术细节

• 框架：React 18 + Zustand 状态管理
• 通信：ACP 协议，基于 HTTP/SSE（非 WebSocket）
• 样式：Tailwind CSS + CSS 变量主题
• 终端：xterm.js + fit addon
• 搜索：MiniSearch 客户端全文搜索
• Markdown：react-markdown + remark-gfm + 语法高亮；Mermaid 图按需动态加载（只在消息里出现 mermaid 代码块时拉取，不增加首屏体积）

相关文档

• 远程控制 — 通过 Gateway 和 Tunnel 启动 Web UI
• HTTP API — 完整的 REST API 文档
• ACP 协议 — IDE 集成的 Agent Client Protocol
• 权限模式 — --permission-mode 语义
• CLI 参考 — --agent / --serve 参数
• 设置 — 配置选项