1. 项目概述与核心价值如果你和我一样日常开发中同时用着 Claude Code、Codex CLI、Gemini CLI 等多个 AI 编程助手那你一定也经历过这种混乱为了处理一个前端 Bug你需要在终端里手动切换到 Gemini CLI为了调试一个后端 API又得切回 Codex CLI同时你还得在 Telegram 里接收同事发来的任务请求手动复制粘贴到对应的 CLI 里。整个过程不仅效率低下而且你完全不知道 AI 助手正在执行什么操作只能干等着它输出结果。这种“盲盒式”的开发体验让我下定决心要打造一个统一的指挥中心——这就是 Claw-Kanban。Claw-Kanban 本质上是一个AI 智能体编排看板。它不是一个全新的 AI 工具而是一个调度层一个可视化控制台。它的核心价值在于将你分散在各个终端窗口、不同平台上的 AI 编程助手目前支持 Claude Code、Codex CLI、Gemini CLI、OpenCode、GitHub Copilot 和 Google Antigravity 这 6 种统一管理起来。你只需要在看板上创建一个任务卡片Claw-Kanban 就会根据预设的角色如 DevOps、后端、前端和任务类型新增、修改、Bug 修复自动将任务分配给最合适的 AI 助手去执行。整个过程你都可以在浏览器里实时看到 AI 助手的终端输出就像在监控一个真实的工程师工作一样彻底告别了“盲等”。更棒的是它完美继承了你的现有工作环境。对于 Claude Code、Codex CLI 这类 CLI 工具Claw-Kanban 是通过在后台启动你本地已安装的 CLI 进程来工作的。这意味着你在终端里为这些 CLI 配置的所有个性化设置——比如自定义的 MCP 服务器、项目特定的指令文件如CLAUDE.md、各种技能插件——都会被原封不动地继承。你无需在 Claw-Kanban 里重新配置一遍开箱即用。而对于 Copilot 和 Antigravity 这类 HTTP 接口的助手则通过 OAuth 授权直接调用其 API无需本地 CLI。这个工具非常适合独立开发者、小团队技术负责人、或者任何需要高效利用多个 AI 助手进行编码的工程师。无论你是想自动化处理 GitHub Issue还是想通过 Telegram 接收任务并自动派发亦或是单纯想有一个地方集中监控所有 AI 助手的工作状态Claw-Kanban 都能显著提升你的“人机协作”效率。接下来我将带你从零开始深入它的设计、部署、配置和实战技巧。2. 架构设计与核心思路拆解在动手部署之前理解 Claw-Kanban 的“双模执行架构”和“看板状态机”是至关重要的。这能帮助你在后续配置和排错时清楚地知道每个环节在发生什么。2.1 双模执行架构CLI 继承 vs. HTTP 直连Claw-Kanban 对 6 种 AI 助手的支持并非一刀切而是根据其技术特性分成了两种执行模式这是其设计的精妙之处。CLI 代理模式你的环境你的规则这种模式针对 Claude Code、Codex CLI、Gemini CLI 和 OpenCode。当你在看板上点击“开始”一个任务时Claw-Kanban 的服务器一个 Node.js 进程会使用 Node.js 的child_process模块在你的系统上启动一个对应的 CLI 进程。例如分配的任务给 Claude Code它就会执行类似claude “修复登录按钮的样式” --project-path /path/to/project的命令。关键优势环境无损继承。这个子进程会完全继承父进程即 Claw-Kanban 服务器的环境变量、工作目录上下文以及任何通过npm install -g全局安装的 CLI 工具及其配置。你在~/.claude.json里保存的 OAuth 信息、在项目根目录配置的CLAUDE.md指令文件、甚至是你为 Claude Code 安装的第三方 MCP 服务器都会自动生效。这意味着AI 助手在 Claw-Kanban 里运行的效果和你在自己终端里手动运行的效果是完全一致的实现了零配置迁移。HTTP 代理模式零安装仅 OAuth这种模式针对 GitHub Copilot 和 Google Antigravity。它们没有独立的、可被命令行调用的本地 CLI 工具而是提供了 Web API。Claw-Kanban 服务器内置了与这些 API 直接通信的逻辑。当任务分配给这类助手时服务器会直接向对应的 API 端点如 Copilot 的 OpenAI 兼容接口发起 HTTP 请求并流式接收响应再将响应内容实时推送到前端的终端查看器。要使用它们你只需要在 Claw-Kanban 的“设置”面板中点击对应提供商的“OAuth 连接”按钮完成网页授权即可。授权后的访问令牌会由服务器端加密存储前端不接触敏感信息。设计考量这种分离设计是经过深思熟虑的。对于 CLI 工具继承环境是最简单、最可靠的方式。而对于云服务直接调用 API 避免了依赖可能不稳定的第三方 CLI 封装也简化了安装步骤。作为用户你无需关心背后的区别在看板上操作体验是完全一致的。2.2 看板状态机与任务流转逻辑Claw-Kanban 采用了经典的看板工作流包含 6 个状态列构成了一个完整的任务生命周期状态机收件箱所有新任务的起点。可以来自网页手动创建、API 调用或 Webhook如 Telegram 消息。计划中可选用于暂存和规划任务。你可以在这里对任务进行详细描述、分配优先级或设置计划时间。进行中任务已被分配给某个 AI 助手并开始执行。此时该卡片会关联一个后台进程并开启实时日志流。审查/测试AI 助手执行完毕进程退出码为 0后卡片会自动移入此列。系统会自动触发一次审查通常是由 Claude 来检查生成代码的质量、逻辑或风格。已完成审查通过后卡片移入此列。如果配置了 OpenClaw 网关会发送“唤醒”通知。已停止任务被手动停止或 AI 执行过程中出错非零退出码卡片移入此列。这个状态机是自动驱动的。最关键的自动化节点有两个一是从“计划中”或“收件箱”点击“开始”后系统根据规则自动选择 AI 助手并启动执行二是执行完成后自动进入审查阶段。这个设计确保了任务流转的连贯性减少了人工干预。2.3 项目路径安全机制防止“跑错片场”这是一个非常实用且关键的安全设计。AI 助手执行任务必须在一个明确的代码仓库目录下。Claw-Kanban 通过三级回退机制来确保这一点首选卡片专属字段。每个卡片都有一个project_path字段在创建或编辑卡片时直接指定。这是最清晰、最推荐的方式。备选描述中的标记。如果project_path字段为空系统会解析卡片的description字段寻找## Project Path标题下的路径。兜底执行拦截。如果以上两种方式都未提供路径当尝试启动任务调用/runAPI或触发审查调用/reviewAPI时服务器会直接返回错误阻止操作。这个机制从根本上避免了 AI 助手在错误目录比如系统根目录下执行命令可能带来的风险。在实际使用中我强烈建议始终通过 API 或 Webhook 创建卡片时显式传递project_path或者在 UI 中创建卡片后第一时间在详情面板中填写。3. 环境准备与部署实操理解了架构我们就可以动手搭建了。Claw-Kanban 的部署非常灵活从一键脚本到手动安装适应不同场景。3.1 前置条件检查与 AI 助手配置在安装 Claw-Kanban 本身之前你需要确保基础环境和至少一个 AI 助手可用。Node.js 版本是硬性要求由于 Claw-Kanban 使用了 Node.js 22 内置的node:sqlite模块来操作数据库因此Node.js 版本必须 22。你可以通过以下命令检查node -v如果版本低于 22强烈建议使用nvm进行版本管理# 安装并切换到 Node.js 22 nvm install 22 nvm use 22包管理器选择官方推荐使用pnpm它在依赖安装速度和磁盘空间占用上有优势。当然npm也完全兼容。# 如果未安装 pnpm可以用 npm 安装 npm install -g pnpm至少配置一个 AI 助手你需要至少安装并认证一个 CLI 助手。以下是各个助手的安装和登录命令请务必在终端中亲自运行并完成登录流程因为 Claw-Kanban 依赖这些全局安装的、已认证的 CLI。# Claude Code (Anthropic) npm install -g anthropic-ai/claude-code claude login # 这会打开浏览器完成 OAuth 登录 # Codex CLI (OpenAI) npm install -g openai/codex codex auth login # 同样需要浏览器登录 # Gemini CLI (Google) npm install -g google/gemini-cli gemini auth login # OpenCode npm install -g opencode opencode auth实操心得认证文件位置。这些 CLI 工具的认证信息通常保存在用户主目录的隐藏文件中例如~/.claude.json,~/.codex/auth.json,~/.gemini/oauth_creds.json。Claw-Kanban 的/api/cli-status接口就是通过检查这些文件来判断登录状态的。如果你遇到“已安装但未认证”的提示可以去检查一下这些文件是否存在且内容有效。3.2 一键安装与手动部署详解方案一一键安装脚本推荐用于快速体验对于 macOS/Linux 和 Windows项目提供了官方安装脚本。# macOS / Linux curl -fsSL https://raw.githubusercontent.com/GreenSheep01201/Claw-Kanban/main/install.sh | bash # Windows (PowerShell需以管理员身份运行) irm https://raw.githubusercontent.com/GreenSheep01201/Claw-Kanban/main/install.ps1 | iex这个脚本会自动化完成以下所有步骤克隆仓库、安装依赖、构建前端、配置环境变量、设置AGENTS.md文件甚至为你的系统macOS 的 launchd, Linux 的 systemd, Windows 的计划任务注册一个开机自启的服务。安装完成后服务会自动启动你可以直接在浏览器打开http://127.0.0.1:8787访问。方案二手动部署适合深度定制和开发如果你想了解每一步的细节或者需要在特定目录部署手动部署是更好的选择。# 1. 克隆代码库 git clone https://github.com/GreenSheep01201/Claw-Kanban.git cd Claw-Kanban # 2. 安装依赖使用 pnpm 或 npm pnpm install # 或 npm install # 3. 构建前端静态资源 pnpm build # 4. 复制环境变量模板并配置关键步骤 cp .env.example .env # 此时用文本编辑器打开 .env 文件至少配置 OAUTH_ENCRYPTION_SECRET.env文件是配置的核心。以下是一些关键配置项的说明# .env 文件示例 PORT8787 HOST127.0.0.1 # 改为 0.0.0.0 可供局域网访问 DB_PATH./kanban.sqlite LOGS_DIR./logs # !!! 必须设置用于加密 OAuth 令牌 !!! OAUTH_ENCRYPTION_SECRETyour-super-secure-random-string-here # 如果你希望通过 Telegram 等接收任务需要配置 OpenClaw 网关路径 # OPENCLAW_CONFIG~/.openclaw/openclaw.jsonOAUTH_ENCRYPTION_SECRET是一个用于加密存储 GitHub/Google OAuth 令牌的密钥。你可以使用任何随机生成的字符串。请务必设置它否则 OAuth 连接功能将无法使用。方案三开发模式运行如果你打算参与贡献或修改代码可以使用开发模式它支持前端热重载HMR。pnpm dev # 开发模式API在 8787 端口前端在 5173 端口且可被局域网访问 pnpm dev:local # 开发模式仅限本地访问 (127.0.0.1)在开发模式下Vite 开发服务器会代理 API 请求到后端方便调试。3.3 关键配置AGENTS.md 集成这是让 AI 助手能与看板交互的灵魂配置。AGENTS.md是许多 AI 编码助手如 Claude Code会读取的项目级指令文件。Claw-Kanban 提供了一个脚本将一段“编排规则”插入到你的工作空间的AGENTS.md文件头部。# 在 Claw-Kanban 项目根目录运行 pnpm setup这个脚本会自动寻找你当前工作目录或父目录中的AGENTS.md文件并在其开头添加一段注释规则。这段规则告诉 AI 助手当用户输入以#开头的消息时例如# 修复登录 Bug这应该被识别为一个任务请求。助手应该调用 Claw-Kanban 的 API (/api/inbox) 来创建一个看板卡片而不是尝试直接执行它。注意事项pnpm setup执行的是“插入”操作不会覆盖你原有的AGENTS.md内容。如果你的项目没有AGENTS.md它会创建一个。完成此步骤后当你在配置了该AGENTS.md的项目目录下对 AI 助手说“帮我修复登录 Bug”助手会先询问你项目路径然后自动在 Claw-Kanban 看板上创建任务卡片实现了从自然语言到任务卡片的无缝转换。4. 核心功能使用与配置实战系统运行起来后我们进入核心的使用环节。Claw-Kanban 的界面简洁但功能点密集需要逐一攻克。4.1 看板操作与任务管理访问http://127.0.0.1:8787后你会看到一个深色主题的看板界面。主要操作如下创建卡片点击看板顶部的“ New Card”按钮。在弹出的表单中填写标题、描述并最关键的一步设置Project Path。这是 AI 助手的工作目录。分配与启动创建卡片后它位于“Inbox”。你可以点击卡片上的“Start”按钮。此时系统会根据你稍后设置的“自动分配”规则选择一个 AI 提供商或者弹出一个下拉菜单让你手动选择。实时监控卡片进入“In Progress”后点击卡片在右侧详情面板中会有一个“Terminal”选项卡。点击它你可以看到 AI 助手执行命令的实时标准输出和错误输出就像在终端里tail -f日志一样。停止任务如果 AI 助手卡住了或执行方向错误可以点击卡片上的“Stop”按钮这会强制终止对应的后台进程。手动触发审查在“Review/Test”列可以点击“Review”按钮手动触发审查通常由 Claude 执行。4.2 提供商设置与自动分配规则点击界面右上角的齿轮图标进入“Settings”这里是控制中枢。1. AI 提供商状态检测“AI Providers”区域会显示已检测到的 CLI 工具及其认证状态。如果显示“Not Authenticated”你需要回到终端运行对应的login命令。点击“Re-check”按钮可以刷新状态。2. 角色与任务类型映射核心配置这是实现智能调度的关键。在“Role-based Providers”和“FrontEnd Providers”区域你可以进行映射DevOps / Backend 角色你可以为这两个角色分别指定一个默认的 AI 提供商。例如将所有 DevOps 任务如部署脚本、Dockerfile 编写默认交给 Claude Code将所有后端任务如 API 开发、数据库查询默认交给 Codex CLI。前端任务细分对于“Frontend”角色你可以进一步根据任务类型New-新增功能、Modify-修改现有功能、Bugfix-修复缺陷来指定不同的提供商。例如前端新功能开发用 Gemini CLI可能创意更强而 Bug 修复用 Claude Code可能更稳健。3. 阶段覆盖在“Stage-based Providers”区域你可以为“In Progress”和“Review/Test”这两个特定阶段强制指定提供商。例如你可以设置无论任务之前由谁执行进入“Review/Test”阶段后统一由 Claude Code 来进行审查。这是一个更精细的流程控制点。4.3 Webhook 集成从外部接收任务这是实现自动化工作流的神器。Claw-Kanban 提供了一个/api/inbox端点来接收 Webhook。以 Telegram 为例在 Telegram 中创建一个 Bot获取它的token。使用一个简单的服务器例如用express写一个或者使用ngrok等内网穿透工具将 Claw-Kanban 的 API 临时暴露到公网来接收 Telegram Bot 的消息。当收到消息时判断其是否以#开头。如果是则将其转发到 Claw-Kanbancurl -X POST http://127.0.0.1:8787/api/inbox \ -H Content-Type: application/json \ -d { text: # 修复用户登录页面在移动端的样式错位问题, source: telegram, author: 张三, project_path: /Users/yourname/projects/your-web-app }这样你在手机上给 Telegram Bot 发一条消息看板上就会自动出现一个待处理的任务卡片。project_path字段在这里至关重要确保了任务有明确的执行上下文。4.4 OAuth 连接配置用于 Copilot/Antigravity对于 GitHub Copilot 和 Google Antigravity 这两个 HTTP 代理需要在设置面板中进行 OAuth 连接。确保.env文件中设置了OAUTH_ENCRYPTION_SECRET。在 Claw-Kanban 的 Settings 页面找到 “GitHub Copilot” 或 “Google Antigravity” 区域。点击 “Connect via OAuth” 按钮。这会弹出一个新窗口引导你完成 GitHub 或 Google 的官方授权流程。授权成功后窗口会自动关闭Settings 页面会显示连接状态为 “Connected”。安全提示OAuth 令牌由服务器端加密后存储在 SQLite 数据库中。前端浏览器永远不会接触到原始的刷新令牌。这是符合 OAuth 2.0 对于桌面/本地应用的最佳实践。项目内置的 OAuth Client ID 和 Secret 是公开的仅用于标识应用本身你的个人令牌是独立加密存储的。5. 高级技巧、问题排查与维护经过一段时间的深度使用我积累了一些超出官方文档的实战经验和排错方法。5.1 性能优化与稳定性实践日志管理AI 助手执行会产生日志默认存储在./logs目录可通过LOGS_DIR环境变量修改。定期清理旧的日志文件可以释放磁盘空间。你可以写一个简单的 cron 任务或计划任务来定期删除超过 7 天的日志。数据库备份所有的卡片数据、设置都存储在./kanban.sqlite文件路径由DB_PATH定义。定期备份这个文件非常重要。你可以使用sqlite3命令行工具进行备份sqlite3 kanban.sqlite .backup backup.sqlite。进程管理如果发现某个 AI 任务卡死但前端“Stop”按钮无效可以尝试通过系统命令强制结束。首先通过node scripts/kanban.mjs status查看服务器进程 PID或者用ps aux | grep node找到 Claw-Kanban 的主进程及其子进程即 AI CLI 进程然后使用kill -9 PID结束它们。在 Windows 上可以使用taskkill /F /PID PID。5.2 常见问题排查速查表以下是我在实际部署和使用中遇到的一些典型问题及解决方案症状可能原因排查与解决步骤启动服务器失败提示node:sqlite相关错误Node.js 版本低于 22。运行node -v确认版本。使用nvm use 22或升级 Node.js。访问http://127.0.0.1:8787连接被拒绝服务器未运行或端口被占用。1. 在项目目录运行pnpm start。2. 检查端口占用lsof -i :8787(macOS/Linux) 或netstat -ano | findstr :8787(Windows)结束占用进程或修改.env中的PORT。Settings 中所有 AI Provider 都显示 “Not Installed”全局 CLI 未安装或不在系统 PATH 中。1. 运行which claude(或where claudeon Windows) 检查命令是否存在。2. 确认已用npm install -g安装并重启终端。3. 确保 Claw-Kanban 服务器进程的环境变量 PATH 包含全局 npm 目录。有时从图形化启动器启动的服务 PATH 不同建议从终端启动pnpm start测试。Provider 显示 “Installed but Not Authenticated”CLI 工具未登录或认证文件损坏/位置不对。1. 在终端手动运行claude login等命令重新登录。2. 检查对应用户目录下的认证文件如~/.claude.json是否存在且有有效内容。3. 在 Settings 页面点击 “Re-check” 按钮。点击 “Start” 后卡片无反应不进入 “In Progress”任务缺少project_path。1. 检查卡片详情确认Project Path已设置且路径有效。2. 查看浏览器开发者工具F12的 Network 标签看/api/cards/:id/run请求是否返回 400 错误错误信息会提示缺少路径。3. 通过编辑卡片或 API 补全路径。终端查看器无实时输出或输出停滞SSE (Server-Sent Events) 连接问题或进程已退出。1. 刷新页面重新打开终端查看器。2. 检查服务器日志是否有错误。3. 直接查看./logs/目录下对应卡片的日志文件确认进程是否有输出。OAuth 连接 GitHub 失败.env中未设置OAUTH_ENCRYPTION_SECRET或网络问题。1.必须在.env文件中设置OAUTH_ENCRYPTION_SECRET变量。2. 确保服务器可访问 GitHub (api.github.com)。3. 清除浏览器缓存重试连接。5.3 与现有工作流的深度集成思路Claw-Kanban 的 API 设计得非常开放这为自定义集成提供了无限可能。GitHub Actions 集成你可以创建一个 GitHub Action当有新的 Issue 被创建或评论时自动调用 Claw-Kanban 的/api/inboxwebhook将 Issue 内容转为看板任务。甚至可以更进一步当卡片状态变为“Done”时让 Action 自动关闭对应的 Issue。Slack/钉钉/飞书机器人仿照 Telegram 的例子为你团队常用的聊天工具开发一个机器人将#任务格式的消息转发到看板。定时/批量任务写一个简单的脚本读取一个任务列表文件如 CSV 或 JSON然后循环调用POST /api/cardsAPI 批量创建卡片。这对于需要 AI 助手批量处理相似任务如代码重构、生成测试用例的场景非常有用。自定义审查逻辑默认的自动审查是由 Claude 执行的。你可以修改服务器端代码server/index.ts中关于review的逻辑将其替换为调用你自己的代码审查服务或者结合 ESLint、Prettier 等工具进行更严格的检查。5.4 维护与管理命令项目提供了便捷的管理脚本scripts/kanban.mjs。# 检查服务状态 node scripts/kanban.mjs status # 启动服务后台运行 node scripts/kanban.mjs start # 停止服务 node scripts/kanban.mjs stop # 重启服务 node scripts/kanban.mjs restart # 查看帮助 node scripts/kanban.mjs --help对于生产环境建议使用系统级服务管理如 systemd 或 launchd来确保 Claw-Kanban 常驻运行。一键安装脚本已经为你配置好了这些服务。最后一点个人体会Claw-Kanban 最大的价值不在于替代某个 AI 助手而在于串联和可视化。它把原本孤立的、手动的 AI 调用过程变成了一个可管理、可监控、可自动化的流水线。刚开始使用时建议从一两个简单的任务开始熟悉卡片创建、路径设置和自动分配规则。一旦跑通再逐步接入 Webhook设置复杂的角色映射你会发现它就像给你的 AI 助手团队请了一个不知疲倦的项目经理让你能从繁琐的调度工作中解放出来更专注于更高层次的决策和设计。