Cowork

🤝 Cowork——为 Claude Code、Codex、Gemini CLI 和 Hermes Agent 提供的统一任务收件箱

一个可自托管的 MCP 服务 + Web 仪表盘，让不同的 AI 编码 Agent 共用一个任务队列。 从任意 Agent（或界面）分派任务；调度器会将任务路由到指定的执行身份（模型 × CLI × 机器），运行并验证结果，并在遇到速率限制时切换到下一个执行身份。内置工作流、产物、远程机器以及成本／用量计量功能。

• 多厂商 Agent，共用一个收件箱： Claude Code、Codex、Gemini CLI / Antigravity、Hermes、Ollama。
• 支持备用链的执行身份路由： 按角色路由、按任务固定执行身份，并在配额错误时切换。
• 磁盘上的纯文件： 任务存储采用文件形式，无需运行数据库。
• 远程执行身份： 另一台机器只需运行一条命令即可加入并提供其模型 (JOIN-AS-A-BRAIN.md)： COWORK_URL=http://<host>:6868 HOST=<you> node cowork/deploy/remote-brain-client.mjs

跳转到：快速开始 · 连接 Agent · 调度器 · 执行身份 · 工作流 · MCP 工具

截图

一个深色主题的统一操作面板，涵盖整个运行状态：实时主机指标 （CPU / GPU / 内存 / 温度）、未完成任务和 Agencies 计数器、调度器当前的 角色 → 模型链，以及实时活动动态。

本 README 中展示了 工作流、 任务收件箱、执行身份、 连接和聊天视图。

支持的平台

平台	Agent	格式
Claude Code	~285	.md，带 YAML frontmatter
Antigravity (AGY)	内置 + skills	SKILL.md
Hermes Agent	39 个 skills	SKILL.md + 触发器
Gemini CLI	从源格式转换	.md 子 Agent
GitHub Copilot	与 Claude 相同	.md Agent
Codex	已转换	.toml Agent
Cursor	已转换	.mdc 规则
+ 其他 7 个	参见 agency-agents 仓库	多种格式

---

快速开始

前置条件

• Node.js ≥ 20（已在 v22 上测试）

• npm ≥ 10

• agency-agents 仓库——作为 git 子模块包含在 cowork/agency-agents 中（Agencies——285 个 Agent）。克隆时需包含子模块：

  git clone --recurse-submodules https://github.com/slashman413/cowork
  # already cloned without it? initialise the submodule:
  git submodule update --init
  

快速安装——两个脚本（推荐）

从仓库根目录运行，需先按上文所述克隆并包含子模块：

# 1. Build + launch the server (installs deps, builds, starts a systemd user service)
deploy/install-server.sh

# 2. Drop the coordination skill + MCP connection into your agent clients on this box
deploy/install-skill.sh            # auto-detects Claude Code / Hermes / Antigravity

install-server.sh 会生成一个 systemd 单元，其中包含此机器的实际 node 路径和 工作目录（无需手动编辑）；也可以传入 --foreground，在终端中启动，或传入 --build-only，在构建完成后停止。install-skill.sh 会将对应客户端的 skill 复制到正确位置；对于 Claude Code，它还会以非破坏性方式将 mcpServers.cowork 合并到 ~/.claude.json 中（远程服务可添加 --url http://<host>:6868；使用 --client claude|hermes|agy|all 指定目标客户端）。下面的编号步骤与此过程相同， 只是拆分开来，方便手动操作。

容器（仅 hub）

docker run -d -p 6868:6868 -v cowork-data:/data ghcr.io/slashman413/cowork:1.0.1
docker logs <container>   # first start prints the generated API key once

该镜像（amd64 + arm64）运行 MCP 服务、仪表板和任务收件箱，并关闭本地调度器：Agent 连接到 http://<host>:6868/mcp，机器通过 deploy/remote-brain-client.mjs 提供其大脑（参见 JOIN-AS-A-BRAIN.md）。配置和所有状态都保存在 /data 卷中。/api 和 /mcp 始终需要密钥：使用 -e COWORK_API_KEY=… 传入自有密钥，或者服务器在首次启动时生成密钥、将其保存到 /data/api-key 并打印一次。客户端发送 Authorization: Bearer <key>（大脑客户端读取 COWORK_API_KEY）；打开一次 http://<host>:6868/?apiKey=<key>，即可登录仪表板。镜像由 .github/workflows/release.yml 根据 v* 标签构建，基础镜像固定到摘要。

1. 安装依赖项

cd cowork/server
npm install

2. 配置设置

配置保存在仓库外。 已跟踪的 cowork/config.json 仅是经过清理的模板。首次运行时，服务器会将其复制到 ~/.cowork/config.json——这是每台服务器的实际配置（主机绑定、已注册的大脑、链）。请编辑该副本，而不是模板；服务器也会将所有实时仪表板/API 编辑保存到该文件中，因此你的个人主机/大脑设置不会触及仓库。可通过 COWORK_CONFIG 环境变量指定其他位置。

编辑 ~/.cowork/config.json，使其符合你的环境：

