各平台适配状态（当前支持标准）

平台	当前支持方式	适用条件
Claude	原生MCP联动	注册 `mcpServers`
Codex	MCP脚本联动	执行 `scripts/mcp-setup.sh --codex` 或同等配置
Gemini	MCP注册	配置 `mcpServers` /桥接
OpenCode	MCP/桥接联动	配置 `omx` / `ohmg` 类工具或同等结构

仅使用当前技能是否可行：

Claude/Gemini：可行
Codex：可行（需基于脚本配置）
OpenCode：可行（需通过编排中转）

Vibe Kanban — AI Agent Kanban看板

在单个Kanban看板中统一管理多个AI Agent（Claude/Codex/Gemini）。将卡片（任务）移至In Progress状态时，会自动启动git worktree创建+Agent执行流程。

何时使用此技能

将史诗需求拆解为多个独立任务并并行分配给Agent时
需要可视化追踪AI任务的执行状态时
希望在UI中通过diff/日志审核Agent结果并重新执行时
要将基于GitHub PR的团队协作与AI Agent工作流结合时

前置条件

bash

# 需要Node.js 18+版本
node --version

# 需提前完成Agent认证
claude --version    # 需配置ANTHROPIC_API_KEY
codex --version     # 需配置OPENAI_API_KEY（可选）
gemini --version    # 需配置GOOGLE_API_KEY（可选）
opencode --version  # 无需额外配置（基于GUI认证）

已验证版本（截至2026-02-22）

vibe-kanban: v0.1.17

claude (Claude Code): 2.1.50

codex: 0.104.0

gemini: 0.29.5

opencode: 1.2.10

安装 & 运行

npx方式（最快）

bash

# 直接运行（无需安装）
npx vibe-kanban

# 指定端口（默认端口3000）
npx vibe-kanban --port 3001

# 同时指定端口和环境变量
PORT=3001 npx vibe-kanban --port 3001

# 使用包装脚本
bash scripts/vibe-kanban-start.sh

浏览器会自动打开

http://localhost:3000

。

⚠️ 注意端口冲突：若Next.js等其他开发服务器占用3000端口，请执行
PORT=3001 npx vibe-kanban --port 3001
启动。启动日志中出现
Main server on :3001
后，访问
http://localhost:3001
。

正常启动日志：

Starting vibe-kanban v0.1.17...
No user profiles.json found, using defaults only
Starting PR monitoring service with interval 60s
Remote client initialized with URL: https://api.vibekanban.com
Main server on :3001, Preview proxy on :XXXXX
Opening browser...

克隆仓库 + 开发模式

bash

git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban
pnpm i
pnpm run dev

环境变量

变量	说明	默认值
`PORT`	服务器端口	`3000`
`HOST`	服务器主机	`127.0.0.1`
`VIBE_KANBAN_REMOTE`	允许远程连接	`false`
`VK_ALLOWED_ORIGINS`	CORS允许来源	未设置
`DISABLE_WORKTREE_CLEANUP`	禁用worktree清理	未设置
`ANTHROPIC_API_KEY`	用于Claude Code Agent	—
`OPENAI_API_KEY`	用于Codex/GPT Agent	—
`GOOGLE_API_KEY`	用于Gemini Agent	—

在

.env

文件中配置后启动服务器。

各Agent的API密钥配置位置（Settings → Agents → Environment variables）
Claude Code:
ANTHROPIC_API_KEY
Codex:
OPENAI_API_KEY
Gemini:
GOOGLE_API_KEY
Opencode: 无需额外配置（内置认证）

MCP配置

Vibe Kanban可作为MCP（Model Context Protocol）服务器运行，允许Agent直接控制看板。

Claude Code MCP配置

在

~/.claude/settings.json

或项目的

.mcp.json

中配置：

json

{
  "mcpServers": {
    "vibe-kanban": {
      "command": "npx",
      "args": ["vibe-kanban", "--mcp"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "3001"
      }
    }
  }
}

OpenCode MCP配置

在

~/.config/opencode/opencode.json

中添加：

json

{
  "mcp": {
    "vibe-kanban": {
      "command": "npx",
      "args": ["vibe-kanban", "--mcp"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "3001"
      }
    }
  }
}

重启后，

vk_*

工具可直接在OpenCode会话中使用。

MCP工具列表

工具	说明
`vk_list_cards`	查看所有卡片（工作区）
`vk_create_card`	创建新卡片
`vk_move_card`	更改卡片状态
`vk_get_diff`	查看卡片diff
`vk_retry_card`	重新执行卡片任务

