English | 简体中文

Deepclaw

一个自己跑起来的 agent 平台。招一支 agent 团队，给它们装上技能，让它们去做你的项目、按你的日程干活 —— 网页界面和终端界面都有。

所有东西都跑在你自己的机器上，用你自己的模型密钥。没有配过的地方，不会有数据发过去。

安装

需要 Node 22 或更新的版本。Linux、macOS 和 Windows 都能跑。

npm install -g @sacephor/deepclaw

启动

deepclaw start            # 网页界面，地址是 http://localhost:3000
deepclaw stop             # 把它停掉
deepclaw restart          # 停掉再重新起来
deepclaw start --tui      # 终端界面

网页界面在后台接着跑，deepclaw start 打印完地址就把命令行还给你。服务端要说的话写在 deepclaw 目录下的 console.log 里，deepclaw stop 停掉它。

| 选项 | 作用 | | -------------- | ------------------------------------------ | | --tui | 打开终端界面，而不是网页界面 | | --foreground | 网页界面留在这个终端里，Ctrl-C 结束它 | | --port | 网页界面的端口，不指定就是 3000 | | --host | 网页界面绑定的地址，默认 127.0.0.1 |

第一次启动会引导你走一遍设置：用哪个模型，以及连它用的密钥。

网页界面不设密码，所以它只待在运行它的那台机器上。任何能访问到它的人都能拿你的密钥驱使你的 agent 干活 —— 在用 --host 把它交给一个网络地址之前，这一点值得记住。

最近更新记录

v0.3.2

• 还没人做过的任务现在可以在卡片菜单里删掉：它从看板上消失，什么都不留下，等它的任务不用再等。动过的任务则是作废，那会留下「计划过」的记录。

v0.3.0

• 不值得再做的任务现在可以作废，卡片上能改，做这个项目的 agent 也能改：它带着删除线落在已完成那一列 里，计数算已完成，等它的任务一并放行。
• 项目标题现在可以在看板上直接改，和描述一样。
• 基础信息设置里现在可以写公司简介，每个 agent 干活之前都知道这活儿是为谁做的，以替代DEEPCLAW.md文件。

v0.2.2

• 项目现在可以指定一个自己的工作目录——一个代码仓库，或者一堆文档——这个项目的每一次 run 都在那里干活。
• 任务现在可以给自己开一个 git worktree，同时在做的几个任务因此永远不会共用一份检出。
• Agent 的情绪现在可以是对手下这摊活儿跑得怎么样的感受，不只是对自己这一轮的。

v0.2.1

• 任务报告和项目报告现在可以在打开的报告面板里直接改。
• 定时任务的标题、执行周期和任务内容现在可以在定时任务页面上直接改。
• deepclaw restart 现在把服务停下来再起回去。

完整变动记录： changelog 里。

界面上有什么

侧边栏里五个地方：Agent、项目看板、定时任务、技能、设置。

Agent

每个 agent 都是一个具体的人：名字、头像、角色、性格特点，还有它擅长的领域。招人和辞退都在设置里。

点开一个，详情面板会告诉你它此刻在干什么 —— 正在跑哪些任务、进度到哪儿了、有没有在帮别人评审哪个 任务、归属哪个项目、还有哪些定时任务在等它。Agent 分忙碌和空闲，而且各自带着心情：开心、专注、疲惫、困惑，或者不想说。

对话

可以跟某个 agent 聊，也可以跟某个项目聊。回复是一边生成一边流式吐出来的，消息里可以带图片。

看够了的这一轮可以就地打住：agent 在干活的时候，停止会顶掉发送的位置，一按就能截在模型说话的 半句上、截在正在跑的命令上，连它派出去的每个子 agent 一起。已经说出来的话留在对话里，你接着说的 就从那儿往下走 —— 停止是结束这一轮，不是暂停。开着这个对话的任何一个标签页都能停，不限于发起的 那个。

碰上只有你能拍板的事，agent 会停下来问 —— 比如要执行一条得先确认的命令，或者要碰工作目录之外的 文件。问题直接弹到你面前：允许这一次、这类操作本次会话内都允许，或者拒绝。要是你人不在，会有通知 告诉你有人在等。问题跟着对话走，不跟着你发起的那个标签页：把那个页关掉，另一个开着同一段对话的 页面会接着被问。

