agent-loft

多个 agent 的工作台。 把本机的 Claude Code、Codex（以后还有更多）放到同一张台面上统一管理，在网页、飞书和桌面端（macOS / Windows / Linux）随时驱动它们，进展推送到飞书、iPhone 和 Mac。

📖 完整的产品介绍和使用指南见 docs/产品介绍.md：六大核心亮点、快速上手、使用指南、命令速查、常见问题和故障排查。

由 feishu-claude-bridge 和 feishu-codex-bridge 合并而来：一个进程、一份配置，飞书和网页共用同一套会话、审批和模型切换。

理念

这里的 Loft 不是阁楼，是工作台：agent 是干活的人，agent-loft 是它们共用的那张台面。

• 多 agent，一张台面：Claude Code、Codex 各有所长，不该各开一个窗口、各记一套会话。它们在这里共用工作目录、会话列表、审批和模型切换，同一条会话里随时换人接手，各自的上下文都保留着。
• 统一管理，而不是再造一个 agent：agent-loft 不自己做模型、不改 agent 的行为，只负责把官方的 agent 接进来、管起来。新的 agent 接一个驱动就能上台。
• 人在哪，台面就在哪：电脑上用网页，手机上用 PWA 或飞书。同一个会话、同一个授权请求，在哪个渠道处理都行，其他地方自动同步。
• 跑在你自己的机器上：代码、凭据和会话都留在本机，agent-loft 只是一层安全的遥控。

Logo 就是这个意思：一大两小几颗星（多个 agent）站在同一张台面上。

六大核心亮点

能做什么

• 多个 agent：Claude Code、Codex。两个 agent 共用工作目录，能看到对方改过的文件，但聊天记录各自独立。

• 多个飞书机器人：设置 → 飞书 →「可用专家」直接勾选内置或共享专家，并选择「默认专家」。只勾一个共享专家即可专用，不用再勾选底层 Agent；每个人绑定自己的账号后，直接私聊就是这个专家，使用各自的记忆和工具。机器人能在 Web 上扫码创建（Lark 国际版用「手动添加」），改完配置立即生效，不用重启。

  • 群聊里要 @ 机器人；不同话题是各自独立的会话；支持文字、富文本、图片、文件、语音和视频。
  • 思考和工具调用显示在实时刷新的过程卡片里，最终回复是普通消息。
  • 陌生人发消息会拿到配对码，在设置页批准后才能使用；每个机器人单独授权。

