AI编程代理看板调度中心：Claw-Kanban的设计、部署与实战

1. 项目概述：一个为AI编程代理设计的看板调度中心

如果你和我一样，日常开发中会同时使用多个AI编程助手——比如Claude Code、GitHub Copilot、Codex CLI，那么你一定也经历过这种混乱：为了一个任务，需要在几个终端窗口之间来回切换，手动决定哪个助手更适合当前的工作，然后盯着空白的终端等待它完成，整个过程既低效又割裂。Claw-Kanban就是为了解决这个痛点而生的。它是一个本地运行的AI代理编排看板，你可以把它理解为一个专为AI编程助手设计的“任务调度中心”或“指挥台”。

它的核心价值在于，将你手头分散的AI能力（目前支持Claude Code、Codex CLI、Gemini CLI、OpenCode、GitHub Copilot和Google Antigravity这六种）整合到一个统一的视觉化界面里。你不再需要记住每个工具的启动命令，或者纠结于“这个bug该让Claude还是Copilot来修”。你只需要在看板上创建一个任务卡片，Claw-Kanban会根据你预设的规则（比如“后端任务给Codex”、“前端Bug给Claude”）自动分配最合适的AI代理去执行。更重要的是，整个过程是实时可视的。卡片进入“进行中”状态后，你可以直接在浏览器里打开一个终端视图，像看直播一样看到AI助手正在执行的每一条命令、生成的每一行代码，彻底告别“盲等”。

这个工具特别适合独立开发者、小团队的技术负责人，或者任何希望将AI编程助手的工作流标准化、自动化的人。它不改变你已有的AI工具配置，而是作为一个轻量的协调层运行在你本地。接下来，我会详细拆解它的设计思路、如何从零部署、核心功能的使用技巧，以及我在实际使用中踩过的坑和总结的经验。

2. 核心架构与设计哲学：为什么是“双执行模型”？

Claw-Kanban在技术实现上最精妙的设计，莫过于其“双执行模型”（Dual Execution Model）。这不仅仅是支持6个AI代理那么简单，而是根据代理的不同性质，采用了两种截然不同的调用方式，从而在便利性、安全性和功能继承上取得了最佳平衡。理解这一点，是高效使用这个工具的关键。

2.1 CLI代理：继承你的完整开发环境

CLI代理包括Claude Code、Codex CLI、Gemini CLI和OpenCode。它们的共同点是：你已经在自己的电脑上通过npm install -g安装了它们的命令行工具，并且用claude login、codex auth login等方式完成了认证。

当Claw-Kanban需要调用一个CLI代理时，它做的不是去访问某个远程API，而是在你的本地操作系统上，启动一个该CLI工具的子进程。这意味着，这个子进程会完整继承你当前Shell环境中的所有配置：

• 自定义技能与代理：如果你为claude配置了自定义的skills目录或agents，子进程同样拥有这些能力。
• MCP服务器连接：你本地配置的Model Context Protocol服务器（比如文件系统、Git仓库的MCP服务）会被自动连接上。
• 项目特定指令：项目根目录下的CLAUDE.md、.cursorrules等文件会被CLI工具读取并遵守。
• 所有环境变量与认证：包括你的OPENAI_API_KEY、ANTHROPIC_API_KEY等敏感信息，都通过环境变量安全地传递给子进程。

实操心得：环境继承是一把双刃剑这带来了巨大的便利，因为你无需在Claw-Kanban里重新配置一遍所有密钥和设置。但这也意味着，Claw-Kanban服务器的运行环境（比如你启动它的那个终端）决定了AI代理能看到什么。我建议专门为一个项目启动Claw-Kanban时，先cd到该项目目录，再运行pnpm start。这样，所有由此看板派发的任务，其AI代理都会默认在该项目上下文中工作，能正确读取到项目的.gitignore、package.json等文件。

2.2 HTTP代理：零安装的云端直连

HTTP代理目前包括GitHub Copilot和Google Antigravity。对于它们，Claw-Kanban采用了另一种方式：直接调用其官方API。