{
  "server": {
    "port": 6868,          // ← Change the port here
    "host": "0.0.0.0",     // ← Bind address (0.0.0.0 = all interfaces)
    "name": "cowork-mcp",
    "version": "1.0.0",
    "apiKey": null          // ← Set a string to require API key auth (see below for null)
  },
  "paths": {
    "agencyAgents": "./agency-agents",  // ← Path to agency-agents repo
    "inbox": "./inbox",
    "status": "./.status",
    "decisions": "./decisions",
    "workflows": "./workflows",
    "artifacts": "./artifacts",
    "inputs": "./inputs"
  }
}

所有路径均相对于 cowork/（即 server/ 的上级目录）。 主目录路径请使用 ~（例如 ~/.claude/agents）。

关键设置

设置	默认值	说明
server.port	6868	MCP 端点和 Web UI 的 HTTP 端口
server.host	0.0.0.0	绑定地址（仅限本地时使用 127.0.0.1）
server.apiKey	null	/api 和 /mcp 的 API 密钥。当值为 null 且 host 不是环回地址时，会生成密钥并将其写入配置文件旁的 api-key，然后打印一次
server.allowUnauthenticated	false	在非环回主机上无密钥提供服务（也可设置 COWORK_ALLOW_NO_AUTH=1）。仅适用于可信且有防火墙保护的网络
paths.agencyAgents	./agency-agents	agency-agents 仓库的路径
platforms.*.enabled	true	启用/禁用各个平台
platforms.*.agentsDir	不定	平台专属 Agent 在磁盘上的存放位置
services.*.enabled	false	启用/禁用服务健康监控

3. 启动服务器

# Development mode (with hot-reload)
cd cowork/server
npm run dev

# Production mode
npm run build
npm start

你应该会看到：

🤝 Cowork MCP Server running at http://0.0.0.0:6868
   MCP endpoint: http://0.0.0.0:6868/mcp
   Web Dashboard: http://0.0.0.0:6868/
   REST API: http://0.0.0.0:6868/api/
   Agencies loaded: 285 agents across 19 divisions

4. 打开仪表板

在浏览器中打开 **http://localhost:6868**。

---

连接 AI Agent

与任何已连接模型交流的最快方式是使用仪表板的 Chat 视图：选择一个大脑，可选地指定某个部门和具体 Agent，然后发送消息；消息会作为任务分派，回复即为任务结果。

选择一个部门	…然后选择一个 Agent 角色

如需以编程方式访问，请在 Agent 客户端中配置 MCP 连接：

脚本方式（推荐）： deploy/install-skill.sh 会安装 cowork 协作技能，并为这台机器上检测到的每个 Agent 客户端配置 MCP 连接——只需一条命令，无需逐一手动编辑配置：

deploy/install-skill.sh                          # auto-detect all clients, localhost server
deploy/install-skill.sh --client claude          # just Claude Code
deploy/install-skill.sh --client all --url http://cowork-host:6868   # remote server, every client

该脚本会将各客户端的技能（规范副本位于 deploy/skills/）放入客户端当前使用的技能目录；对于 Claude Code，它会将 mcpServers.cowork 条目合并到 ~/.claude.json，且不会影响其他服务器。下方提供各客户端的手动配置，供参考。

Claude Code

将以下内容添加到 MCP 配置中（~/.claude.json 或项目级配置）：

{
  "mcpServers": {
    "cowork": {
      "url": "http://localhost:6868/mcp",
      "transport": "streamable-http"
    }
  }
}

然后在 Claude Code 中，Agent 可以调用：

Use the cowork MCP tools: register_agent, create_task, get_roster, etc.

Antigravity (AGY)

添加到你的 AGY MCP 设置中：

{
  "mcpServers": {
    "cowork": {
      "url": "http://localhost:6868/mcp"
    }
  }
}

agy 配额计量器 / 令牌刷新。 要生成 Antigravity 访问令牌，用量探测器和 deploy/remote-brain-client.mjs 需要 Google OAuth 客户端值。这些是随 agy 和 Gemini CLI 一起发布的公开值，不会提交到代码库。将 .env.example 复制到 ~/.cowork/oauth-clients.env，填写内容，然后运行 chmod 600。或者，在服务环境中导出相同的变量；进程环境变量优先。如果未设置任何值，agy 计量器仅在缓存的 CLI 访问令牌仍然有效时才能工作。

Hermes Agent

在 Hermes 中配置 MCP 端点：

{
  "mcp_endpoints": {
    "cowork": "http://localhost:6868/mcp"
  }
}

任意兼容 MCP 的客户端

该服务通过 Streamable HTTP 使用标准 MCP。任何支持 MCP 的客户端都可以连接到 http://localhost:6868/mcp。

---

任务执行 — 调度器

该服务包含一个调度器，可将排队的任务转换为实际的 Agent 运行结果。输出会成为任务的 result；完整记录会保存为任务制品目录中的 result.md。

每个任务都会进入任务收件箱，并标记运行任务的部门 / Agent 以及运行任务的大脑，同时附带可按状态筛选的输出制品（done · in-progress · pending · wait-input · failed）。

两阶段路由

未分配的任务会由编排器 / 分类器大脑（默认通过 Hermes 使用 qwen3.8-27b，orchestration.classifier）分两个阶段进行路由：

1. 部门 — 从 19 个部门中选择 1 个（测试、工程、安全，……）。
2. Agent — 从该部门约 285 个 Agent 中选择 1 个。所选 Agent 的完整 .md 角色设定会成为系统提示词。