• Web 工作台：电脑和手机都能用，界面参照 ChatGPT。

  • 回复逐字显示，markdown 和代码高亮，思考过程和工具调用可以折叠；每条回复下方显示用时、费用和完成时间，可以复制，也可以「从这里分叉」成一条新会话（原会话不动）；自己发的消息也能一键复制。
  • agent 做多步骤的活时列的任务清单显示在输入框上方，看得到做到第几项、正在做哪一项。
  • 授权卡、提问卡直接在页面上点。
  • 附件：点击输入框的「+」直接上传，也可以粘贴、拖拽，手机上可以拍照；可以预览和下载。附件存在服务端的专用上传目录里，发出去的都收进资料库，开新会话、切换目录也不删；删除会话时立即清理。
  • 回复里提到的文件（链接、路径、正文里的绝对路径，Claude 和 Codex 都认）点一下就能预览：图片、PDF、音视频、markdown、代码和文本直接看，网页渲染出来看（也能切到源码），其它的下载。Codex 的 visualize 插件画的图表（回复里的 visualize{"path":…}）和官方客户端一样直接嵌在回复里。网页和图表放在沙箱里显示，碰不到登录态和本站接口。
  • 回复里的图：专家和 agent 在回复里写 ```chart（一段 JSON：折线、面积、柱状、饼图、散点）就画成可悬停的图，可以切到表格看具体数字；写 ```mermaid 画流程图、时序图等。跟着系统深浅色走，图库用到时才加载；飞书上 chart 换成表格。写法自动附在每个专家（包括内置的 Claude Code、Codex）的提示词里。只认这条对话里 agent 回复写过的路径；私钥、.ssh、.env、各种凭据和 agent-loft 自己的配置数据一律不给看。
  • 回复里的相册：agent 用 ```album JSON 描述多张本地照片，网页显示缩略图网格，每页 12 张、懒加载；点开大图可左右切换，也支持方向键和 Esc。可附名称、拍摄日期、说明和查询总数，每个相册最多 200 张；飞书显示简短摘要。写法自动附在所有专家的提示词里，图片沿用会话文件权限。
  • 聊天右上角「更多」和侧栏会话右键菜单共用分叉、重命名、在飞书继续、删除操作，按会话类型和可用机器人显示。
  • 语音输入：用浏览器自带的语音识别（Chrome / Edge / Safari，需要 HTTPS）。
  • 新对话页：点大标题里的目录名，在固定高度的目录弹窗里逐层选工作目录，也能新建文件夹；输入框上方选专家，鼠标停在专家上看简介，右下角选模型和思考程度。对话从头到尾一个专家，要换专家就新建对话；模型和思考程度随时可换。
  • 输入框里的小圆环显示上下文窗口占用；模型按钮显示实际的模型和思考程度（如「Opus 5.5 high」）。
  • 滚动和 ChatGPT 一样：发出的问题顶到最上面、下面留白，回复长到屏幕底部才跟着往下滚；回复过程中自己滚动了就不再自动滚，下次发消息再恢复。
  • 定时发送：右上角「更多」→「定时发送」，默认排在 5 小时额度重置后 5 分钟（弹窗里提示 5 小时 / 7 天额度的重置时间），由服务端到点发出，关掉页面也会发。适合额度用完、要等刷新才能接着干活的时候。
  • 侧栏直接显示各个文件夹，Web 会话按工作目录归类（目录可以拖动排序，右键可置顶；排好的顺序跟着账号走、各设备一致，新消息不会打乱），飞书会话按机器人分组，微信的当前与历史会话按账号分组，两者都能展开 / 折叠并记住状态，收起时仍显示运行中和待处理提示，展开即可查看历史会话。渠道分组行右侧始终显示飞书或微信的静态图标，Web 页面不提供这些分组的新建会话入口。项目名、渠道分组名和有分叉的会话后面有个小三角，点一下折叠 / 展开（分叉折叠后显示「N 个嵌套会话」）；分叉出来的会话缩进挂在原会话下面，用一条细线连着；标题放不下时尾巴淡出；Web 和飞书会话都先用首条消息命名，再同步 agent 自动生成的标题，旧飞书会话会从历史记录补名，双击可手动重命名；鼠标移到会话上，行尾显示对应的专家图标；定时任务的时钟图标始终放在最右侧。
  • 搜索：侧栏「搜索」弹窗，搜全部会话的标题、目录名和聊天内容（不开记忆也能搜），可以按专家筛；电脑和手机上弹窗都固定高度，结果在内部滚动，手机上从底部展开；↑↓ 选、回车打开。
  • 侧栏菜单：项目上方的「更多」支持点击或鼠标悬停展开，设置入口也在这里。「编辑侧边栏」可勾选直接显示的菜单、拖动调整顺序，未勾选的收进「更多」；配置跟着账号走，电脑和手机共用。
  • 会话页顶部标题前是专家的头像，PC 端头像与会话名称字号一致（15px）；鼠标停上去或点一下，看专家的说明、模型、能力、当前工作目录和本会话 Token 用量。
  • 附件可以直接拖到聊天区任意位置上传。
  • 回复过程中接着发的消息排队，标着「排队中」，隐藏底部的复制和回退按钮，上一条回复完自动接着处理；点「撤销并编辑」图标把排队消息放回输入框；点「打断并发送」停掉正在进行的回复、马上处理这条；点停止则连排着的一起取消（标「没有发出」）。
  • 用户消息的复制按钮后有「回退到此处」图标：把这条消息及附件放回输入框，并删除它及之后的聊天内容，重新发送时从之前的上下文继续。
  • 太长的消息先收起，点「展开显示」看全文；对话里有至少 3 条用户消息时，右侧显示快速定位尺，电脑上鼠标移入查看消息开头、点击跳转；手机上手动滚动时显示短轨道，按住拖动可预览问题和位置，松手跳转，停止操作约 1.6 秒后隐藏。
  • 回复底部的 token 数自动按大小显示为 K、M 等单位。
  • 项目右键（触屏长按）可「删除项目…」：二次确认后删除文件夹及全部文件、子目录和关联会话，同时清理附件、资料库文件和定时发送；目录选择器里也可删除空文件夹。工作区根目录、包含其他用户会话的目录不能删除，Agent 自己保存的原始会话记录仍保留。
  • 侧栏按页加载：每个项目目录和飞书机器人分组先显示 5 条，点「展开显示」每次再拉 10 条。
  • 项目、飞书和微信分组可混合拖拽排序，渠道分组可以放在项目前面或项目之间；右键（触屏长按）可置顶、上移、下移或按最近活跃重排。顺序按账号保存，刷新、换设备后保留，新消息不会改变已排好的位置。
  • 侧栏底部显示 Claude / Codex 的订阅额度（5 小时 / 7 天窗口，以及多久后重置）；关了额度查询就整块不显示。
  • 专家信息弹窗底部显示当前会话累计消耗的 Token 分布（输入 / 缓存写入 / 缓存读取 / 输出，Claude 还有按 API 价格估算的费用）。设置入口在侧栏的「更多」里。
  • 设置 → 用量：按日 / 月 / 年（默认按月）统计 token 和金额，有每天（每月）的柱状图，按 agent、模型、用户（管理员才有）分开看；成员只看到自己的。管理员还可查看服务端本机直接使用的 Claude Code、Codex 桌面端和 CLI 用量，和 Agent Loft 的用量分开显示、避免重复计算。金额都是按 API 价格算的参考值：Agent Loft 的 Claude 用它自己报的费用，Codex 和直接用的 Claude Code 按模型单价 × token 估算（OpenAI 单价来自 LiteLLM 公开价格表，内置快照、联网时每天更新）。Agent Loft 的账从 0.2.34 开始记录；本机直接使用的用量可回溯已有会话记录。
  • 「添加到主屏幕」后当 App 用；切到后台再回来会自动重连，补上错过的内容。
  • 前端资源按指纹长缓存：再次打开不用逐个向服务端确认，升级或改了文件后刷新页面自动换新。
  • 手机顶栏采用实色圆形按钮和「专家＋更多」胶囊按钮组；从左边缘右滑展开侧栏，在侧栏或遮罩上左滑收起，短滑会回弹。消息底部操作栏与下一条消息之间留 4px。

• 网页多服务器切换：在 设置 → 服务器 添加其他 agent-loft，再点「授权」到对方页面确认，侧栏左上角通过名称和紧随其后的箭头切换，不显示服务器图标，嵌入桌面端时隐藏此入口；各台分别登录，切走后保持连接，列表显示待处理数和运行状态，刷新后保留选择。几台需使用同一主域名下的 HTTPS 地址（例如 mac.example.com、nas.example.com）。在外层页面开启系统通知后，各台的提醒都能推到同一个主屏幕 App，点通知自动切到对应服务器和对话。见使用指南。

• 系统通知：Web 会话回复完成、出错、需要授权或提问时推送到手机 / 电脑（设置 → 系统 → 系统通知 → 「在此设备开启通知」，可以发测试通知）。飞书会话由飞书提醒，正在前台看着的会话不推。需要 HTTPS 访问，iPhone 需 iOS 16.4+ 且从主屏幕图标打开。

• 跨渠道同步：飞书里的会话在 Web 上也能打开接着聊。同一个授权请求同时出现在飞书卡片和网页上，哪边先点算哪边，另一边自动变成「已处理」。

• 授权：允许一次 / 本会话全部允许 / 总是允许（按钮上写明放行范围）/ 拒绝。权限级别（输入框左下角或 /permission）：逐次询问 / 自动改文件 / 完全允许，定时任务也可以单独设，完全允许只给管理员。/autoedit on 让 Claude Code 在这条会话里改工作目录内的文件不再询问（Bash 仍询问）。超时一律按拒绝处理。

• 设置都在网页上，按用途分组：我的（账号、飞书和微信绑定、自己的登录设备、记忆、专家、技能、MCP、用量）；Agent（运行环境置顶，各 agent 卡片分别配置默认模型、思考程度、可选模型、个人默认技能和 MCP，Codex 沙箱、额度查询；工作目录、会话闲置过期、授权卡超时和 Claude 的「总是允许」名单；「/」命令）；连接（飞书机器人、配对批准、指令面板同步；远程控制；服务器）；管理（用户标题旁添加用户，用户的「管理 → 登录设备」查看和下线各自设备；系统页管理服务端版本和升级、重启、局域网访问和端口，网络访问下方是系统通知；成员也可在系统页设置自己的通知）。账号页通过「修改名称」「修改密码」按需展开表单；飞书和微信绑定操作位于卡片右上角。设置、新建 / 编辑专家、重命名等编辑弹窗不会因点击外部或按 Esc 关闭；通过关闭、取消或保存 / 完成按钮退出。改了没保存就切页或关掉设置会先提醒。

• 多用户（信任型）：管理员在 设置 → 用户 里给别人建账号。每个人只看得到自己的对话、授权和通知；个人设置各自管理，服务器设置由管理员修改，见下面「安全」。

• 专家：设置 → 专家。专家是一份配置，新建对话、定时任务时选一个，对话从头到尾都是它（中途不能换；飞书里 /expert 名字、/claude、/codex 换专家会开新会话）。内置专家：Claude Code、Codex，保留原装提示词和所有工具，默认技能与 MCP 在「设置 → Agent」中按账号、按引擎分别选择。自定义专家由创建者管理，可以勾选「共享给所有账号」。共享后，其他人能在网页、绑定账号后的飞书私聊和定时任务中选择它；只有创建者能修改设定。每个人在该专家的「我的工具」里选择自己的技能和 MCP，使用各自的变量、凭据、记忆和聊天记录；创建者沿用原有工具选择，其他人未配置时不加载技能或 MCP。取消共享后，其他人的历史对话保留，后续消息不能继续调用该专家，相关定时任务在下次运行时暂停。可以配：

  • 头像（点头像区域的加号上传；未上传时，会话中用引擎的图标）、引擎（Claude / Codex，建好后不能换）、默认模型和思考程度（从模型列表里选）；
  • 提示词：人设、规则、输出格式。agent-loft 在后面自动补上这个专家能做什么、今天的日期、记忆。Claude 专家默认只用这段提示词（一句话约 2 千 token），也可以选「追加在 Claude Code 原装提示词后面」（干活更稳，每轮多约 1.6 万）；Codex 的基础指令改不了，专家的提示词附在第一条消息后面，约束力弱一些；
  • 权限，勾选：联网搜索、读网页，以及文件权限（一级包含一级）：都不勾就是只能联网（不碰本机文件、不弹授权，文本附件内容直接放进消息）／能读文件／能改文件／能跑命令（跑命令就等于能改任何文件，需要授权时弹卡）。Claude 按权限给工具；Codex 按权限开 shell、apply_patch，沙箱只读或 workspace-write；
  • 带不带个人记忆，默认工作目录，新对话页上的欢迎语和快捷提问；
  • 技能：只给选中的（Claude 用技能白名单，没选的调不了；没选技能就不挂 Skill 工具，省 token）；
  • MCP：从「设置 → MCP」里勾（管理员还能勾机器上配的）；
  • 子智能体（只有 Claude）：别的 Claude 专家，主专家用 Agent 工具把子任务派给它。子智能体的权限不能超过主专家（运行时也封顶在主专家的权限）。

  只勾联网搜索、读网页的 Claude 专家就是以前聊天模式的效果。专家改了，用它的对话下一条消息起生效；专家删了，用它的对话还能看、不能再发消息，用它的定时任务暂停。以前的聊天模式取消了：升级后聊天模式的旧对话不再保留，聊天模式的定时任务暂停，选个专家再启用。

• MCP：设置 → MCP，每人管自己的：本机进程（命令 + 参数 + 环境变量）或 HTTP 地址（+ 请求头），值可以标成密钥（网页上不回显，只交给 MCP 进程或请求头，不进提示词）。可以设「调用前询问」，不设就直接用。自定义专家加载各自勾选的服务；内置专家在「设置 → Agent → 对应 Agent 卡片 → 默认加载」里选择，支持个人 MCP、管理员可选的机器 MCP，也可全部取消；不指定时管理员沿用机器配置。

• 记忆：像 ChatGPT 的记忆，设置 → 记忆（默认关）。「关于我」加上一条条记住的事，每次对话都带上；agent 在聊天里遇到长期有用的信息会自己用 remember 记一条（回复里会说），记错了用 forget 删。自动整理：把上次整理之后新说的话交给模型（不留会话记录的一次性调用），补充、更新或删掉过时的记忆，用户自己加的条目它不动。什么时候整理每个人自己定：每天一次（默认凌晨 2 点，把当天的对话合起来一次整理，最省）／每段对话聊完后（停多久可选，改了什么会在对话里说一声）／只在点「现在整理」时／不整理；整理哪些对话也能选：全部／只整理选中专家的对话；用哪个 agent 的哪个模型也能选，默认 Claude Haiku，没有 Claude 就用 Codex 的默认模型、思考程度 low。参考以前的聊天：agent 遇到「上次说的那个……」会用 search_past_chats 搜你以前的对话（关键词搜索，只有你自己的、没被删掉的对话）。聊天记录索引不开记忆也会记（侧栏的「搜索」也用它），升级后会把已有对话收录进来一次；没开记忆时记进来的不拿去整理。两项都能在设置里单独关。每个用户一份，Claude 和 Codex、Web 和飞书共用。只用在有主人的对话里：你的 Web 对话，以及绑定了飞书账号后和机器人的私聊；飞书群聊不用。别人（包括管理员）看不到你的记忆，管理员只能清空它；删用户时记忆一起删，不转给管理员。

• 定时任务：像 ChatGPT 的 Tasks，侧栏的「定时任务」。到点把一段提示词交给 agent，结果发回对话：一次 / 每天 / 工作日 / 每周 / 每月 / 每隔几小时 / 自定义 cron，按服务端时区，两次至少隔 15 分钟。有需要才提醒（默认）：agent 自己判断这次有没有要告诉你的事（比如「有新版本才告诉我」），没有就在回复第一行写 [[静默]]，推送、飞书都不发，对话里折叠成一行；没写暗号一律照常提醒。结果发到专用对话（任务自己的一条对话，第一次运行时新建、之后续用，可选专家和目录；可以设成不携带上下文，每次运行都换新会话，之前的结果还留在对话里，只是 agent 看不到），在专用对话右上角的「更多」里可以直接编辑任务、立即运行，或者原来的对话。也能直接在对话里说「每天早上 9 点帮我……」：agent 用 create_task / update_task / delete_task / list_tasks 工具管理，新建、修改、删除都会先弹授权卡让你确认（只有暂停不用；没有「总是允许」），任务自己运行的那一轮里不能再建、改、删任务。按人隔离：每人只看得到、改得了自己的任务（最多 30 个），删用户时一起删；到点再核对一次对话还是不是他的，对话被删或换了主人就暂停任务。到点对话在忙（正在回复或挂着授权）就等它，最多 30 分钟；服务停着时错过 2 小时以内的启动后补跑一次。工具和记忆一样只给有主人的对话，飞书群聊里没有。

• 技能（skills）：设置 → 技能。技能就是 Claude Code / Codex 用的那种 SKILL.md（可以带脚本和资料），由 agent-loft 按人管理，两个 agent 都能用。来源：在页面上写、上传技能包（.zip / .skill / 单个 SKILL.md / 整个文件夹），或者在对话里让 agent「把刚才的做法存成技能」（agent 用 create_skill / update_skill，先弹授权卡）。共享：新建、编辑时选择「仅自己可见」「指定用户」或「所有人可见」，也可在自己技能的「更多 → 共享」里调整；默认仅自己可见。其他用户在「共享技能」中查看正文和附带文件、安装；安装后出现在「我的技能」，可停用、卸载或重新安装。安装的是作者的同一份技能，更新自动跟随；作者撤回共享后，范围外用户不再可用。只有作者能编辑，管理员可下架自己看得到的共享技能。共享不包含作者填写的变量和密钥，每人使用自己的配置。使用：内置专家默认使用你启用的全部技能，也可以在「设置 → Agent」中分别指定 Claude Code / Codex 加载哪些技能；自定义专家只用它选中的；agent 遇到对得上的事自己用。变量：技能可以声明要用的环境变量（接口地址、密钥），每个人填自己的值，只注入自己的会话；密钥再写上「只允许发往」的地址就成了受保护的密钥——不进环境变量，agent 看不到值，只能用 skill_request 工具让 agent-loft 代发请求（在地址、请求头、请求体里写 {{变量名}}），只发往你确认过的地址、不跟随跳转、响应里出现的值会被抹掉；作者后来改了地址，要你再确认一次才放行。机器上原有的技能（~/.claude/skills、~/.agents/skills、插件市场和 claude.ai 同步的）只给管理员：成员的会话里看不到、调不了（Claude 用技能白名单，/技能名 也会被拦下；Codex 关掉它自己的技能清单），管理员在「设置 → 技能 → 本机技能」里能看到。

• 资料库：像 ChatGPT 的资料库，侧栏的「资料库」。对话里发过的附件、agent 回复里给出的、这一轮新写出来的图片 / 文档 / 音视频（复制一份收进来，之后原文件改了删了不影响）都汇总在这里：按图片 / 文档 / 音视频筛、按文件名搜，点开看大图或下载，「在新对话里用」，单个或批量删除（文件从磁盘上删掉）。从资料库拿到对话里的文件硬链接进那条对话的上传目录，不占双份空间，agent 照常能读。按人隔离，规则同对话：自己的；没主人的对话（飞书群聊等）的归管理员。上传了一直没发出去的一天后清掉；删除会话时立即清理该会话的上传文件和资料库记录，删除原件也会清理复用到其他会话的副本。agent 侧的会话记录仍保留，恢复会话不会恢复已删除的文件。

• 远程控制：侧栏「定时任务」下面的「远程控制」，直接操作这台机器的桌面和终端，上面一键切换；切回对话时连接留在后台（侧栏入口上亮个小绿点），再进来接着用。这台机器没有图形桌面（服务器、NAS）时只有终端。

  • 桌面：走 VNC 协议，网页里用 noVNC 显示，鼠标、键盘、剪贴板都能用，进来时不自动连、点「连接桌面」才连，工具栏上选画质：流畅 / 标准（默认）/ 高清由服务端把画面缩小到长边 1280 / 1920 / 2560、只把变了的地方压成 JPEG 发过来（macOS 屏幕共享只给无损的 ZRLE，5K 屏一整屏 30MB，原样转发隔着公网几秒一帧），原画是原样转发、只适合局域网；远程那边接了几块屏时可以只看其中一块（按系统里的显示器名称选，服务端只截那块再缩，比几块屏拼在一起缩小清楚得多；macOS 的各块屏位置要从屏幕共享发来的画面里学，第一次连上要几秒，原画下不能选）；可以缩放到窗口或按原始大小看、全屏（手机上也能，iPhone 上是铺满页面）、「只看不控制」、发送 Ctrl+Alt+Del 之类的组合键。手机上有两种手势（右上角切换，「?」看说明）：触控板模式（默认）屏幕上有个指针，单指滑动移动、轻点单击、双指轻点右键、长按后拖动是按住左键拖、双指滑动滚动；触摸模式点哪就点哪。两种模式都能双指捏合在本地放大画面（放大后小按钮也点得准，右下角「还原」），画面下面一排 Esc / Tab / Ctrl / Alt / Win / 方向键，Ctrl、Alt、Win 点一下会粘住，带给下一个按键或点击；键盘按钮弹出软键盘打字，中文输入法也能用。Linux 上 agent-loft 在有人连时用 x11vnc 共享当前的桌面（Xorg 会话；只听 127.0.0.1、随机端口、每次随机密码，需要 sudo apt install x11vnc），没人连着 30 分钟后停掉；macOS 上在 设置 → 远程控制 里改用「已有的 VNC 服务」，接系统自带的屏幕共享：填 VNC 密码，或者屏幕共享没开 VNC 密码时填 Mac 的用户名和登录密码（苹果认证，由服务端登录）。
  • 终端：进入或刷新页面时不自动连接，点击「连接终端」后接上后台终端，没有现成的才新建；也可直接点击「新建终端」。新终端开在当前对话的工作目录里，可以开多个标签；Ctrl+Shift+C / Ctrl+Shift+V 复制粘贴。Ctrl+` 在对话下面拉出终端面板（高度可拖动），面板和远程控制里的是同一批终端。关掉页面、手机切到后台、断线都不结束 shell，重新打开后手动连接即可接着用、补上错过的输出，别的设备上也能接上；没有页面连着超过 30 分钟（设置里可改）才结束，点标签上的 × 立即结束。依赖可选的原生模块 node-pty：Linux 上安装时要现场编译（需要 make、g++、python3），没装好时终端用不了，其他功能照常。手机上单指上下滑翻看历史（在 less、vim 里是翻页），长按选中文字、接着拖动扩大选区，再点「复制」；终端下面多一排 Esc / Tab / Ctrl / Alt / 方向键 / Home / End / PgUp / PgDn / 粘贴。iOS 上软键盘弹出来时这排键会垫到键盘上面。
  • 管理员能用；成员要管理员在 设置 → 用户 里单独「开通远程控制」。终端、桌面在 设置 → 远程控制 里各有总开关。