你不需要在本地安装copilot或antigravity的CLI。你只需要在Claw-Kanban的Web设置界面里，点击“OAuth Connect”按钮，用你的GitHub或Google账号登录授权。之后，Claw-Kanban的服务器会帮你管理OAuth令牌，并用这些令牌直接向Copilot或Antigravity的API发起请求。

• 优势：部署极其简单，特别适合在那些无法安装CLI工具或网络受限的环境（例如某些Docker容器或严格管控的服务器）中使用。
• 安全机制：所有获取到的OAuth刷新令牌（Refresh Token）都会使用你设置的OAUTH_ENCRYPTION_SECRET环境变量进行AES-256-GCM加密，然后才存入本地的SQLite数据库。前端页面永远接触不到这些原始令牌。访问令牌（Access Token）仅在内存中缓存，并会定期刷新或过期失效。

2.3 设计背后的权衡

这种双模型设计，体现了开发者对实际使用场景的深刻理解：

1. 对于重度定制用户：CLI模型保证了极致的灵活性和个性化，你的所有“魔法”配置都能无缝迁移。
2. 对于追求开箱即用的用户：HTTP模型降低了使用门槛，点几下鼠标就能用上强大的Copilot。
3. 对于混合环境：你可以让Claude处理复杂的架构设计（利用其强大的MCP上下文），同时让Copilot快速生成一些样板代码，在看板上并行不悖。

这种架构也决定了安装后的配置重点：CLI代理，请确保你的命令行工具已登录；HTTP代理，请务必在设置中完成OAuth连接。两者互不干扰，你可以按需启用。

3. 从零开始：详细部署与配置指南

虽然项目提供了炫酷的“AI一键安装”指令，但作为一个老手，我更喜欢手动走一遍流程，这能帮你理解各个组件是如何协作的，出问题时也能快速定位。下面是我在macOS/Linux环境下的标准部署流程，Windows的PowerShell步骤逻辑类似。

3.1 环境准备与依赖检查

首先，确保你的系统满足最低要求。Node.js 22+是硬性要求，因为它内置了node:sqlite模块，Claw-Kanban用它来存储数据，避免了额外安装SQLite3的麻烦。

# 1. 检查Node.js版本，必须 >= 22 node -v # 如果版本低于22，强烈建议使用nvm管理 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重新打开终端后 nvm install 22 nvm use 22 # 2. 检查包管理器，推荐pnpm，速度更快 pnpm -v # 如果未安装，用npm安装 npm install -g pnpm # 3. 检查至少一个AI CLI代理是否可用 # 这是核心，Claw-Kanban本身不提供AI能力，它只是调度器。 which claude || which codex || which gemini || which opencode # 如果没有任何输出，你需要先安装并登录至少一个。 # 例如，安装Claude Code： npm install -g @anthropic-ai/claude-code claude login # 按照提示完成浏览器认证即可。

注意事项：认证状态是关键which命令只能检查是否安装了CLI。安装后，务必执行登录（login）操作。Claw-Kanban会通过检查你的本地配置文件（如~/.claude.json）来判断是否已认证。未认证的代理在看板的下拉列表中会被禁用。

3.2 克隆、构建与启动服务

环境就绪后，获取项目代码并启动服务。

# 1. 克隆仓库 git clone https://github.com/GreenSheep01201/Claw-Kanban.git cd Claw-Kanban # 2. 安装依赖并构建前端 pnpm install # 构建过程会生成dist目录，包含编译好的前端资源 pnpm build # 3. 启动生产服务器 pnpm start

启动成功后，终端会显示类似Server running on http://127.0.0.1:8787的信息。此时，用浏览器打开这个地址，你应该能看到看板界面。

3.3 核心配置详解：.env 文件

项目根目录下的.env.example是配置模板。我们需要复制它并修改为自己的配置。

cp .env.example .env

现在，打开.env文件，以下几个配置项需要你特别关注：

# .env 关键配置项说明 PORT=8787 HOST=127.0.0.1 DB_PATH=./kanban.sqlite LOGS_DIR=./logs # 1. OAuth加密密钥（重要！） OAUTH_ENCRYPTION_SECRET=your-super-secure-random-string-here