随后，Agent 会在大脑回退链上运行（见下文）。若要跳过分类器，可直接指定目标：context.agent: "<agent-slug>" 或特殊执行器名称。为任务添加 manual 标签，可禁止其自动执行。

执行器：特殊 Agent + Agencies

• 特殊执行器（config.json → orchestration.agents）——仅有 orchestrator、generalist、video；每个执行器都是包含自身执行链的 {description, brains: [...]}。video 运行 ComfyUI LTX 流程（deploy/video-pipeline.sh；仅限 LTX，绝不使用 Wan/Hunyuan/SVD）。
• Agencies Agent — agency-agents 子模块中的约 285 个角色设定，分为 19 个部门。它们没有自己的执行链；如果部门设置了执行链，就使用部门执行链，否则使用全局默认值。

大脑回退链（GET /api/chains）

• 全局默认值 — orchestration.defaultChain；在大脑视图中拖动以重新排序（PUT /api/chains/default）。
• 按部门覆盖 — orchestration.divisionChains[<division>]；在Agent视图中设置 / 清除（PUT /api/chains/division/:division；空值 = 使用默认值）。

执行链按从上到下的顺序运行：任务先在 chain[0] 上运行；如果失败，调度器会移交给 chain[1]，然后是 [2]……每次尝试都会在任务上记录失败的大脑，直到成功或执行链耗尽。使用 context.brain: "<id>" 可将单个任务固定到一个大脑。

Agent视图会显示每个部门的执行链——拖动即可重新排序，选择 ＋ add brain… 可添加大脑，或重置为全局默认值。无需编辑模板，也无需重启。

大脑 — 命名的执行身份（模型 × 平台 × 位置）

config.json → orchestration.brains（GET /api/brains）为执行链可引用的每个大脑命名。大脑视图会列出所有已注册的大脑——其平台（claude / agy / hermes）、底层模型、位置，以及是否由连接的客户端auto注册——并支持一键注销：

别名	位置	运行内容
local-hermes-qwen3.8-27b	本地	使用该模型运行 Hermes
local-dsh-qwen3-8-27b	本地	使用该模型运行 DeepSeek Harness（dsh）
local-cc-opus-5-5 / -sonnet-5-5 / -fable-5-1	本地	使用该模型运行 Claude Code
local-agy-* / local-comfy-ltx	本地	Antigravity/Gemini / ComfyUI-LTX 视频
remote-codex-gpt-5-6-terra / -luna / -default	远程	Codex，由 Codex 客户端（在此主机上）认领
remote-ai-code-gen-cc-opus-4-8 / -sonnet-5 / -fable-5	远程	在 ai-code-gen 机器上运行 Claude Code
remote-<host>-cc-sonnet-5-5	远程	在另一台机器上运行 Claude Code

Brain ID 会包含模型版本（local-cc-opus-5-5，而非 local-cc-opus），因此从 ID 就能看出 Brain 运行的模型；只有跟随账户默认设置的 -default Brain 不带版本号。local-/remote- 前缀必须与 Brain 的 location 匹配，它表示由谁运行（local = 调度器启动；remote = 客户端从收件箱认领），而非 Brain 所在的机器。DeepSeek Brain 已停用——加载时，注册表中任何匹配 /deepseek/i 的 ID 都会被清除（参见 DENYLISTED_BRAIN_RE），因此新 ID 中切勿包含 deepseek。

重命名后的 ID 仍可使用。 server/src/config.ts 中的 BRAIN_ID_ALIASES（以及配置中的可选 orchestration.brainAliases）会将已停用的 ID 映射到其规范 ID。磁盘配置中的旧 ID、任务的 context.brain 固定值或客户端注册中的旧 ID，都会解析为规范 Brain。仍声明旧 ID 的客户端会继续以该 ID 接收任务（Brain 上的 clientId），直到它重新声明规范 ID。于 2026-10-07 重命名：

已停用的 ID	规范 ID
local-ha-qwen3-8-27b、local-ha-qwen38-27b、local-ha-qwen3.8-27b	local-hermes-qwen3.8-27b
local-codex-default / -gpt-5-6-terra / -gpt-5-6-luna	remote-codex-default / -gpt-5-6-terra / -gpt-5-6-luna
remote-ai-code-gen-cc-opus / -sonnet / -fable	remote-ai-code-gen-cc-opus-4-8 / -sonnet-5 / -fable-5

本地 Brain 由调度器在此处启动。远程 Brain 会保持 pending，调度器还会将 Brain ID 发布到任务的 context.brain，以便该机器上的客户端发现并认领它（客户端会筛选 list_inbox，查找 context.brain 属于自身 ID 之一的任务）。如果没有客户端在 orchestration.remoteGraceMs（默认为 60 s）内认领某个远程步骤，调度器就会推进到链中的下一个 Brain，因此没有客户端的远程步骤不会让任务卡住。

制品适用于两者：本地 Brain 将文件保存到 $COWORK_ARTIFACTS_DIR（调度器从磁盘收集文件）；远程 Brain 将文件保存到相同的环境目录，客户端则通过 POST /api/artifacts/:taskId/:file 上传每个文件。无论哪种方式，文件都会放到 artifacts/<task-id>/，并可从收件箱下载。