• 微信 ClawBot：设置 → 账号 → 微信 →「扫码连接微信」，用手机微信扫码并确认（要求微信 8.0.70 以上，「设置 → 插件」里有 ClawBot；这个功能腾讯还在逐步放量）。每个人连自己的微信，会话归扫码的人，用他的记忆和工具，只认扫码的这个微信号；发送 /new 创建独立会话并保留旧记录，Web 微信分组里可以查看和续聊历史；服务端主动连向腾讯，不需要公网地址。微信里发文字或语音（要微信能转成文字），不发过程，只显示「正在输入」，结束后发结果；授权和提问是一条文字，回复数字处理（1 允许一次、0 拒绝，含义固定），网页上也能处理。/new、/stop、/model、/expert 等命令都能用。连接后可在同一设置页的「微信使用的专家」中选择专家并点击「切换专家」，也能在首次发微信消息前选好；已有聊天内容时，切换会创建独立会话并保留旧记录，和微信里的 /expert 共用同一份选择。

  微信的限制（官方没公布具体数字，以下来自社区实测，agent-loft 按此处理）：每条入站消息之后约能发 10 条，所以长回复每次发 3 段，回「继续」接着发，额度用完时在网页上说明；约 24 小时没在微信里说话后微信会拒绝发送，定时任务的结果可能发不过去，这时改走网页提示和系统推送。接口受理了但没给 message_id 时手机可能没收到（微信可能在静默限制账号），设置页和对话里会提示。Web 上说的话回复留在 Web，不花微信的额度。暂不支持群聊和收发图片、文件。

  消息会经过腾讯服务器，腾讯保留限制、拦截和终止服务的权利（《微信 ClawBot 功能使用条款》）。建议先用小号，不要反复重新扫码（有开发者反映会触发风控）。如果走了代理，让 ilinkai.weixin.qq.com 和 *.cdn.weixin.qq.com 直连。