• HOST: 默认127.0.0.1只允许本机访问。如果你希望通过局域网（比如同一WiFi下的iPad）或者Tailscale等虚拟局域网访问看板，可以改为0.0.0.0。安全警告：改为0.0.0.0后，同一网络内的任何设备都能访问你的看板，因为它没有用户认证功能。请仅在可信网络环境下使用。
• OAUTH_ENCRYPTION_SECRET:这是最重要的安全配置之一。它用于加密存储GitHub/Google的OAuth令牌。请务必设置一个足够长且复杂的随机字符串。一旦设置，不要轻易更改，否则之前存储的加密令牌将无法解密。你可以用命令生成一个：openssl rand -base64 32。

3.4 连接HTTP代理（Copilot/Antigravity）

启动服务并打开浏览器后，点击界面右上角的“Settings”按钮。

1. 在设置面板中，找到“AI Providers”区域。系统会自动检测已安装的CLI代理并显示其状态（如“Claude Code: Ready”）。
2. 向下滚动，找到“OAuth Connect”区域。
3. 点击“GitHub”或“Google”按钮，会弹出一个新的浏览器标签页，引导你完成标准的OAuth授权流程。
4. 授权成功后，页面会自动关闭，回到看板设置页，你会看到对应Provider的状态变为“Connected”。

避坑技巧：OAuth连接失败排查如果点击连接按钮没反应，或者授权后无法跳回，请检查：

1. .env中的HOST和PORT：OAuth回调地址是基于HOST:PORT构建的。如果你用localhost:8787访问，但HOST设为127.0.0.1，可能造成回调地址不匹配。确保你浏览器访问的地址和.env中的配置一致，或者显式设置OAUTH_BASE_URL=http://你的实际访问地址:端口。
2. 浏览器弹窗拦截：确保没有拦截弹出窗口。
3. 服务器日志：查看运行pnpm start的终端，是否有相关的错误日志。

3.5 集成到工作流：AGENTS.md 设置

这是让Claw-Kanban变得智能的关键一步。AGENTS.md是你项目根目录下的一个文件，用于指导AI代理（如Claude Code）如何与你的项目交互。Claw-Kanban的pnpm setup命令，会向这个文件头部插入一套“编排规则”。

# 在Claw-Kanban项目目录下执行 pnpm setup

这条命令会自动寻找你当前工作空间（通常是启动命令的目录）的AGENTS.md文件，如果找不到，它会尝试在父目录中寻找。你也可以指定路径：

pnpm setup -- --agents-path /your/project/path/AGENTS.md

插入的规则主要做两件事：

1. 任务识别：告诉AI代理，当用户输入以#开头的消息时（例如“# 修复登录按钮的样式”），这应该被识别为一个需要创建看板卡片的“任务”。
2. 交互逻辑：指导AI代理如何通过调用Claw-Kanban的API（/api/inbox）来创建卡片，以及在执行任务前如何检查project_path、如何报告进度等。

实操心得：AGENTS.md是双向通信的桥梁不要仅仅把pnpm setup当作一个一次性命令。当你切换不同的项目目录时，可以重新运行它，将看板规则注入到不同项目的AGENTS.md中。这样，无论你在哪个项目里和AI对话，它都能理解“#任务”的语义，并将任务提交到同一个中央看板进行统一调度。这实现了跨项目的任务集中管理。

4. 看板核心功能实战与技巧

服务跑起来，配置也做好了，现在我们来真正用起来。看板界面简洁直观，但其中蕴含的高效工作流需要一些实践才能完全掌握。

4.1 创建任务与自动分配

创建任务有三种主要方式：

1. 网页界面手动创建：点击看板“Inbox”列上的“+”按钮，填写标题、描述，选择角色（Role）和任务类型（Type）。
2. 通过API创建：方便与其他工具集成，比如你的脚本。

   curl -X POST http://localhost:8787/api/cards \ -H 'Content-Type: application/json' \ -d '{ "title": "重构用户认证模块", "description": "将当前的Session认证改为JWT，并增加刷新令牌机制。", "role": "Backend", "type": "Modify", "project_path": "/Users/yourname/projects/auth-service" }'

3. 通过Webhook/聊天集成：这也是最酷的方式之一。配置好Telegram Bot或Slack Incoming Webhook后，你只需要在聊天窗口发送“# 修复登录页面的CSS响应式问题”，一张卡片就会自动出现在看板的“Inbox”中。