输入文件的流向相反——用户附加文件供 Brain 读取。可在聊天输入框（📎）或任意收件箱卡片（“＋ 附加文件”）上附加文件；文件会存储在 inputs/<task-id>/ 下，并同步到 context.inputFiles。调度器会在提示词中提供文件的绝对路径，供本地 Brain 使用；远程 Brain 客户端则会在运行前下载这些文件（GET /api/inputs/:taskId），并在提示词中列出本地路径。重新运行时会保留输入文件。

失败的任务与重新运行。 当任务耗尽整个回退链（所有 Brain 均未通过验证）后，会以 failed: true 标记结束。收件箱会将这些任务归入红色的 “failed” 筛选项（不计入绿色的“done”数量），并提供需要确认的 ↻ 重新运行选项，将任务从链的起点重置为 pending（POST /api/inbox/:id/rerun）——同时保留任务简介和附加的输入文件。

自动注册的大脑（客户端能力协议）

连接的 MCP 客户端通过 register_agent 工具的 brains 字段声明它能运行的大脑；服务器会自动将这些大脑添加到注册表（标记为 dynamic，归该客户端所有）。一台机器可以同时提供多个模型。自动注册的大脑会一直保留，只有通过 deregister_agent 或 Brains 视图才能移除（心跳超时不会移除）；移除时会一并从默认链、所有部门链和所有特殊 Agent 中删除。可在仪表板的 Agents 和 Brains 视图中管理以上所有内容。

接入远程大脑机器

deploy/remote-brain-client.mjs 是一个零依赖（Node 18+）的 Cowork MCP 客户端，专门用于完成这一流程。其头部注释记录了所有环境变量。

最快方式——直接运行（前台运行；适合初次测试）。单个大脑：

git clone https://github.com/slashman413/cowork
COWORK_URL=http://<cowork-host>:6868 EXEC=claude MODEL=claude-sonnet-5-5 \
  BRAIN_ID=remote-<host>-cc-sonnet-5-5 \
  node cowork/deploy/remote-brain-client.mjs

同一台机器提供多个大脑（全部声明；每个大脑都会成为可指定的目标）：

COWORK_URL=http://<cowork-host>:6868 EXEC=claude HOST=<host> \
  BRAINS='[{"id":"remote-<host>-cc-opus-5-5","model":"claude-opus-5-5"},
           {"id":"remote-<host>-cc-sonnet-5-5","model":"claude-sonnet-5-5"}]' \
  node cowork/deploy/remote-brain-client.mjs

作为启动服务运行（永久运行的机器推荐此方式）：

mkdir -p ~/.config/cowork-remote-brain
cp cowork/deploy/remote-brain-client.env.example ~/.config/cowork-remote-brain/aicodegen.env
# edit: COWORK_URL, BRAINS (or BRAIN_ID), EXEC, HOST, COWORK_CLIENT_JS
cp cowork/deploy/[email protected] ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now cowork-remote-brain@aicodegen

它会连接到 COWORK_URL/mcp，调用 register_agent（声明其 BRAINS，并自动将这些大脑注册到注册表），随后轮询并认领 context.brain 为其某个大脑 ID 的任务，运行对应的 EXEC/MODEL，并使用结果和上传的工件调用 complete_task——与其他客户端一样显示在 Connections 中。灵活：只需更改环境变量，同一脚本即可服务于任意大脑。可扩展：添加 <name>.env 文件即可增加机器和大脑；任务认领是原子操作（单进程比较并设置），因此即使多个客户端使用同一个大脑 ID，也不会重复运行任务——先认领者胜出。

每个已连接的客户端都会实时显示在 Connections 视图中，按平台分组，并列出其提供的大脑、空闲/忙碌状态，以及每个会话中各个大脑已运行和已提交的任务数统计：

Connections 中显示为 cowork/orchestrator 的常驻协调 Agent 会轮询收件箱、通过两阶段路由分配未指派的任务、重新认领孤立任务并进行调度；临时的单任务工作进程在运行时会显示为 testing / Workflow Optimizer · local-hermes-qwen3.8-27b 或 video · local-comfy-ltx 等名称。

CEO 工作流：向 Hermes（例如通过 Discord）提出一个想法 → Hermes 使用 context.agent: "orchestrator" 创建一个任务 → 协调 Agent 通过 POST /api/inbox 将其拆分为子任务 → 每个子任务经两阶段路由分配给其大脑链上的 Agent → 结果和工件实时显示在仪表板上。

LLM 分类器——不遗漏任何任务

未分配的任务（例如直接从 Discord 提交的自由文本想法）不再会停滞：调度器会运行两阶段 LLM 路由器（默认通过 Hermes 使用 qwen3.8-27b，配置项为 config.json 中的 orchestration.classifier），读取任务、选择部门，然后选择 Agent，再由该 Agent 按其大脑链正常调度。为任务添加 manual 标签即可跳过路由和调度。

重新认领过期任务

orchestration.staleClaimMs（默认 30 分钟）会重新认领任意正在进行、但其认领 Agent 已消失的任务——例如崩溃或退出的实时 Agent，或在运行期间被终止的调度器——并将其状态改回 pending，以便重试。仍由正在发送心跳的 Agent 所有的任务不会受到影响。

调度器状态：GET /api/dispatcher。可在配置中调整 orchestration.maxConcurrent / taskTimeoutMs / pollIntervalMs / classifier / staleClaimMs。