• 飞书账号绑定：设置 → 账号 → 飞书账号 →「生成绑定码」，再在飞书私聊机器人发 /bind 绑定码（10 分钟内有效，群里发不算）。绑定后这个私聊就是你的个人会话：用你的记忆，/sessions 只列你的会话，/web 只能接上你自己的 Web 会话，管理员在 Web 上也看不到它。必须本人在两边各操作一次，管理员不能替人绑定（只能解除），否则就能借飞书读到别人的记忆。

安装

需要 Linux 或 macOS，Node.js 22.13 及以上。

npm install -g agent-loft         # 或者在仓库里 npm install 后用 node bin/cli.js
agent-loft start                  # 前台运行，日志里会打印首次登录用的设置码
agent-loft service install        # 注册为开机自启服务（systemd / launchd），日志在 ~/.agent-loft/logs/

打开 http://<机器 IP>:8800（本机用 http://localhost:8800）：第一次需要输入日志里的设置码，然后建一个管理员账号（用户名默认 admin）。设置码找不到的话，直接运行 agent-loft passwd 设密码。

到 设置 → Agent 检查 Claude Code、Codex 装好、登录了没有：Claude Code 随 agent-loft 一起安装，只需在服务端终端里登录；Codex 可以点「直接在服务器上安装」。设置 → 系统 里能看到服务端版本，有新版本时点「升级」即可（npm install -g agent-loft@latest，以系统服务运行时会自动重启，打开的页面会自动刷新）。