一段对话可以关掉，从头开始。新对话把当前这段归档，给 agent 留一个空的上下文 —— 当你要问的事 已经换了方向、后面那串历史只剩成本的时候，用它。关掉的对话收在历史对话里，各自以第一句问话 命名，带着日期、轮数和花掉的 token；点开就能读回来。Agent 还在干活、或者手上还有后台命令没跑完 的时候，这段对话会一直留着，等它做完。

每段对话都会显示花了多少 token，其中有多少输入是从缓存里拿的。

项目看板

任务分三列 —— 待办、进行中、已完成 —— 干完一段就往右挪。卡片上带着负责人、优先级、进度，以及它在等 哪些任务。项目可以按标题、描述或标签搜索，看板也可以只看某一个负责人的。

任务卡片上的两个按钮是你介入的入口。暂停告诉 agent 做完这个任务就停下，别接着往下跑。它停在 那儿之后，任务会等你验收：你没看过、没点头，后面就不会继续。那些你想先过目再往上垒的环节，用它。 还没人开工的任务也可以换个人做，点负责人旁边的铅笔 —— 活一旦被接走，就归接走它的那个了。

让别人过一遍

任务可以指一个评审人：另一个 agent，在任务关掉之前把活读一遍。卡片还在待办列时，用 + 评审人 指上，旁边的铅笔可以改、也可以取消。活一旦开工，这个名字就定了 —— 那时候加上去，等于在一个本来打算 直接做完的流程前面横一道闸；那时候撤掉，等于把已经许出去的一次评审又收回来。

读的过程是一段独立的运行：评审人自己的模型、自己的记忆、自己的技能，一段空的上下文，还有同一份文件。 它对干活那段对话一无所知，所以它看的是文件里真实的样子，而不是谁说过什么 —— 它能读文件、跑你的测试、 读项目信息，这就是它能做的全部。读的时候，卡片上评审人那一行旁边转着圈，这个 agent 自己的页面上也会 在"正在进行"里单列一行。它交出来的是一个结论加一份报告，报告从卡片上点开。

结论是意见，不是闸门。关掉任务的仍然是任务的负责人：不通过意味着活退回去改、改完再读一遍；负责人要是 认为评审人判错了，就把理由说给你，然后带着这个"不通过"把任务关掉。agent 唯一做不到的是在没人读过的 情况下凭自己一句话把任务关掉。你可以：该读而没读的时候你自己动手关掉它，卡片上会照实写着 —— 未评审，由你关闭 —— 而不是摆出一份没人写过的报告。

做完的任务会附一份报告，可以当场读，也可以下载。做完的项目也有自己的一份，挂在项目那一行上：整件事 最后成了什么样，这是单个任务的报告说不了的。

定时任务

会重复的活儿：一段提示词、一个日程、一个接活的 agent。每条都显示上次什么时候跑的、下次什么时候跑， 留着完整的执行历史，还能暂停和恢复，历史一条不丢。

你不用去填表建它。跟 agent 说清楚要跑什么、什么时候跑，它会替你把任务建好。

技能

技能是你的 agent 会做的事，这里列着每个技能是干什么的、应用在哪些 agent 上。一个技能可以对所有人 开放，也可以只留给某一个 agent。

和定时任务一样，装技能靠说。让 agent 去找一个技能装上，它会自己搜索、下载、安装。用不上了的那个， 点行末的垃圾桶就从磁盘上清掉，动手之前它会先问你一声。

设置

语言，以及每个 agent 一张卡片：它是谁、用哪个模型和对应的密钥、画图用哪个模型、要不要接钉钉或飞书。 MCP 服务地址在高级设置里。

用你的语言，在你的手机上

整个界面支持 English 和简体中文，在设置里选一个，其余地方都会跟着变。

Agent 页面和对话有专门为窄屏做的布局，看板的列在挤不下的时候会自动堆叠 —— 所以用手机看看 agent 干得怎么样，是可行的。

你的 agent 能做什么

用你的电脑。 agent 模式下的 agent 能读写文件、执行 shell 命令、盯着长时间运行的进程。chat 模式的只会说话 —— 当你要的是一个助手而不是一个操作员时，就该用这个。

把一个项目做到底。 领到任务的 agent 会在一段独立的对话里处理它，按需调用工具，最后回报结果。 多个任务能在不同 agent 上同时推进，看板实时跟着变。依赖关系是被尊重的：被挡住的任务会等在那儿。