⚠️ 注意工具名称变更：
vk_list_tasks
→
vk_list_cards
，
vk_create_task
→
vk_create_card
以上为v0.1.17版本中实际MCP API的工具名称。

Codex MCP适配

若要在Codex中联动Vibe Kanban，在项目根目录执行：

bash

bash scripts/mcp-setup.sh --codex

此命令会在

~/.codex/config.toml

中添加

vibe-kanban

MCP服务器配置。基于钩子的自动重试并非Codex默认功能，需通过看板卡片状态或上层编排来管理重试/重复执行。

工作区 → 并行Agent → PR工作流

v0.1.17版本实际UI结构：Vibe Kanban虽为Kanban看板形式，但实际工作单元为Workspace（工作区）。每个工作区独立处理一个任务。

1. 启动服务器

bash

# 默认运行
npx vibe-kanban
# → http://localhost:3000

# 端口冲突时（如Next.js占用3000）
PORT=3001 npx vibe-kanban --port 3001
# → http://localhost:3001

2. （可选）使用planno审核史诗需求规划

text

请用planno审核此功能的实现规划

planno（plannotator）是独立技能 — 无需Vibe Kanban即可使用。

3. 创建工作区（Create Workspace）

访问UI → 点击**"+ Create Workspace"**或左侧侧边栏
```
+
```
按钮
**Which repositories?**界面：
- Browse → 从文件系统中选择git仓库（可手动输入路径）
- Recent → 选择之前使用过的仓库
- 选择仓库后选择分支（默认：
```
main
```
  ）
- 点击Continue
**What would you like to work on?**界面：
- 选择Agent（Opencode、Claude Code、Codex、Gemini、Amp、Qwen Code、Copilot、Droid、Cursor Agent）
- 输入任务描述（支持Markdown）
- 选择模式（Default、Build等）
- 点击Create

4. Agent自动执行

创建工作区时：

自动创建

vk/<hash>-<slug>

分支（例如：

vk/3816-add-a-comment-to

）

自动创建git worktree（实现Agent间完全隔离）
执行所选Agent CLI并流式输出日志

工作区状态：

Running：Agent执行中（左侧侧边栏显示）
Idle：等待中
Needs Attention：Agent执行完成或需要输入

5. 查看结果

Changes面板：查看文件diff
Logs面板：查看Agent执行日志
Preview面板：预览Web应用
Terminal：直接执行命令
Notes：添加备注

6. 创建PR & 完成任务

进入工作区详情 → 点击**"Open pull request"**按钮
PR合并后 → 工作区移至Archive
自动清理worktree

Git Worktree隔离结构

工作区目录（可在Settings → General → Workspace Directory中修改）：

~/.vibe-kanban-workspaces/          ← 默认位置（主目录下）
├── <workspace-uuid-1>/             ← 工作区1隔离环境
├── <workspace-uuid-2>/             ← 工作区2隔离环境
└── <workspace-uuid-3>/             ← 工作区3隔离环境

分支命名规则（可在Settings → General → Git → Branch Prefix中修改）：

vk/<4位ID>-<task-slug>
示例：vk/3816-add-a-comment-to-readme

内部执行逻辑：

bash

git worktree add <workspace-dir> -b vk/<hash>-<task-slug> main
<agent-cli> -p "<task-description>" --cwd <workspace-dir>

推荐添加到.gitignore的条目：
.vibe-kanban-workspaces/
.vibe-kanban/

远程部署

Docker

bash

# 官方镜像
docker run -p 3000:3000 vibekanban/vibe-kanban

# 传递环境变量
docker run -p 3000:3000 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e VK_ALLOWED_ORIGINS=https://vk.example.com \
  vibekanban/vibe-kanban

反向代理（Nginx/Caddy）

bash

# 必须配置CORS允许
VK_ALLOWED_ORIGINS=https://vk.example.com

# 或多个允许来源
VK_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com

SSH远程打开

与VSCode Remote-SSH集成：

vscode://vscode-remote/ssh-remote+user@host/path/to/.vk/trees/<task-slug>

故障排除

Worktree冲突 / 孤立worktree

bash

# 清理孤立worktree
git worktree prune

# 查看当前worktree列表
git worktree list

# 强制删除特定worktree
git worktree remove .vk/trees/<slug> --force

403 Forbidden（CORS错误）

bash