在外面只用飞书的话不需要任何网络配置（机器人由服务端主动连向飞书）。在外面用网页、系统推送和语音输入需要 HTTPS，见下面的「安全」和产品介绍里的「从外网访问」。

桌面端（macOS / Windows / Linux）

到 Releases 下载 desktop-v* 里对应的安装包：

• macOS：对应芯片的 DMG（Apple 芯片选 arm64，Intel 选 x64），拖进「应用程序」。还没有 Apple 开发者签名，第一次打开如果提示无法验证，到 系统设置 → 隐私与安全性 里点「仍要打开」。
• Windows：Agent-Loft-Setup-*-x64.exe，装在用户目录里，不用管理员权限。没有代码签名，SmartScreen 拦的话点「更多信息 → 仍要运行」。
• Linux：Debian / Ubuntu 用 deb（sudo apt install ./agent-loft-desktop_*_amd64.deb），其他发行版用 AppImage（需要 libfuse2）；ARM 选 arm64。App 内一键更新只支持 AppImage。GNOME 要装 AppIndicator 扩展才看得到托盘图标。

下面以 macOS 为例，Windows / Linux 上「菜单栏」是托盘、⌘ 是 Ctrl：

• 同时连多台服务器，顶部标签栏切换、拖动排序；每台各自登录，切走了也在后台连着，回复完成、需要授权时弹系统通知，程序坞图标显示未读数。
• 菜单栏图标：悬停看各服务器的 Claude / Codex 额度、待处理和运行中的会话；双击打开主窗口。同一个账号的额度只查一次。（Windows 上点托盘图标弹出；Linux 上在托盘菜单里点「额度和待处理」。）
• 菜单栏图标可以换成额度条：Claude、Codex 各是一只像素小宠物，看样子就知道是谁，身子是 5 小时额度，下面一条是周额度。桌面端设置 → 额度显示 →「菜单栏显示额度」，选所有服务器合起来（取最高），或者按服务器分别选 Claude / Codex（图标上不写服务器名）；都不选就只显示图标。「额度条显示」选实心表示剩余额度（默认，像电池）还是已用额度。只有 macOS 有，Windows / Linux 的托盘图标太小放不下。
• 支持前面挡着 Cloudflare Access 的服务器：验证页直接在窗口里完成，过期会提醒；也可以配 Service Token 免验证。
• 首次打开可以选「这台 Mac 也作为服务端」：一键在终端里安装 agent-loft（没有 Node.js 会先用 Homebrew 装）并开机自启，装好自动连上；设置里可以改成「只在桌面端运行时运行」（不开机自启，打开桌面端时启动、退出时停止）。Linux 上一样（需要先装好 Node.js 22.13+，开机自启用 systemd 用户服务）；Windows 上服务端还没有开机自启，可以在 WSL 里装，桌面端会自动检测到 127.0.0.1 上的它。防休眠：本机有会话在跑时不休眠；另有永不休眠、定时休眠（设休眠时段，时段外不休眠，时段内本机没有会话在跑、屏幕锁上后让 Mac 睡下去）和合盖不休眠（macOS，第一次开关要输管理员密码，之后不用；开着时闲置也不睡，定时休眠到点会临时关掉它让 Mac 睡下去，醒来再打开）。
• macOS 从系统菜单「显示 → 用量汇总」（⌘⇧U）打开汇总页，Windows / Linux 也可点顶栏服务器标签后面的用量按钮（柱状图图标）：从所有已添加服务器拉取 token 和费用，包括各服务器本机直接使用的 Claude Code、Codex 桌面端和 CLI（仅管理员可见）。按日 / 月 / 年统计，和网页设置 → 用量一样有柱状图和按 agent、模型、用户的分项，另外多一栏按服务器来源。采集在各服务端完成：读取运行服务的系统用户下 ~/.claude/projects、~/.codex/sessions 和 archived_sessions（支持 CLAUDE_CONFIG_DIR / CODEX_HOME），按服务器时区记日期，并跳过 Agent Loft 已记账的会话。桌面端不再扫描本机文件；这台电脑的直接用量也需要添加本机服务端才能统计。不在线、没登录或缺少用量接口的服务器不计入，页面上会注明；有旧版用量接口但不支持本机采集的，会提示升级。
• macOS 从系统菜单「Agent Loft → 设置…」（⌘,）打开桌面端设置，Windows / Linux 也可点顶栏设置按钮。在服务器列表里展开某台服务器，能看它的 Agent 环境和版本，有新版本时点「升级服务端」；桌面端自己的更新在同一页的「更新」里点「更新并重启」。