自动分配的奥秘在于设置中的“Role-based Providers”和“FrontEnd Providers”。系统会根据你创建卡片时选择的role和type，自动匹配并分配预设的AI代理。默认规则是：

• role: DevOps-> Claude Code
• role: Backend-> Codex CLI
• role: Frontend+type: New-> Gemini CLI
• role: Frontend+type: Modify/Bugfix-> Claude Code

你可以在Settings里完全自定义这套映射关系。比如，你可以把所有Bugfix类任务都交给Claude，因为它在代码诊断上可能更擅长。

4.2 项目路径（project_path）：安全运行的基石

这是Claw-Kanban一个非常重要的安全设计。每个任务都必须在一个明确的项目目录下执行，以防止AI代理误操作你的系统文件。

设置project_path有三种方式，优先级从高到低：

1. 卡片专用字段（推荐）：在创建或编辑卡片的详情面板中，直接填写“Working Directory”。
2. 描述中的特殊章节：在卡片描述中，写入## Project Path并换行后跟上路径。
3. 通过API或Webhook传入：如上文的curl示例。

如果系统检测到卡片没有设置有效的project_path，当你点击“Start”或尝试自动运行时，服务器会返回错误并阻止操作。这强制你养成好习惯，明确每个任务的上下文。

注意事项：路径权限与存在性你填写的project_path必须是服务器进程（即运行pnpm start的用户）有读写权限的目录，并且目录需要真实存在。否则，AI代理进程会在启动时失败。我建议使用绝对路径，避免相对路径可能带来的歧义。

4.3 实时监控与交互：终端查看器

卡片被分配并启动后，会进入“In Progress”列。此时，卡片上会出现一个“终端”图标。点击它，会弹出一个终端查看器窗口。

这个窗口通过Server-Sent Events (SSE) 实时流式传输AI代理在后台执行的所有输出。你会看到：

• AI代理启动的命令行参数。
• AI思考的过程（如果该CLI工具输出的话）。
• AI实际执行的每一条shell命令及其结果。
• 最终的任务完成状态和退出码。

这个功能彻底改变了AI协作的体验。你不再需要猜测AI在做什么，或者它卡在了哪里。你可以实时观察它的工作流，如果发现它跑偏了，可以及时点击卡片上的“Stop”按钮终止任务，调整描述后重新开始。

4.4 自动评审（Review）流程

当一个AI代理完成任务并成功退出（exit code 0）后，卡片会自动移动到“Review/Test”列。此时，系统会自动触发另一个评审流程。

默认情况下，这个评审任务会分配给Claude Code（可在设置中配置）。Claude会接收到一个包含原始任务描述和AI代理工作输出（即终端日志）的提示，要求它对完成的工作进行审查、测试，并提出修改意见。

如果评审通过，卡片会移动到“Done”列，整个流程结束。如果评审发现问题，卡片会停留在“Review/Test”列，并将评审发现的问题更新到卡片描述或评论中，等待你的进一步处理。

个人经验：善用自动评审，但保持最终判断自动评审是一个很好的质量关卡，尤其是对于代码风格、明显的逻辑错误或遗漏的边界情况。但我发现，对于非常复杂的业务逻辑变更，AI评审的深度可能不够。我的做法是，将自动评审视为“第一道自动化测试”，我一定会亲自检查“Review/Test”列中的卡片，特别是Claude输出的评审意见，然后再手动将其拖到“Done”。对于关键任务，我甚至会手动点击“Review”按钮，用不同的AI代理（比如从Claude换成Gemini）进行二次交叉评审。

5. 高级集成与自动化

Claw-Kanban的魅力在于它是一个平台，可以轻松地与你现有的工具链集成，实现自动化。

5.1 与OpenClaw Gateway集成（可选）

如果你同时在使用OpenClaw Gateway（一个AI代理网关），可以通过配置实现状态同步通知。

1. 在.env文件中设置你的OpenClaw配置文件路径：

   OPENCLAW_CONFIG=~/.openclaw/openclaw.json

2. 配置好后，当看板中有新卡片进入“Inbox”，或者卡片从“Review/Test”移动到“Done”时，Claw-Kanban会自动向配置的Gateway发送一个“wake”通知。