部署（systemd）与远程访问

最简单的方式是运行 deploy/install-server.sh，它会使用本机解析出的 Node 路径和工作目录生成并启用用户服务：

deploy/install-server.sh          # build + install & start the cowork-mcp user service

手动执行的等效方式（受版本控制的 deploy/cowork-mcp.service 中有 /home/USER 占位符，必须先编辑——脚本会替你填好）：

cp deploy/cowork-mcp.service ~/.config/systemd/user/   # then edit the USER/paths inside
systemctl --user daemon-reload
systemctl --user enable --now cowork-mcp

设置 server.host: "0.0.0.0" 后，其他机器可通过 http://<host-ip>:6868/ 访问仪表板（局域网或 Tailscale IP——0.0.0.0 本身是绑定地址，不是 URL）。非回环主机始终需要密钥：设置 server.apiKey（或 COWORK_API_KEY），或者使用首次启动时在配置文件旁生成到 api-key 文件中的密钥。通过 http://<host-ip>:6868/?apiKey=<key> 登录仪表板一次（这会设置一个同站 Cookie）。设置 server.allowUnauthenticated: true 可选择不启用身份验证；届时任何能访问该端口的人都可以为你的 brains 创建任务。

**将正在运行的开放 hub 切换为使用密钥，同时不把任何人拒之门外：**设置密钥，同时保留 allowUnauthenticated: true。这就是软（迁移）模式：有效密钥会被接受，无效密钥会收到 401，而不带密钥的请求仍会通过，但会列在 GET /api/auth/keyless 中（需要密钥）。将密钥提供给每个客户端（brain 客户端：COWORK_API_KEY；MCP 配置：Authorization: Bearer <key> 标头，例如 deploy/install-skill.sh --key <key>；仪表板：访问 /?apiKey=<key> 一次）。派发的任务会自动在其环境中获得 COWORK_API_KEY。当 /api/auth/keyless 中没有条目时，移除 allowUnauthenticated 并重启以强制启用身份验证。

从 HTTP 切换到 HTTPS

默认情况下，服务器通过纯 http:// 监听。在 localhost 上这样没问题，但浏览器只会在安全上下文中开放麦克风（新建任务中的 听写 语音转文字按钮）——即 https:// 或 http://localhost。如果通过 http://<lan-or-tailscale-ip>:6868 访问仪表板，navigator.mediaDevices 就是 undefined，因此无法启动听写。通过 HTTPS 提供服务即可解决此问题。

只要 server.tls 指向磁盘上存在的证书/密钥文件，服务器就会自动提供 HTTPS；如果文件缺失，则会记录警告并回退到 http://。请按以下顺序迁移——请谨慎执行切换，因为所有仍指向 http://…:6868/mcp 的 MCP 客户端和技能都会在协议切换的那一刻失效：

1. 生成证书/密钥（对于 LAN/tailnet，自签名证书即可）。将要访问的所有主机名/IP 都包含为 SAN：

   server/gen-tls-cert.sh ~/.cowork/tls cowork-host 100.80.243.33 cowork.tailXXXX.ts.net
   

   若要在 Tailscale tailnet 上使用无警告证书，请优先使用 tailscale serve（真实的 Let's Encrypt 证书），而不是自签名证书。

2. 将配置指向这些文件。 在 ~/.cowork/config.json（实际生效的配置——仓库中的 config.json 只是默认模板，内含 "tls": null）里的 server 下添加 tls 块：

   "server": {
     "host": "0.0.0.0",
     "port": 6868,
     "tls": { "certFile": "~/.cowork/tls/cert.pem", "keyFile": "~/.cowork/tls/key.pem" }
   }
   

   ~ 和相对于仓库的路径会自动解析。**最容易漏掉的就是这一步：**单独生成证书不起作用——没有这个块，服务器仍会使用 http://。

3. 重启服务器以应用新的协议。 在任务运行期间执行普通的 systemctl --user restart cowork-mcp 会向该任务发送 SIGKILL（它是正在重启的单元的子进程），因此请使用可安全等待任务空闲的重新部署方式，它会等到没有任务运行时再执行：

   systemd-run --user --collect --unit=cowork-server-redeploy \
     deploy/redeploy-server-when-idle.sh
   

   确认服务器已通过 HTTPS 启动：

   journalctl --user -u cowork-mcp -n 5 | grep 'API:'
   curl --cacert ~/.cowork/tls/cert.pem https://localhost:6868/api/status | jq .uptime   # HTTPS handshake + a live number
   

4. 将所有客户端重新指向 https://。 使用 https URL 重新运行安装程序，以更新每个客户端的 mcpServers.cowork 条目和技能，然后重启客户端：

   deploy/install-skill.sh --client all --url https://cowork-host:6868
   

   使用 COWORK_URL=http://… 启动的远程 brain 客户端必须改用 COWORK_URL=https://… 重新启动。自签名证书会触发一次性浏览器警告（“继续访问网站”）——继续访问后，该来源就属于安全上下文，听写功能也能正常使用。

   Node 客户端必须信任自签名证书，否则 MCP 握手会因 SELF_SIGNED_CERT_IN_CHAIN 失败。在启动客户端的环境中（例如运行 claude 的 shell，或 remote-brain 客户端的环境）将证书指定为额外 CA：

   export NODE_EXTRA_CA_CERTS=~/.cowork/tls/cert.pem
   

   相比之下，应优先使用此方法，而不是 NODE_TLS_REJECT_UNAUTHORIZED=0（它会完全禁用验证）；只有在信任 CA 确实不切实际时，才在私有 tailnet 上退而使用后者。