桌面端只是个壳（代码在 desktop/），服务端照常用 npm 安装和升级。

桌面端一键安装的服务端放在 ~/.local，无需管理员权限，也不修改 npm 的全局配置。如果旧版桌面端安装时出现 EACCES /usr/local/lib/node_modules/agent-loft，可以先在终端执行：

npm install -g --prefix "$HOME/.local" agent-loft
PATH="$HOME/.local/bin:$PATH" "$HOME/.local/bin/agent-loft" service install

第一条成功后再执行第二条，然后重新打开桌面端，选择连接本机服务端即可。需要 Node.js 22.13 以上。

从旧桥接器迁移

agent-loft import --dry-run       # 先看会导入什么
systemctl --user disable --now feishu-claude-bridge feishu-codex-bridge   # 同一个机器人不能被两个程序同时连
agent-loft import                 # 导入机器人凭据、白名单、配对、会话绑定、总是允许名单
agent-loft service install

导入后，飞书群里原来的会话会接着聊。

命令

aloft 是 agent-loft 的简写。

聊天里的命令（飞书和 Web 通用；Web 打开页面时会预加载当前专家和目录的命令，输入框打 / 会弹出命令补全，飞书里打 / 会弹出机器人的指令面板（agent-loft 自动注册，约 5～8 分钟生效；只发一个 / 也会回一张可点击的命令卡片），顺序和显示项在 设置 → 命令 里调整）：/new /fork /sessions [all] /resume <id> /model [名称] /effort <程度> /stop /cd <目录> /pwd /status /permission [ask|edit|full|default]、/autoedit [on|off] /approve <id> allow-once|allow-always|allow-session|deny /help；只在飞书里有的：/expert [名称]（或者直接发 /claude、/codex，换专家会开新会话）/web /detach /bind <绑定码>

