Claude Web Chat

中文

English

中文

English

Appearance

Claude Web Chat — 用户操作手册 ​

基于 Claude Code 的 Web 交互界面，提供 Chat 模式（一对一 AI 对话）和 Crew 模式（多 Agent 团队协作）。

语言切换: English

目录 ​

快速开始 ​

Claude Web Chat 由两部分组成：

  1. Server（服务端） — 本项目的 Web 应用，部署在你的服务器上。
  2. Agent（代理） — CLI 工具（@yeaft/webchat-agent），安装在运行 Claude Code 的机器上。Agent 通过 WebSocket 连接到服务端，执行 Claude Code 命令。

部署服务端后，你需要：

  1. 使用账号密码登录
  2. 安装并连接至少一个 Agent（参见 Agent 安装与连接）
  3. 开始对话或创建 Crew Session

Chat 模式 ​

Chat 模式提供与 Claude 的一对一对话界面，类似于在终端中使用 Claude Code，但通过 Web UI 操作。

创建会话 ​

有两种方式创建新会话：

  1. 欢迎页面 — 未选择会话时，欢迎页面会显示"新建会话"按钮（仅在有 Agent 在线时可见）。
  2. 侧边栏 — 点击"最近聊天"旁边的"+"图标，或在折叠侧边栏中点击"+"按钮。

创建会话时需要选择：

  • Agent — 运行 Claude Code 的机器
  • 工作目录 — 对话使用的项目文件夹路径

发送消息 ​

  • 在底部文本区域输入消息
  • 按 Enter 发送（使用 Shift+Enter 换行）
  • 点击发送按钮发送
  • 助手处理期间会显示停止按钮，可随时取消执行
  • 支持草稿保存 — 切换会话时，未发送的文本会自动保存，切回时恢复

文件和图片上传 ​