这个功能适合更复杂的AI智能体编排场景，让Gateway知道何时有新的任务需要处理，或者何时任务已经完成，可以触发下游动作。

5.2 构建自定义Webhook输入源

内置的Telegram集成需要你自建Bot。更通用的方式是使用/api/inbox这个webhook端点。你可以用任何能发送HTTP POST请求的工具来创建任务。

例如，结合macOS的快捷键工具Keyboard Maestro或Alfred，你可以创建一个快捷键，快速将当前选中的文本作为一个任务发送到看板。

再比如，在VS Code中安装一个“Add to Claw-Kanban”的扩展，一键将当前文件或选中的代码块作为一个Bug报告或改进任务提交。

Webhook的通用格式如下：

curl -X POST http://localhost:8787/api/inbox \ -H 'Content-Type: application/json' \ -d '{ "text": "# 优化数据库查询：用户列表接口", "source": "my_custom_script", "author": "your_name", "project_path": "/current/project/path" # 可选 }'

source和author字段会记录在卡片中，方便你追溯任务来源。

5.3 管理后台任务与清理

Claw-Kanban作为后台服务运行，提供了管理脚本。

# 进入项目目录 cd Claw-Kanban # 检查服务器状态 node scripts/kanban.mjs status # 启动后台服务 node scripts/kanban.mjs start # 停止服务 node scripts/kanban.mjs stop # 重启服务 node scripts/kanban.mjs restart

对于macOS，安装脚本还会帮你创建launchd服务，实现开机自启。Linux下则是systemd用户服务。这意味着你可以让Claw-Kanban在后台持续运行，随时通过浏览器访问。

定期清理已完成的任务也是一个好习惯，可以通过API批量操作：

# 删除所有状态为“Done”的卡片 curl -X POST "http://localhost:8787/api/cards/purge?status=Done"

6. 故障排查与常见问题实录

在实际使用中，你可能会遇到一些问题。下面是我遇到过的典型情况及其解决方法。

6.1 AI代理状态显示“Not Authenticated”

现象：在Settings页面，已安装的CLI代理（如Claude Code）状态显示为红色“Not Authenticated”，导致无法分配任务。

原因与排查：

1. 未登录：你只安装了CLI工具（npm install -g ...），但没有运行claude login等登录命令。
   • 解决：在终端直接运行登录命令，完成浏览器认证流程。
2. 配置文件路径问题：Claw-Kanban在特定路径下查找认证文件（如~/.claude.json）。如果你用sudo安装了全局CLI，或者使用了自定义配置目录，可能找不到。
   • 解决：确保你以同一个用户身份运行Claw-Kanban服务器和进行CLI登录。检查对应的配置文件是否存在且内容正确。
3. 缓存问题：Claw-Kanban会缓存CLI状态30秒。
   • 解决：在Settings页面点击“Re-check CLI Status”按钮，或调用API：curl "http://localhost:8787/api/cli-status?refresh=1"。

6.2 启动任务失败，提示“No project_path set”

现象：点击卡片“Start”按钮，任务没有启动，卡片状态无变化，浏览器控制台或服务器日志显示错误。

原因：这是最重要的安全保护机制。卡片没有设置有效的project_path。

解决：

1. 点击卡片，打开详情面板。
2. 在“Working Directory”输入框中，填入一个绝对路径，指向你希望AI代理工作的项目根目录。
3. 点击“Save Details”。
4. 再次点击“Start”。

6.3 终端查看器无输出或连接中断

现象：点击终端图标，弹窗一直显示“Connecting...”或连接后很快断开，看不到实时日志。

原因与排查：

1. SSE连接问题：终端流依赖于Server-Sent Events，某些浏览器扩展或公司网络代理可能会干扰这种长连接。
   • 解决：尝试禁用广告拦截器或隐私保护扩展，或使用无痕模式。检查浏览器控制台（F12）的Network标签，查看对/api/cards/:id/terminal的请求是否失败。
2. AI代理进程已结束：如果AI任务执行得非常快，可能在打开终端查看器之前就已经结束了。
   • 解决：查看卡片的历史日志（Logs）。对于执行速度很快的任务，实时查看的意义不大，直接看最终输出日志即可。