服务器端的自调度已能识别协议，无需配置。 调度器会根据 server.tls 构建编排器的 curl 命令和子 brain 的 COWORK_API 环境变量，因此启用 TLS 后，它们会指向 https://localhost:6868（curl 使用 --cacert，Node 子进程会自动注入 NODE_EXTRA_CA_CERTS）。切换协议后，仓库中不会残留硬编码的 http://localhost:6868。

如需回滚，将 server.tls 设为 null（或移除该块）并重新部署——服务器将恢复为 http://。

MCP 工具参考

连接后，Agent 可以使用以下工具：

工具	描述
register_agent	注册此客户端；可选择声明它能运行的 brains
deregister_agent	移除此客户端，并级联移除它注册的所有 brain
heartbeat	更新状态和当前任务
get_roster	搜索 19 个部门中的约 285 个 Agent
create_task	为其他 Agent/平台创建任务
claim_task	领取待处理的收件箱任务
complete_task	将任务标记为已完成并附上结果
list_inbox	按状态/平台筛选并列出收件箱任务
get_dashboard	获取完整的仪表板数据（活跃 Agent、收件箱统计等）

示例：跨平台任务调度

You: "Review the auth code in saas-starter"

AGY Agent calls:
  create_task(
    title: "Review auth middleware",
    from_platform: "antigravity",
    from_agent: "self",
    to_platform: "claude",
    to_agent: "engineering-code-reviewer",
    priority: "normal"
  )

→ Task appears in dashboard inbox
→ Claude Code picks it up, runs review
→ Claude calls complete_task(...) with its result + artifacts
→ Result + artifacts appear on the task card

---

工作流——声明式流水线，两种执行模式

工作流是一个受版本控制的模板（workflows/<id>.json）。它会以以下两种模式之一运行，通过模板中的 "mode" 选择：

工作流视图会将每个模板呈现为实时图：既包括顺序串联流水线，也包括并行扇出／扇入的菱形结构；每个步骤都会指定一个部门或 Agent，并提供 Dry run（检查解析后的计划）和 Run 控件：

build-and-ship — 5 步工程流水线	expand-perspectives — 并行的多视角扇出 → 综合

• dag（默认）——**静态且确定。**步骤构成一个通过 dependsOn 连线的 DAG；整个图会预先展开为收件箱任务，调度器再按依赖顺序处理。无需新增执行引擎：展开操作只是预先连好调度器本来就会运行的任务。多步骤作业因此变得可复用、可检查，而不必每次都让大模型从头重新规划。
• orchestrated —— 自适应，由编排器驱动。这些步骤是一个候选操作库；不会预先规划任何内容。每个步骤完成后，编排器大脑会根据 goal 和迄今为止的结果，自动决定下一步，也可以回答 DONE。执行路径会根据返回结果自适应调整。每个决策（所选步骤及其理由）都会记录到 workflow-runs/<runId>.json，并在仪表板中呈现为决策日志。

DAG 模式

模板由一系列步骤组成；每个步骤都是一个任务，具有稳定的 key，其他步骤通过 dependsOn 引用它（运行时会解析为实际任务 ID）：

{
  "id": "content-pipeline",
  "params": ["topic"],
  "steps": [
    { "key": "research", "title": "Research: {{topic}}", "division": "marketing" },
    { "key": "draft",    "title": "Draft {{topic}}", "division": "marketing", "dependsOn": ["research"] },
    { "key": "review",   "title": "Review {{topic}}", "agent": "code-reviewer", "dependsOn": ["draft"] },
    { "key": "publish",  "title": "Publish {{topic}}", "division": "marketing", "dependsOn": ["review"] }
  ]
}

运行它（或使用 dry-run 检查解析后的计划，而不创建任何内容）：

curl -s -X POST localhost:6868/api/workflows/content-pipeline/run \
  -H 'content-type: application/json' -d '{"params":{"topic":"RISC-V laptops"}}'

运行创建的每个任务都会携带 context.workflowId、context.workflowRunId 和 context.stepKey，以便仪表板中的工作流选项卡对运行进行分组，并按节点实时状态呈现其 DAG。加载模板时会进行验证（键唯一、依赖项存在，且图为无环图——否则循环会导致 dependsOn 永久死锁）；未通过验证的模板会被跳过，而不会导致列表崩溃，并会在仪表板中显示原因（也可通过 GET /api/workflows-invalid 查看），便于修复格式错误的模板。步骤可以指定 agent、division 或 brain，也可以不指定，让路由器自行选择。

编排（自适应）模式

将 "mode" 设为 "orchestrated"，为模板设置 goal，并将步骤列为候选库（dependsOn 会成为可选提示，用于在上游步骤已运行时连接步骤的输入）。运行时会写入一条运行记录，不会创建任何任务——调度器的编排循环会在下一个时钟周期做出第一个决定，此后每个步骤完成后再做出一个决定：