# 远程访问时需配置CORS
VK_ALLOWED_ORIGINS=https://your-domain.com npx vibe-kanban

Agent无法启动

bash

# 直接测试CLI
claude --version
codex --version

# 检查API密钥
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

端口冲突

bash

# 使用其他端口
npx vibe-kanban --port 3001

# 或通过环境变量
PORT=3001 npx vibe-kanban

SQLite锁错误

bash

# 禁用worktree清理后重启
DISABLE_WORKTREE_CLEANUP=1 npx vibe-kanban

UI vs CLI选择标准

场景	模式
团队共享看板、可视化进度追踪	UI（ `npx vibe-kanban` ）
CI/CD流水线、脚本自动化	CLI（ `scripts/pipeline.sh` ）
快速本地实验	CLI（ `scripts/conductor.sh` ）
浏览器中查看diff/日志	UI

支持的Agent列表（v0.1.17已验证）

在Settings → Agents中可配置各Agent的详细设置：

Agent	命令	API密钥
Opencode	`opencode`	内置（默认）
Claude Code	`claude`	`ANTHROPIC_API_KEY`
Codex	`codex`	`OPENAI_API_KEY`
Gemini	`gemini`	`GOOGLE_API_KEY`
Amp	`amp`	单独配置
Qwen Code	`qwen-coder`	单独配置
Copilot	`copilot`	GitHub账号
Droid	`droid`	单独配置
Cursor Agent	`cursor`	Cursor订阅

各Agent可配置的项：

Append prompt：Agent执行时添加的额外指令
Model：使用的模型名称（例如：
```
claude-opus-4-6
```
）
Variant：模型变体
Auto Approve：自动批准Agent操作（默认：开启）
Auto Compact：自动压缩上下文（默认：开启）
Environment variables：API密钥等环境变量

典型使用场景

1. 史诗需求并行拆解处理

"支付流程v2"史诗需求
  ├── 工作区1：前端UI  → Claude Code
  ├── 工作区2：后端API     → Codex
  └── 工作区3：集成测试    → Opencode
→ 3个工作区同时Running → 并行实现

2. 按角色分配专业Agent

Claude Code  → 侧重设计/领域相关功能
Codex        → 侧重类型/测试/重构
Gemini       → 侧重文档/Storybook编写
Opencode     → 通用任务（默认）

3. 基于GitHub PR的团队协作

设置VIBE_KANBAN_REMOTE=true
→ 团队成员可在看板中查看状态
→ 仅在GitHub PR中进行审核/批准
→ 结合Agent并行执行与传统PR流程

4. 实现方案对比

同一任务，创建两个工作区：
  工作区A → Claude Code（侧重UI结构）
  工作区B → Codex（侧重性能优化）
→ 对比PR后选择最优方案

5. OpenCode + ulw并行委托

结合OpenCode的ulw(ultrawork)模式，按史诗需求级别并行执行Agent：

python

# ulw关键字 → 启用ultrawork并行执行层
# Vibe Kanban看板：在单独终端执行npx vibe-kanban

task(category="visual-engineering", run_in_background=True,
     load_skills=["frontend-ui-ux", "vibe-kanban"],
     description="[Kanban WS1] 前端UI",
     prompt="实现支付流程UI — src/components/payment/ 下的卡片输入、订单确认、完成页面")

task(category="unspecified-high", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[Kanban WS2] 后端API",
     prompt="实现支付流程API — POST /charge, POST /refund, GET /status/:id")

task(category="unspecified-low", run_in_background=True,
     load_skills=["vibe-kanban"],
     description="[Kanban WS3] 集成测试",
     prompt="编写支付E2E测试 — 成功/失败/退款场景")

# → 3个工作区将以Running状态同时显示在Kanban看板中
# → 完成时：Needs Attention → 创建PR → Archive

小贴士

保持卡片范围狭窄（1卡片 = 1提交单元）
若需修改2个以上文件，先使用planno审核规划
```
VIBE_KANBAN_REMOTE=true
```
仅在可信网络中使用
若Agent停滞，可重新分配或拆分卡片

架构概述

┌─────────────────────────────────────────────────────────┐
│                    Vibe Kanban UI                       │
│   ┌──────────┬──────────┬──────────┬──────────┐        │
│   │  To Do   │In Progress│  Review  │   Done   │        │
│   └──────────┴──────────┴──────────┴──────────┘        │
└───────────────────────────┬─────────────────────────────┘
                            │ REST API