自定义命令：设置 → 命令 → 「添加命令」，填命令名、说明和一段提示词，之后发 /命令名 参数 就会把这段提示词发给 agent（提示词里的 $ARGUMENTS 换成参数，没写就把参数接在后面）。按 agent 分开存，可以编辑、删除，也会同步到飞书指令面板。

安全

这个服务能让 agent 在你的机器上执行命令，等于一个远程 shell。

• Web 登录密码用 scrypt 哈希保存。首次建管理员必须用启动日志里的一次性设置码，防止「谁先打开页面谁就成了主人」。
• 管理员在 设置 → 用户 添加成员时，或点已有成员的「使用权限」，可以分别设置共享专家、内置 Agent、服务器切换为「全部允许（含以后新增）」或指定列表（可全部取消）；旧账号沿用全部允许。共享专家和内置 Agent 分别授权，成员自己创建的专家仍可使用；收回权限后旧对话可查看，但不能继续调用，相关定时任务会暂停。服务器权限控制本机切换列表，当前服务器保持可用，各台服务器仍各自登录和管理账号。每个用户都可以在 设置 → 账号 修改自己的账号名称（也是登录名），修改不影响原有对话和登录设备。
• 多用户只隔开界面上的东西：会话列表、授权 / 提问卡、通知、记忆、/sessions 能列出和恢复的 agent 会话；设置、飞书机器人和飞书会话只给管理员（绑定了账号的飞书私聊除外，它归绑定的人）；会落盘、对所有人生效的「总是允许」（Claude 的总是允许名单、Codex 的 execpolicy）只有管理员能点。它不是安全边界：所有 agent 都以同一个系统用户运行，任何用户都能让 agent 读到这台机器上的文件（别人的对话记录、配置里的密钥），用的也是同一个 Claude / Codex 订阅。只给信任的人开账号；要真正隔离，就每人用自己的系统用户各跑一份 agent-loft。
• 从老版本升级：原来的登录密码自动变成管理员 admin，已登录的设备不用重新登录。
• 登录态通过 HttpOnly cookie 保存，服务端只存它的哈希。同一 IP 连续输错 5 次锁 15 分钟。所有写请求和 WebSocket 都校验 Origin。页面开启了严格的 CSP。
• 暴露到公网时，只通过 HTTPS 反向代理（比如 Lucky）或 Cloudflare Tunnel 访问，并把不在本机的反代 IP 加进 web.trustedProxies（只有从这些地址来的连接才采信 X-Forwarded-*）。不要直接把 8800 端口映射出去。局域网访问可以在 设置 → 系统 → 网络访问 里关掉。
• 远程控制不经过授权卡：拿到终端就是拿到运行 agent-loft 的那个系统用户的 shell，拿到桌面就是坐在登录桌面的那个人面前。所以默认只给管理员，成员要管理员单独开通（开通时会再提醒一次）；收回权限、停用或删除用户、在设置里关掉终端 / 桌面时，他开着的 shell 立刻结束、桌面立刻断开。终端和桌面的 WebSocket 和其他接口一样校验登录态和 Origin。shell 拿不到本服务自己的凭据（和 agent 子进程一样剔除环境变量）。共享桌面用的 x11vnc 只听本机、密码每次随机生成、经文件传过去（不出现在命令行里）；用「已有的 VNC 服务」时，配置里的 VNC 密码会交给开通了远程控制的人的页面；填了 Mac 用户名走苹果认证时由服务端登录，登录密码不会发到页面（但和 VNC 密码一样明文存在 config.json 里）。
• 审批超时一律按拒绝处理。Codex 默认沙箱为 workspace-write，不会因为 ~/.codex/config.toml 里配了 never 或 danger-full-access 就绕过审批。
• agent 子进程拿不到本服务自己的凭据（FEISHU_*、AGENT_LOFT_* 等环境变量会被剔除）。
• 技能存在 data/skills/：技能本体在 files/<技能 id>/，每个人装了哪些、变量的值在 users/<用户 id>.json（0600）。普通变量注入到会话环境里，agent 能读到；受保护的密钥 agent 看不到值，但和多用户一样不是安全边界——能读文件的专家（包括内置的 Claude Code / Codex）能直接读这些文件。别人分享的技能会在你的会话里照着执行，装之前在技能页点开看一眼它要做什么、要哪些变量。
• 记忆和聊天记录索引都存在 data/agent-loft.db（SQLite，会话、脚注、用量也在里面）。记给谁由 agent-loft 在拉起记忆工具时定死（工具参数里没有用户），模型想写别人的记忆也写不了；但和多用户一样不是安全边界：能读文件的专家能读到这个数据库文件。只能联网的专家没有读写本机文件的工具，网页里的提示注入也骗不走本机文件。
• 专家存在 data/experts.json，MCP 存在 data/mcp.json（0600，含 MCP 的密钥值），内置 Agent 的个人默认选择存在 data/builtin-agents.json。和技能一样不是安全边界：能读文件的专家读得到。