你可以在消息中附加文件：

  • 点击输入区域旁的回形针图标（📎），或使用文件选择器
  • 直接从剪贴板粘贴图片（Ctrl+V / Cmd+V）
  • 支持的文件类型：图片（image/*）、文本文件、PDF、Word 文档（.doc、.docx）、Excel（.xls、.xlsx）、JSON、Markdown、Python、JavaScript、TypeScript、CSS、HTML
  • 文件先上传到服务端，然后附加到消息
  • 图片附件在发送前显示缩略图预览
  • 发送后，附件以可折叠标签显示（如"📎 2 张图片, 1 个文件"）— 点击展开查看

图片预览 ​

点击消息中的任意图片附件可打开全屏预览浮层：

  • 图片居中显示在深色背景上
  • 点击背景区域（图片外的暗色区域）关闭
  • 按 Escape 键关闭
  • 浮层有平滑的淡入/淡出过渡动画

斜杠命令 ​

在输入区域输入 / 可查看可用的斜杠命令及自动补全：

  • /compact — 压缩会话上下文（详见下文）
  • /clear — 清除所有消息
  • /context — 显示上下文信息
  • /cost — 显示 token 用量和费用
  • /init — 初始化项目
  • /doctor — 运行诊断
  • /memory — 管理 Claude 的记忆
  • /model — 切换模型
  • /review — 代码审查
  • /mcp — MCP 服务器管理
  • /skills — 列出可用技能

使用方向键导航自动补全菜单，Tab 或 Enter 选择命令。

Compact 与 Clear 的区别 ​

聊天头部提供两个会话管理操作：

Compact（↕ 压缩图标） ​

  • 作用：向 Claude 发送 /compact 命令，将对话历史总结压缩为简洁形式，减少 token 使用同时保留上下文。
  • 使用时机：当上下文百分比较高（50%+）且你希望继续对话而不丢失上下文时。
  • 效果：UI 中消息仍然可见，但发送给 Claude 的底层上下文已被压缩。处理过程中会显示"正在压缩..."状态条，完成后显示"压缩完成"。
  • 压缩期间输入区域被禁用。

Clear（🗑 清除图标） ​

  • 作用：向 Claude 发送 /clear 命令，删除当前会话的所有消息并重置上下文。
  • 使用时机：当你想在同一会话中重新开始时。
  • 确认：清除前会弹出确认对话框。
  • 效果：所有消息被移除。状态条显示清除进度。

会话恢复 ​

如果服务器重启或连接中断，你的会话可以恢复：

  • 点击聊天头部的刷新按钮（↻ 图标）重新从 Agent 同步消息
  • 系统会加载会话的最近 5 轮对话
  • 消息加载时会显示加载遮罩

上下文用量指示器 ​

聊天头部右上角有一个百分比徽章，显示当前上下文窗口使用量：

  • 绿色（0-49%）：上下文使用健康
  • 黄色（50-79%）：建议尽快压缩
  • 红色（80%+）：上下文接近满载，建议立即压缩

悬停在徽章上可查看精确的 token 数量（如"Context: 45k / 200k"）。

助手回复功能 ​

Claude 的回复以"Turn"形式渲染，包含丰富的功能：

  • Markdown 渲染 — 支持语法高亮的代码块
  • 复制按钮 — 每条回复都有复制按钮，可复制文本内容
  • 代码块复制 — 每个代码块有独立的复制按钮和语言标签
  • 工具使用展示 — 显示 Claude 使用了哪些工具（文件读取、编辑、搜索等）
    • 最新的工具操作始终可见
    • 之前的操作折叠在"还有 N 个"切换按钮后面
  • Todo 进度 — 当 Claude 使用 TodoWrite 工具时，会显示任务清单，包含对勾（✓）、旋转图标和状态
  • 交互式提问（AskUserQuestion） — 当 Claude 提问时，会显示交互卡片：
    • 预定义选项供选择（单选或多选）
    • 自定义文本输入框可自由回答
    • 提交按钮发送你的回复
    • 已回答的问题显示已选的答案

Crew 模式 ​

Crew 模式支持多 Agent 团队协作，多个 AI Agent 作为一个团队协同工作，各有角色分工，由 PM（项目经理）Agent 统一管理和协调。

创建 Crew Session ​

  1. 在侧边栏点击 Crew Sessions 旁的"+"图标
  2. 打开 Crew Session 配置面板：

第一步：选择 Agent

  • 选择一个在线且支持 Crew 模式的 Agent（必须具备 crew 能力）
  • 下拉菜单中只会显示支持 Crew 的 Agent

第二步：设置工作区

  • 输入或浏览选择项目目录
  • 这是 .crew 文件夹将被创建的根目录
  • 如果 .crew 目录已存在，你会看到恢复上一次 Session 或删除配置重新开始的选项

第三步：配置团队

  • 输入团队名称（可选，最多 30 个字符）
  • 选择团队模板或从零开始

第四步：启动

  • 点击启动按钮初始化 Crew Session
  • 初始化进度指示器显示"正在准备角色..." → "正在设置工作区..."

团队模板 ​

提供四种内置模板，每种都有预配置的角色：

模板描述角色
开发团队软件开发团队PM、开发者、审查者、测试者、设计师
写作团队创意写作团队定制的写作角色
交易团队金融交易团队交易相关角色
短视频团队短视频制作团队视频制作角色
自定义空白角色列表无预定义角色

模板提供中文和英文两个版本，根据 UI 语言设置自动选择。

角色配置 ​

每个角色具有以下属性：

属性描述
图标Emoji 或短文本（最多 4 个字符），作为角色头像显示
显示名称UI 中显示的角色名称
描述对角色职责的简要说明
决策者单选按钮 — 每个团队只有一个决策者（★ 星标）。此角色负责协调团队。
自定义 Prompt高级设置 — 为此角色添加额外的 CLAUDE.md 指令
并发数对于开发者、审查者、测试者角色：设置并行实例数（1-3）。审查者和测试者自动跟随开发者的并发数。

添加角色：

  • 点击"添加角色"打开内置角色选择器
  • 可用预设角色：PM、开发者、审查者、测试者、设计师、架构师、运维、研究员
  • 部分角色有捆绑关系（如添加开发者会同时添加审查者和测试者）
  • 也可以通过"自定义角色"选项创建完全自定义的角色

移除角色：

  • 点击角色卡片上的"×"按钮移除
  • 如果被移除的角色是决策者，则第一个剩余角色自动成为新的决策者

使用 Crew ​

Crew Session 运行后：

发送消息：

  • 在底部输入区域输入消息
  • 使用 @ 提及特定角色（如 @pm 请创建一个任务...）
    • 自动补全菜单显示可用角色
    • 使用方向键导航，Enter 选择
  • 按 Enter 发送，Shift+Enter 换行

消息展示：

  • 消息按 Feature 线程分组（按任务组织的可折叠区块）
  • 每个 Feature 线程显示：
    • 任务标题作为头部
    • 状态指示器（进行中 / 已完成）
    • 正在处理该任务的活跃角色（角色图标）
    • "查看历史"切换按钮查看旧消息
    • 最新消息始终可见
  • 全局消息（没有任务 ID 的消息）直接显示在 Feature 区块外
  • Round 分割线标记对话进入新一轮
  • 底部的最新消息区域显示任意角色最近的一条消息

状态栏：

  • 输入区域上方的状态行显示：
    • Round 编号（R0、R1、R2...）
    • 费用（美元）
    • 总 token 数

Feature 与任务管理 ​

Feature 面板（右侧边栏）展示看板风格的任务板：

总进度：

  • 顶部进度条显示整体完成度（如"3 / 5 — 60%"）

进行中区域：

  • 每个活跃 Feature/任务显示为一张卡片
  • 每张卡片包含：
    • 任务标题
    • 进度条（已完成 / 总数）
    • 正在处理的活跃角色（角色图标）
    • 创建以来的耗时
    • 可展开的 todo 列表，显示各个步骤
  • 点击卡片标题展开/折叠 todo 列表
  • 双击卡片跳转到消息流中对应的 Feature

已完成区域：

  • 默认折叠 — 点击标题展开
  • 显示已完成的 Feature 及其最终进度和总耗时

面板布局 ​

桌面端（>768px）：

  • 三栏布局：角色面板（左）| 消息区（中）| Feature 面板（右）
  • 两个侧面板可通过头部按钮切换显示/隐藏（人物图标 = 角色面板，图表图标 = Feature 面板）
  • 面板隐藏时，消息区域自动扩展填满空间

移动端（≤768px）：

  • 单栏布局 — 默认只显示消息区域
  • 点击头部的角色或 Feature 按钮打开对应面板（侧滑抽屉）
  • 点击遮罩背景关闭抽屉
  • 抽屉内部也有"关闭"按钮

Session 控制 ​

角色面板操作（角色面板底部）：

  • 添加角色（+）— 向运行中的 Session 添加新角色
  • 清理 Session（×）— 清除所有消息并重置 Session（需确认）
  • 停止全部（⏹）— 停止所有正在运行的角色进程

单个角色操作（角色卡片上）：

  • 中止（⏹）— 停止此角色的当前任务（仅在角色活跃处理时可见）
  • 清除（🗑）— 清除此角色的聊天记录

Crew 设置 — 通过头部齿轮按钮访问：

  • 编辑团队名称
  • 在运行中的 Session 中添加/移除角色
  • 通过"应用更改"按钮立即生效

Workbench 工作台 ​

Workbench 是集成在聊天体验中的开发工具侧面板，显示在聊天区域右侧，支持三个标签页。

访问 Workbench ​

  • 点击侧边栏头部的 Workbench 图标（面板布局图标）
  • 可以最大化以获得更多屏幕空间，或折叠隐藏
  • 拖动左边缘的调整手柄调节面板宽度
  • 可用标签页取决于 Agent 的能力（terminal、file_editor）

Terminal 终端 ​

Terminal 标签页提供连接到 Agent 机器的集成终端：

  • 分屏 — 水平分割（─）或垂直分割（│），可同时运行多个终端
  • 关闭面板 — 关闭当前活跃的终端面板
  • 自动创建 — Agent 运行命令时自动创建终端
  • 点击终端面板使其成为活跃状态（高亮边框）
  • 基于 xterm.js 的完整终端模拟

Files 文件管理 ​

Files 标签页提供类似 VS Code 的文件浏览器和编辑器：

文件树（左栏）：

  • 层级目录树，支持展开/折叠
  • 根据文件类型显示文件/文件夹图标
  • 搜索 — 按文件名过滤（Ctrl+P 快速打开）
  • 新建文件 / 新建文件夹 — 通过工具栏按钮创建
  • 删除 / 移动 — 选择文件后使用操作工具栏
  • 刷新 — 重新加载目录树
  • 全部折叠 — 折叠所有展开的目录
  • 打开文件夹 — 通过文件夹选择器更改根目录
  • 拖放上传 — 从桌面拖放文件到文件树区域上传

编辑器（右栏）：

  • 多标签编辑器，支持语法高亮
  • 查找与替换 — 文件内搜索
  • 支持多种文件类型：代码、Markdown、图片、Office 文档
  • Office 文档可选择本地预览或通过 Office Online 预览（在设置中配置）
  • 字体大小 — 使用 Ctrl+滚轮 调整文件树字体大小

Git 版本控制 ​

Git 标签页提供可视化的 git 状态查看器：

  • 分支显示 — 显示当前分支名和已更改文件数
  • Push 按钮 — 推送提交到远程（显示领先提交数）
  • 文件列表 — 显示已暂存和未暂存的变更及状态指示器
  • Diff 查看器 — 并排或统一模式查看选中文件的差异
  • 暂存/取消暂存 — 在暂存和未暂存之间切换文件
  • 提交 — 编写提交消息并提交暂存的更改
  • 工作目录 — 通过文件夹选择器选择要查看的仓库

Port Proxy 端口代理 ​

Port Proxy 允许你通过 Web UI 访问 Agent 机器上运行的服务：

  • 添加端口 — 指定 Agent、主机、端口号和可选标签
  • 开关 — 使用开关启用/禁用各个端口代理
  • 在浏览器中打开 — 点击可在新标签页中打开代理的服务
  • 复制 URL — 点击 URL 复制到剪贴板
  • 可从侧边栏（折叠模式）和 设置 → 代理 标签页访问

侧边栏提供导航和会话管理功能。

Agent 管理 ​

侧边栏顶部的 Agent 状态区域显示：

  • 在线数量 — 已连接 Agent 的数量（如"2 Agent"）
  • 延迟指示器 — 当前 Agent 的彩色编码 ping 延迟
  • Agent 下拉菜单 — 点击展开完整 Agent 列表：
    • 每个 Agent 显示：名称、版本、延迟、在线/离线状态
    • 升级按钮（↑）— 远程升级 Agent 到最新版本
    • 重启按钮（↻）— 远程重启 Agent 进程

会话列表 ​

侧边栏分为两个区域：

最近聊天：

  • 列出所有 Chat 模式的会话
  • 显示：会话标题（从内容或文件夹名推导）、时间戳、工作目录、Agent 名称、延迟
  • 点击会话切换
  • 点击"×"按钮删除会话
  • 处理中的会话有闪烁的绿点指示

Crew Sessions：

  • 列出所有 Crew 模式的 Session
  • 显示：团队名称、时间戳、工作目录、Agent 名称
  • 每个条目有团队图标（👥）以区分普通聊天

折叠模式 ​

点击折叠按钮（⟵）将侧边栏最小化为图标栏：

  • 菜单图标 — 展开侧边栏
  • 代理图标 — 切换端口代理面板
  • 工作台图标 — 切换 Workbench 面板
  • + 图标 — 新建会话
  • Crew 图标 — 新建 Crew Session
  • 主题图标 — 切换亮色/暗色模式

Settings 设置 ​

通过侧边栏底部的齿轮图标（⚙）访问设置。

通用设置 ​

  • 主题 — 在亮色模式和暗色模式之间切换
  • 语言 — 在中文和 English 之间切换
  • Office 预览模式 — 选择"本地渲染"（内置查看器）或"Office Online"（Microsoft Office 在线查看器）来预览 Office 文档

账户 ​

  • 用户名 — 你的登录用户名（只读）
  • 角色 — 你的账户角色：Pro 或 Admin（只读）
  • 邮箱 — 你的邮箱地址（如已设置）
  • 退出登录 — 登出账户

安全与 Agent Key ​

Agent Key：

  • 用于认证连接到服务器的 Agent 的密钥
  • 点击眼睛图标显示/隐藏密钥
  • 点击复制图标复制密钥到剪贴板
  • 点击重置密钥生成新密钥（需确认 — 所有已连接的 Agent 都需要更新密钥）

安装命令：

  • 获取 Agent Key 后，会显示两条命令：
    1. npm install -g @yeaft/webchat-agent — 全局安装 Agent CLI
    2. yeaft-agent install --server <你的服务器URL> --secret <你的密钥> — 安装为系统服务

修改密码：

  • 输入当前密码、新密码（最少 6 个字符）和确认密码
  • 点击"修改密码"更新

邀请码管理 ​

仅 Admin 可用

管理员可以为新用户创建邀请码：

  • 创建 — 选择角色（Pro）并点击"+"按钮生成邀请码
  • 邀请码列表 — 显示所有邀请码，包括：
    • 邀请码字符串
    • 角色标签
    • 状态：可用 / 已使用 / 已过期
    • 使用者用户名（已使用时）或过期时间
    • 复制按钮（未使用的邀请码）
    • 删除按钮（未使用的邀请码）

新用户在登录页面使用邀请码注册。

端口代理设置 ​

设置中的代理标签页提供与 Workbench 章节相同的端口代理功能。

Agent 安装与连接 ​

Agent（@yeaft/webchat-agent）是一个 Node.js CLI 工具，运行在安装了 Claude Code 的机器上。它通过 WebSocket 连接到 Claude Web Chat 服务端，在 Web UI 和 Claude Code 之间传递命令。

安装步骤 ​

前置要求：

  • 已安装 Node.js 18+
  • 已安装并配置 Claude Code CLI（claude 命令可用）
  • npm 或兼容的包管理器

第一步：安装 Agent

bash
npm install -g @yeaft/webchat-agent

第二步：获取 Agent 密钥

  • 登录 Claude Web Chat
  • 进入 设置 → 安全
  • 复制 Agent Key

第三步：安装为系统服务

bash
yeaft-agent install --server wss://your-server.com --secret YOUR_AGENT_KEY

这会将 Agent 注册为系统服务（Linux 上使用 systemd，macOS 上使用 launchd），开机自动启动。

替代方案：前台运行

bash
yeaft-agent --server wss://your-server.com --secret YOUR_AGENT_KEY --name my-worker

服务管理 ​

安装为系统服务后，可以使用以下命令管理：

命令描述
yeaft-agent start启动服务
yeaft-agent stop停止服务
yeaft-agent restart重启服务
yeaft-agent status查看服务状态
yeaft-agent logs查看服务日志（持续跟踪模式）
yeaft-agent uninstall卸载系统服务
yeaft-agent upgrade升级到最新版本

连接配置 ​

Agent 可通过以下方式配置：

CLI 参数：

参数描述默认值
--server <url>WebSocket 服务器 URLws://localhost:3456
--name <name>Agent 显示名称Worker-{平台}-{PID}
--secret <secret>Agent 认证密钥—
--work-dir <dir>默认工作目录当前目录
--auto-upgrade启动时检查更新关闭

环境变量（覆盖 CLI 参数）：

变量描述
SERVER_URLWebSocket 服务器 URL
AGENT_NAMEAgent 显示名称
AGENT_SECRETAgent 密钥
WORK_DIR工作目录

配置文件（首次运行时自动创建）：

  • 本地：工作目录下的 .claude-agent.json
  • 全局：~/.config/yeaft-agent/config.json

优先级顺序：环境变量 > CLI 参数 > 配置文件

常见问题 ​

Agent 在 Web UI 中显示离线：

  • 检查 Agent 进程是否在运行：yeaft-agent status
  • 确认服务器 URL 正确且可访问
  • 确保 Agent 密钥与 设置 → 安全 中的密钥一致
  • 查看 Agent 日志：yeaft-agent logs

连接持续重连：

  • Agent 默认每 5 秒自动重连
  • 检查 Agent 机器与服务器之间的网络连通性
  • 如使用 WSS（WebSocket Secure），确保 SSL 证书有效

Agent 版本不匹配：

  • 使用侧边栏 Agent 下拉菜单中的升级按钮远程升级
  • 或手动执行：yeaft-agent upgrade 或 npm install -g @yeaft/webchat-agent@latest

Crew 模式不可用：

  • Crew 模式需要 Agent 具有 crew 能力
  • 确保 Claude Code 已正确安装且 claude 命令可用
  • 安装 Claude Code 后需要重启 Agent

登录与注册 ​

登录 ​

  1. 输入用户名和密码
  2. 如果启用了 TOTP（双因素认证）：
    • 首次登录：显示 QR 码 — 使用认证器应用（Google Authenticator、Authy 等）扫描，然后输入 6 位验证码
    • 后续登录：输入认证器应用中的 6 位验证码
  3. 如果配置了邮箱验证，输入发送到邮箱的验证码

注册 ​

  1. 在登录页面点击 "注册新账号"
  2. 填写：
    • 用户名（最少 2 个字符）
    • 密码（最少 6 个字符）
    • 确认密码
    • 邮箱（可选）
  3. 点击提交注册
  4. 注册成功后自动跳转到登录页面

快捷键 ​

快捷键上下文操作
Enter聊天输入框发送消息
Shift+Enter聊天输入框换行
/聊天输入框打开斜杠命令自动补全
@Crew 输入框打开角色提及自动补全
Escape图片预览关闭预览浮层
Ctrl+PFiles 标签页快速打开文件搜索
Ctrl+滚轮文件树调整字体大小
方向键自动补全导航选项
Tab自动补全选择选项

Released under the MIT License.

Copyright 2024-present Yeaft