互相把活读一遍。 任务可以指定另一个 agent，在关掉之前把做完的活读一遍。那个 agent 在一段独立的 运行里读它 —— 自己的上下文、你的文件、你的测试 —— 读出来的问题回到干活的人手上，改完再读一遍。报告 留在卡片上给你看。

记住重要的事。 Agent 会一边做一边记：你的偏好、你给过的规矩和纠正、你反复让它去看的那些文档和 看板的位置。一条记忆可以属于所有人、属于某一个 agent，或者属于某一个项目。

画图。 支持 OpenAI（GPT-image）、阿里（Qwen-Image）、字节（Seedream），每个 agent 可以配自己的 模型和密钥。

在钉钉或飞书里回话。 把 agent 接到即时通讯平台上，那边来的消息会走同一条对话循环，回复直接发回 聊天里。

参考

能对接的模型

• Anthropic（Claude）—— 原生的 tool-use 协议
• OpenAI —— chat completions 和 responses API
• 任何 OpenAI 兼容的端点（baseURL + apiKey）

协议是按 base URL 认出来的，而 URL 分不出 chat completions 和 responses API。认错了的端点，可以在设置 里直接指定用哪个协议。

最多 30 个 agent，每个都能配自己的模型。

技能在磁盘上的样子

一个技能就是一个文件夹，里面有 SKILL.md（frontmatter + markdown 正文），以及需要的配套文件。它们 放在 ~/.deepclaw/.agents/skills/，改动会热加载，所以你手动丢进去的技能不用重启就能被认出来。

记忆在磁盘上的样子

记忆是带 frontmatter 的 markdown 文件。每条都有作用范围和类型：

| 范围 | 覆盖到哪里 | |-------|---------------| | global | 对所有 agent 和项目生效 | | agent | 只属于某一个 agent | | project | 绑定当前的项目或定时任务 |

| 类型 | 什么时候用 | |------|---------------| | preference | 用户的风格、习惯、默认偏好 | | rules | 约束、纠正、已经定下来的决定 | | reference | 指向外部文档、看板、工单的线索 |

什么时候该写一条，agent 自己决定，依据是记忆工具描述里带着的那套准则。

子循环

交给 agent 的任务跑在一条**子循环（sub-loop）**里：一段只服务于这一个任务的对话，有自己的上下文窗口 和自己的工具权限。它读取任务和步骤，干活，边干边更新状态和步骤进度，最后产出一份结构化的输出。编排 器盯着哪些任务在跑、哪些被挡住了、哪些已经可以开始。

评审

一次评审也是这样一条被派出去的运行，跑在评审人自己的 agent 名下，不带一点点发起它的那段对话。它手上 只有四个工具，再没别的：read_file、run_sync_command、get_project_detail、submit_review —— 不能写文件，不能挪任务，除了那个结论之外没有任何说话的途径。一个回合最多同时要两次评审，因为每一次都 可能去跑同一台机器上的测试。

结论写在任务上，只保留最后一次。没有任何东西去核对它是针对哪一版做出的，所以"被驳回、改完、没再读一遍 就关掉"这件事，是靠提示词拦的，不是靠看板拦的：结论有多旧，会摆在需要照它行事的那个运行面前。

MCP（Model Context Protocol）

通过 MCP 接入外部的工具服务。任何兼容 MCP 的服务都会把自己的工具自动暴露给你的 agent —— 工具被发现 之后会加上 MCP_ 前缀，和内置工具一起可用。服务地址在高级设置里填。

内置工具