{
  "id": "adaptive-research",
  "mode": "orchestrated",
  "goal": "Produce a decision-ready brief answering: {{question}}",
  "params": ["question"],
  "steps": [
    { "key": "scope",     "title": "Scope the question", "division": "operations" },
    { "key": "survey",    "title": "Broad survey", "division": "operations" },
    { "key": "deep-dive", "title": "Deep dive on the crux" },
    { "key": "counter",   "title": "Steelman the opposing view" },
    { "key": "brief",     "title": "Write the decision brief" }
  ]
}

编排器的大脑（路由模型——orchestration.classifier，否则为编排器/默认链中的第一个可在本地运行的大脑）会接收目标、已完成的步骤及其结果，以及剩余的候选步骤作为提示；它会回复一个步骤键或 DONE。orchestration.maxWorkflowSteps（默认值为 12）会强制结束编排器始终不返回 DONE 的运行。

两种模式都会为每个任务写入 context.workflowId、context.workflowRunId 和 context.stepKey，这样 Workflows 选项卡就可以将一次运行归组并实时呈现——静态运行显示为 DAG，自适应运行显示为决策时间线。模板会在加载时验证（键唯一、依赖项存在，且 DAG 模式下图必须为无环图）；未通过验证的模板会被跳过，不会导致列表崩溃，原因也会显示在控制面板中（以及 GET /api/workflows-invalid 中）。

引擎（验证、环路检测、拓扑展开、DAG 布线、运行重建和编排决策循环）有测试套件覆盖——cd server && npm test。

随附的公司工作流

workflows/ 目录随附了一组真实的跨职能公司流程。每个步骤都会指定一个 division 或 agent（绝不指定 brain），因此每个角色的大脑回退链都可以在控制面板的 Agents 视图中编辑（特殊 Agent 使用 orchestration.agents[*].brains；Agent 使用 divisionChains[*] / defaultChain）——无需修改模板即可更换执行步骤的对象。

工作流	模式	用途
idea-to-launch	dag	旗舰工作流。CEO 简报 → 市场调研 + 多方视角 → PM 规格说明 → 架构设计 → 工程师构建真实产品并通过 GitHub Actions 推送到 GitHub → 营销推广 + 邮件自动回复 → 销售赋能 → 财务模型 → 幕僚长进行是否继续的审核。params: idea
product-spec	dag	PM 撰写可直接用于构建的 PRD，结合用户调研和工程可行性分析，再拆分为可交付的首个冲刺。params: idea
build-and-ship	dag	从规格说明出发 → 架构设计 → 派遣工程师编写真实代码 → 接入 GitHub Actions CI 流水线 → 代码审查 → 推送并验证流水线通过。params: spec
feedback-to-roadmap	dag	来自员工/客户的原始反馈 → 分类处理 → 提炼主题 → PM 制定行动方案 → 排定路线图优先级 → 将“现在”事项派发为实际工作。params: feedback
gtm-campaign	dag	营销与销售协同制定上市方案：优惠与促销角度 → 邮件序列及入站自动回复规则 → 内容 → 销售赋能 → 成功指标。params: product
finance-close	dag	会计周期：簿记员对账 → FP&A 差异分析 → 前瞻模型 → CFO 签字批准 + 董事会摘要。params: period
expand-perspectives	dag	研究人员从四个独立视角（第一性原理、先例、反向思考、二阶效应）并行深入研究一个想法，然后综合形成可供决策的观点图谱。params: idea
adaptive-research	orchestrated	自适应深度研究——编排器只会针对目标所需之处深入探索。params: question
plan-execution	orchestrated	将计划转化为派发的任务，并推动其完成验证。params: plan
content-pipeline	dag	研究 → 起草 → 审核 → 发布。params: topic
product-brief	dag	市场 + 技术 + 风险并行分析 → 一页式继续/停止简报。params: idea

# Run the flagship end-to-end company workflow:
curl -s -X POST localhost:6868/api/workflows/idea-to-launch/run \
  -H 'content-type: application/json' -d '{"params":{"idea":"a self-hosted receipts scanner"}}'

REST API

Web UI 使用以下端点（也可用于脚本/集成）：

方法	路径	描述
GET	/api/status	仪表板概览数据
GET	/api/agents	所有活动 Agent（id → name）
GET	/api/connections	在线 MCP 客户端（心跳）+ 每个 brain 的已运行/已提交计数器
GET	/api/inbox?status=pending	收件箱任务（可筛选）
POST	/api/inbox	创建新任务；可选的 inputs: [{token,name}] 用于附加已上传文件
PATCH	/api/inbox/:id	认领或完成任务
POST	/api/inbox/:id/rerun	将 FAILED（链已耗尽）任务重新排入队列 — 从其链的起点重置为待处理，并保留其输入
GET/POST	/api/inbox/:id/inputs	列出/向现有任务附加输入文件（{inputs:[{token,name}]}）
POST	/api/uploads?name=<file>	暂存已上传的文件（原始请求体）→ {token}，以便作为任务输入传入
GET	/api/inputs/:taskId, /:taskId/:file	列出/下载任务附加的输入文件
GET	/api/workflows / /api/workflows/:id	声明式工作流模板（经过验证）
GET	/api/workflows-invalid	加载失败的模板及其原因（JSON/验证错误）
POST	/api/workflows/:id/run	开始运行：将 DAG 模板展开为任务，或开始编排运行；{ params, dryRun }
GET	/api/workflow-runs / /api/workflow-runs/:runId	运行视图中的运行记录（DAG 按任务分组；编排运行来自运行记录 + 决策日志）
GET	/api/roster?division=engineering	Agencies（可筛选）
GET	/api/roster-divisions	按 division 分组的 Agencies（用于 Agents 视图）
GET	/api/dispatcher	特殊 Agent + brains + defaultChain + divisionChains + running
GET/PUT	/api/chains, /chains/default, /chains/division/:div	读取/编辑 brain 回退链
GET/PUT/DELETE	/api/brains, /api/brains/:id	Brain 注册表（删除时级联处理）
GET/PUT/DELETE	/api/agents-config, /api/agents-config/:name	特殊执行器链
GET/POST	/api/artifacts/:taskId, /:taskId/:file	列出/下载；POST（原始请求体）从远程 brain 上传文件
GET	/api/config	当前配置
GET	/api/events	SSE 事件流