结构

src/
  core/            与渠道、agent 都无关的中枢
    hub.ts         会话调度：事件广播、命令、按专家拉起会话、换模型 / 目录
    interactions.ts 审批与提问：一个请求，多个渠道都能处理
    store.ts       会话持久化（每个 agent 的会话 id 各自保存）
    config.ts      配置（Web 可改，改完热加载）
    users.ts       Web 登录用户和归属规则（谁能看到哪条会话）
    memory.ts      记忆的存储和注入系统提示的那段文字；personal.ts 定记忆用谁的
    chat-history.ts 聊天记录索引（数据库的 history 表）和关键词搜索
    memory-curator.ts 录入聊天、回填已有对话、聊完后自动整理记忆
    feishu-links.ts 飞书账号 ↔ 用户的绑定和绑定码
    experts.ts     专家的存储、校验，开会话时解析成交给 agent 的配置（MCP、技能、子智能体）
    expert-prompt.ts 专家告诉 agent 的话（Claude 换系统提示或追加，Codex 附在消息后面）
    mcp.ts         MCP 的存储（按人）、机器上原有的 MCP
    library.ts     资料库：文件索引（数据库的 files 表）、收录用户发的附件和 agent 生成的文件、启动时收拾上传目录
    db.ts          数据库（data/agent-loft.db）：建表、导入升级前的 JSON
    tasks.ts       定时任务的存储（按人隔离）；task-schedule.ts 频率和 cron；task-prompt.ts 每次运行附给 agent 的说明和静默暗号
    task-runner.ts 定时任务的调度：到点核对主人和对话、送进对话、记下结果
    tasks-bridge.ts 定时任务工具在主进程这头：核对签名、弹授权卡、增删改（tasks-mcp.ts 定怎么拉起）；技能工具也走这条通道
    skills.ts      技能的存储：可见性、安装、停用、变量和受保护密钥确认过的地址；zip.ts 解技能包
    skill-runtime.ts 技能怎么交给 agent：Claude 的插件目录和成员白名单、Codex 的清单、自定义专家只给选中的、机器上原有的技能
    skills-bridge.ts 技能工具在主进程这头：建 / 改技能（弹授权卡）、skill_request 代发带密钥的请求
    terminals.ts   网页终端：用 node-pty 起 shell、留最近的输出给重连补发、没人连着到点结束、权限收回时结束
    desktop.ts     远程桌面：找这台机器的 X 桌面、按需起 x11vnc（或用已有的 VNC 服务）、没人连着到点停掉
    vnc-auth.ts    由服务端登录 VNC（苹果认证、VNC 密码、不用认证），对页面装成不用认证的
    vnc-transcode.ts 远程桌面转码：服务端当 VNC 客户端收全分辨率画面，缩小、只把变了的格子压成 JPEG 按 Tight 发给页面
    pairing.ts uploads.ts commands.ts …
  mcp/
    memory-server.ts 记忆工具（remember / forget / search_past_chats）的 stdio MCP 服务，两个 agent 共用
    tasks-server.ts  定时任务工具的 stdio MCP 服务：只传话，经 unix socket 转给主进程；AGENT_LOFT_TOOLSET=skills 时是技能工具
  agents/
    claude/        Claude Agent SDK 驱动
    codex/         codex app-server 驱动
  channels/
    feishu/        飞书：一个 FeishuBot 对应一个机器人，支持多个
    weixin/        微信 ClawBot（iLink 协议）：一个 WeixinBot 对应一个用户扫码连上的微信
    web/           HTTP + WebSocket + 鉴权；terminal.ts 是终端的接口和 /ws/term，desktop.ts 是桌面的接口和 /ws/desktop（转给 VNC）
web/               前端（原生 JS，不需要构建）
desktop/           桌面端（Electron 外壳，macOS / Windows / Linux）
docs/              产品介绍和截图

接入新的消息渠道（比如 Telegram）

参照 channels/feishu/bot.ts，做三件事：

1. 收到消息 → hub.ensure() 建会话 → parseCommand()。是命令就调 hub.command()，再把 CommandReply 画出来；是聊天就调 hub.send()。
2. 订阅 hub.on("event")，挑出自己的会话（键前缀如 telegram:<botId>:），把 step / text / result / error 画出来。
3. 订阅 interactions 的 created / updated / settled，把授权卡和提问卡画成按钮。用户点击后调 interactions.decide / select / submit / skip。

接入新的 agent

实现 core/types.ts 里的 AgentDriver，然后在 main.ts 里 hub.registerDriver()。AgentDriver 包括开会话、发消息、中断、切模型、列历史、读历史，审批通过传入的 InteractionHost 发起。以后要接 ACP 协议的 agent（Gemini CLI、OpenCode 等），写一个通用的 ACP 驱动就行。

开发

npm install
npm run dev          # AGENT_LOFT_HOME=./.dev，改代码自动重启
npm test
npm run typecheck