| 工具 | 作用 | |------|-------------| | read_file / write_file / edit_file | 文件操作 | | run_sync_command | 执行一条 shell 命令并等它的输出 | | run_background_command | 启动一个长时间运行的进程 | | check_background_command_status / check_all_background_command_status | 查一个后台进程，或者查全部 | | remove_background_command | 清掉一个不再需要的后台进程 | | generate_image | 用配置好的供应商生成图片 | | create_project / update_project | 创建和管理项目 | | add_task | 给进行中的项目补一个计划里漏掉的任务 | | update_task | 推进任务，归档它的产出 | | update_task_current_step | 推进任务的步骤进度 | | get_project_list / get_project_detail | 读取项目状态 | | task_loop | 把项目里的一个任务交给能继续拆分它的子 agent | | sub_loop | 为一件具体的活开一条子循环 | | work_in_worktree | 为这个任务取一份项目仓库的检出，接下来就在里面干活 | | review_task | 让任务的评审人在它关掉之前把活读一遍 | | submit_review | 交一个结论和一份报告，这是评审唯一写下的东西 | | create_cron_task / update_cron_task | 管理定时任务 | | update_cron_output | 汇报一次定时执行产出了什么 | | get_cron_histories | 回看这个定时任务此前几次执行的产出 | | load_skill_details / search_online_skills / download_skill / create_skill / remove_skill / refresh_skills | 技能操作 | | save_memory / read_memory_detail | 记下值得记的东西，以及把它读回来 | | ask_user | 向你提一个问题，等你回答 | | update_agent_runtime | 让 agent 更新自己的心情和情绪 | | base64 | base64 编解码 |

你的东西放在哪

不管你从哪个目录启动，所有东西都在 ~/.deepclaw 底下：

~/.deepclaw/
├── .deepclaw.config.json     # 设置：agent、模型、IM、MCP
├── .agents/                  # 每个 agent 的会话文件和记忆
│   └── skills/               # 装好的技能
├── .projects/                # 项目数据和任务状态
│   └── <id>/worktrees/       # 任务自己要来的那份检出
├── .cron/                    # 定时任务的定义和历史
├── .memory/                  # 全局记忆条目
├── .logs/                    # 运行日志
├── console.log               # 上一次后台启动说的话
└── deepclaw.pid              # `deepclaw stop` 停的那次运行

用 DEEPCLAW_HOME 指定另一个目录，就能让多份数据互不打扰地并存：

DEEPCLAW_HOME=~/work/deepclaw deepclaw start

让项目在别处干活

活儿是围着你手上的文件转的，就不该在 deepclaw 自己的数据旁边做。趁项目还在 todo，在看板上打开它， 指定它该在哪个文件夹里干活——一个代码仓库，一堆文档——这个项目的每一次 run 就都在那里干活：命令从那里 起跑，写下的相对路径指的是那里的文件，读写那里的文件也不必一个个问过你。跑出来的东西照旧交到这个项目 自己那一行上，那个文件夹还是你认得的样子。

文件夹在开工前定下，开工后就不再动：项目走到一半换地方，会把已经做完的一半留在原处，而且没有任何东西 说得清留在了哪。开头的 ~ 读作你的Home目录。要是指定的文件夹还不存在，看板会先问你一句——问的时候把它 解析出来的那个路径给你看，也就是真要建的那一个——你说建，它才建。

一个任务自己的检出

一个项目里互不依赖的任务会同时派出去，一个任务一个子 agent，而它们都在项目指定的那个文件夹里干活。这 个文件夹要是个代码仓库，那本身就是个麻烦：几个子 agent 改同一批文件，改动互相盖掉，提交也彼此穿插，任 务内部再小心也挡不住。要动代码的子 agent 可以改成要一个 git worktree——这个仓库的一份自己的检出，在一 个自己的分支上——这个任务的一切从此都发生在那里：它的命令、它写下的相对路径、它不必问过你就能碰的文 件，以及事后评审人读这份活儿的地方。

检出放在 deepclaw 自己的数据底下，而不是堆在你的仓库旁边，一个任务一个文件夹；分支按任务命名，形如 deepclaw/<任务叫什么>-<它 id 的尾巴>，你一眼就能看出自己仓库里哪些分支是我们建的。任务结束时什么都不 合并，也什么都不清理——分支和检出原样留着，任务报告里写明这两样在哪，合并还是丢掉由你决定。开 worktree 需要 git 2.31 或更新的版本；没能开成的任务就在项目目录里干活，并在报告里说明这件事。

开发

如果你要改 deepclaw 本身，而不只是用它：

pnpm install
pnpm web      # 网页界面
pnpm tui      # 终端界面

这两条命令直接从源码启动，不经过安装后的启动器，因此它们不会去找 ~/.deepclaw：数据会落在你执行 命令的那个目录里。用 DEEPCLAW_HOME 指一个别处，免得自己的数据混进代码库。

@sacephor/deepclaw 是这个 workspace 里唯一会发布的包。其余的都被打包或构建进了它，所以安装时不需要 再从 registry 拉 deepclaw 的任何其它东西。

pnpm build
pnpm release