---

目录结构

cowork/
├── config.json              # TEMPLATE only — real config at ~/.cowork/config.json
├── README.md                # This file
├── PROTOCOL.md              # Protocol specification
├── JOIN-AS-A-BRAIN.md       # Onboarding for a remote brain client
├── agency-agents/           # git SUBMODULE — the Agencies (~285 agents)
├── workflows/               # Workflow templates (*.json) — DAG + orchestrated
├── workflow-runs/           # Orchestrated run records + decision logs (gitignored)
├── server/                  # MCP Server + Web UI
│   ├── src/                 # TypeScript source
│   └── public/              # Web UI (HTML/CSS/JS)
├── deploy/                  # systemd units, remote-brain client, presets, skills
├── inbox/                   # Task queue (JSON files, auto-managed)
├── artifacts/               # Per-task OUTPUT files (audio/video/md), downloadable
├── inputs/                  # Per-task INPUT files a person attached for the brain (gitignored)
├── decisions/               # Decision log
└── .status/                 # Runtime state (auto-managed)

---

调试

MCP Inspector

使用官方 Inspector 测试 MCP 端点：

npx @modelcontextprotocol/inspector http://localhost:6868/mcp

这会在 http://localhost:6274 打开 Web UI，你可以在其中交互式浏览和测试所有 MCP 工具。

curl 示例

# Check server status
curl http://localhost:6868/api/status | jq

# List active agents
curl http://localhost:6868/api/agents | jq

# List pending inbox tasks
curl "http://localhost:6868/api/inbox?status=pending" | jq

# Browse engineering agents in Agencies
curl "http://localhost:6868/api/roster?division=engineering" | jq

# Watch real-time events
curl -N http://localhost:6868/api/events

测试 MCP 工具调用

# Register a test agent
curl -X POST http://localhost:6868/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "register_agent",
      "arguments": {
        "platform": "antigravity",
        "agent_name": "test-agent",
        "current_task": "Testing MCP connection"
      }
    },
    "id": 1
  }'

# Get dashboard data
curl -X POST http://localhost:6868/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_dashboard",
      "arguments": {}
    },
    "id": 2
  }'

---

配置参考

完整的 config.json 示例

{
  "server": {
    "port": 6868,
    "host": "0.0.0.0",
    "name": "cowork-mcp",
    "version": "1.0.0",
    "apiKey": null
  },
  "paths": {
    "agencyAgents": "./agency-agents",
    "inbox": "./inbox",
    "status": "./.status",
    "decisions": "./decisions",
    "workflows": "./workflows",
    "artifacts": "./artifacts",
    "inputs": "./inputs"
  },
  "platforms": {
    "claude": {
      "enabled": true,
      "agentsDir": "~/.claude/agents",
      "color": "#D97757"
    },
    "hermes": {
      "enabled": true,
      "skillsDir": "../hermes-agent/skills",
      "color": "#7C3AED"
    },
    "antigravity": {
      "enabled": true,
      "skillsDir": "~/.gemini/config/skills",
      "color": "#0EA5E9"
    }
  },
  "inbox": {
    "autoArchiveDays": 30,
    "maxRetries": 3
  }
}

Portal 启动器卡片存放在独立文件 portal.json 中（实时副本 ~/.cowork/portal.json，支持热重载）——请参阅 docs/dashboard.md#portal。

特定环境的覆盖设置

默认情况下，系统从 ~/.cowork/config.json 读取实际配置。使用 COWORK_CONFIG 环境变量指定其他文件（并可在不编辑任何文件的情况下覆盖端口/API 密钥）：

COWORK_CONFIG=~/.cowork/config.staging.json COWORK_PORT=6900 npm start

Agencies 目录会缓存在内存中，并且最多每隔 COWORK_ROSTER_TTL_MS （默认值为 30000）重新扫描一次。在此时间窗口内，新 Agent/子模块更新会生效，无需 重启；设置为 0 可在每次查询时重新扫描，设置为更大的值可减少磁盘操作。

---

Cowork Pro

Cowork Pro（$59） 是面向生产环境的 套件：提供高级工作流、优先支持和终身更新。它也包含在 AI Developer Stack Bundle（$79） 中。

许可证

MIT © 2026 slashman413。核心服务、仪表板和远程 brain 客户端免费且开源；Cowork Pro（见上文）是单独付费的附加产品。