┌───────────────────────────▼─────────────────────────────┐
│                    Rust Backend                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │
│  │ server  │  │executors │  │   git   │  │ services │  │
│  └─────────┘  └──────────┘  └─────────┘  └──────────┘  │
│                   │                                     │
│             ┌─────▼─────┐                               │
│             │  SQLite   │                               │
│             └───────────┘                               │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
   ┌────▼────┐        ┌─────▼─────┐       ┌────▼────┐
   │ Claude  │        │   Codex   │       │ Gemini  │
   │worktree1│        │ worktree2 │       │worktree3│
   └─────────┘        └───────────┘       └─────────┘

参考资源

技能文件结构

.agent-skills/vibe-kanban/
├── SKILL.md              # 主技能文档
├── SKILL.toon            # TOON格式（压缩）
├── scripts/
│   ├── start.sh          # 服务器启动包装脚本
│   ├── cleanup.sh        # Worktree清理脚本
│   ├── mcp-setup.sh      # MCP配置自动化脚本
│   └── health-check.sh   # 服务器状态检查脚本
├── references/
│   ├── environment-variables.md  # 环境变量参考
│   └── mcp-api.md                # MCP API参考
└── templates/
    ├── claude-mcp-config.json    # Claude Code MCP配置模板
    ├── docker-compose.yml        # Docker部署模板
    └── .env.example              # 环境变量示例

脚本使用方法

bash

# 启动服务器
bash scripts/start.sh --port 3001

# 清理Worktree
bash scripts/cleanup.sh --dry-run  # 预览清理内容
bash scripts/cleanup.sh --all       # 删除所有VK worktree

# 配置MCP
bash scripts/mcp-setup.sh --claude  # 配置Claude Code
bash scripts/mcp-setup.sh --all     # 配置所有Agent

# 检查状态
bash scripts/health-check.sh
bash scripts/health-check.sh --json  # 以JSON格式输出

快速参考

=== 服务器运行 ===
npx vibe-kanban                       直接运行（端口3000）
PORT=3001 npx vibe-kanban --port 3001 端口冲突时使用（如Next.js占用3000）
http://localhost:3000                  看板UI地址

=== 环境变量 ===
PORT=3001                        修改端口
VK_ALLOWED_ORIGINS=https://...   配置CORS允许来源
ANTHROPIC_API_KEY=...            Claude Code认证密钥
OPENAI_API_KEY=...               Codex认证密钥
GOOGLE_API_KEY=...               Gemini认证密钥

=== MCP联动 ===
npx vibe-kanban --mcp            启动MCP模式
vk_list_cards                    查看卡片（工作区）
vk_create_card                   创建卡片
vk_move_card                     更改卡片状态

=== 工作区流程 ===
Create → Running → Needs Attention → Archive
Running: 创建worktree + 启动Agent
Needs Attention: 执行完成或需要输入
Archive: PR合并完成

=== MCP配置文件位置 ===
Opencode: ~/.config/opencode/opencode.json
Claude Code: ~/.claude/settings.json 或 .mcp.json

=== worktree清理 ===
git worktree prune               清理孤立worktree
git worktree list                查看worktree列表
git worktree remove <path>       强制删除worktree

vibe-kanban

NPX安装

标签

SKILL.md 内容（中文）

各平台适配状态（当前支持标准）

Vibe Kanban — AI Agent Kanban看板

何时使用此技能

前置条件

安装 & 运行

npx方式（最快）

克隆仓库 + 开发模式

环境变量

MCP配置

Claude Code MCP配置

OpenCode MCP配置

MCP工具列表

Codex MCP适配

工作区 → 并行Agent → PR工作流

1. 启动服务器

2. （可选）使用planno审核史诗需求规划

3. 创建工作区（Create Workspace）

4. Agent自动执行

5. 查看结果

6. 创建PR & 完成任务

Git Worktree隔离结构

远程部署

Docker

反向代理（Nginx/Caddy）

SSH远程打开

故障排除

Worktree冲突 / 孤立worktree

403 Forbidden（CORS错误）

Agent无法启动

端口冲突

SQLite锁错误

UI vs CLI选择标准

支持的Agent列表（v0.1.17已验证）

典型使用场景

1. 史诗需求并行拆解处理

2. 按角色分配专业Agent

3. 基于GitHub PR的团队协作

4. 实现方案对比

5. OpenCode + ulw并行委托

小贴士

架构概述

参考资源

技能文件结构

脚本使用方法

快速参考