3. 服务器资源限制：如果AI代理产生了海量输出（比如运行了npm install并打印了所有包信息），可能会占用大量内存。
   • 解决：Claw-Kanban会限制日志在内存中的保留行数。对于输出极多的任务，考虑让AI代理将输出重定向到文件，或在任务描述中要求其精简输出。

6.4 OAuth连接成功但Copilot/Antigravity任务失败

现象：在Settings中成功连接了GitHub或Google账号，但分配任务给Copilot或Antigravity时失败。

原因与排查：

1. 令牌过期或失效：OAuth访问令牌有一定有效期。Claw-Kanban会自动尝试刷新，但如果刷新令牌也失效了，就会失败。
   • 解决：去Settings页面，先点击“Disconnect”，然后重新进行“OAuth Connect”流程。
2. 权限不足：OAuth授权时申请的权限范围（Scope）可能不足以调用某些API。
   • 解决：目前Copilot集成使用的是公开的OAuth App，权限固定。如果遇到权限问题，可能需要检查GitHub Copilot服务本身的状态，或者等待项目更新。
3. 网络问题：无法访问GitHub或Google的API端点。
   • 解决：检查服务器所在机器的网络连接，确保可以访问api.github.com和googleapis.com。

6.5 在Windows上的特殊问题

现象：进程管理异常，无法正常停止任务。

原因：Windows和Unix-like系统（macOS/Linux）的进程树管理方式不同。

解决：Claw-Kanban的v1.0.1版本专门修复了Windows的进程清理逻辑，使用了taskkill /T /F命令来强制结束进程树。如果你在Windows上使用更早的版本，请升级到最新版。如果问题依旧，可以手动在任务管理器中结束相关的node.exe进程。

7. 性能调优与最佳实践

经过一段时间的使用，我总结出一些能让Claw-Kanban运行更顺畅的经验。

1. 为看板服务分配足够资源虽然Claw-Kanban本身不耗资源，但它启动的AI代理进程（尤其是Claude Code、Codex）可能是资源大户。确保你的机器有足够的CPU和内存。如果同时运行多个AI任务，注意观察系统负载。

2. 精细化角色与类型定义不要随意使用“角色”和“类型”。花点时间规划一下：

• 角色对应技术栈（Frontend, Backend, DevOps, Data）。
• 类型对应工作性质（New-新功能, Modify-修改, Bugfix-修复, Refactor-重构）。 这样，你的自动分配规则才能精准有效。例如，我可以设置所有DevOps任务都交给擅长写Shell和配置文件的Claude，所有Data+New任务交给擅长数据分析的Gemini。

3. 利用描述字段提供丰富上下文AI代理的表现严重依赖于你给的上下文。在创建卡片时，在描述字段里尽量写清楚：

• 背景：为什么要做这个改动？
• 具体要求：输入是什么？期望的输出是什么？
• 相关文件：指出关键的文件路径。
• 约束条件：比如“必须保持向后兼容”、“性能要求<100ms”。 你提供的信息越精确，AI“跑偏”的概率就越低，评审环节也更容易通过。

4. 定期归档与清理“Done”列里的卡片会越来越多，虽然SQLite数据库很小，但为了看板整洁和快速加载，建议定期清理。可以写一个简单的cron job，每周自动调用/api/cards/purge接口清理一周前的已完成任务。

5. 日志管理默认的日志存储在./logs目录（可在.env中配置LOGS_DIR）。每个任务的终端输出都会保存为一个文件。定期清理这个目录，或者配置日志轮转，可以防止磁盘空间被占满。

Claw-Kanban本质上是一个思维框架的具象化工具。它强迫你将模糊的“让AI帮个忙”变成结构化的“任务卡片”，并赋予其明确的属性、上下文和验收流程。这个过程本身，就是对如何高效利用AI进行编程的一次深度思考和实践。从我个人的使用体验来看，最大的收获不是节省了多少时间，而是建立了一种可预测、可监控、可复现的AI协作模式。它让AI从一种“神秘的黑箱助手”，变成了一个可以纳入项目管理流程的、可靠的“团队成员”。