helixml/helix · 上手攻略

  • 仓库：helixml/helix
  • 链接：https://github.com/helixml/helix
  • 分类：AI 基础设施 · 多 Agent 编队 / Spec 驱动开发
  • 作者：Tom
  • 更新：2026-09-25

这是什么

Helix 是一个私有 AI 编程 Agent 编队平台，让团队在自有的 GPU 基础设施上运行多个并行的 AI 编程 Agent——每个 Agent 有自己独立的 GPU 加速 Linux 桌面（内置 IDE、终端、浏览器、文件系统），通过 Spec 驱动的 Kanban 看板组织任务，从需求描述到 PR 合并形成完整流程。

核心定位：不再让所有 Agent 挤在一个终端窗口里，而是给每个 Agent 分配一台"虚拟机"，团队像管理真人员工一样派活、盯进度、review 代码。

解决什么问题

  • 一个 Claude Code 实例一次只能干一件事，想同时跑 N 个任务就要开 N 个终端窗口，无法协作
  • Agent 在本地跑，代码和上下文都在个人电脑上，团队无法共享、无法 review、无法审计
  • 需要在"便宜模型做简单任务、贵模型做复杂任务"之间灵活切换，但 Agent 状态无法跨模型迁移
  • 希望 Agent 真正做到"先写设计文档，人确认后再写代码"，而不是上来就开始写代码

快速安装

方式一：官方一键安装脚本（推荐，Linux）

curl -sL -O https://get.helixml.tech/install.sh
chmod +x install.sh
sudo ./install.sh

安装脚本会提示你即将做的系统变更，默认 dashboard 入口为 http://localhost:8080。

⚠️ 版本号：当前 Release 为 v2.12.22（2026 年 9 月），./install.sh --help 可查看完整选项。

方式二：Helm Chart 生产部署

# 添加 Helm 仓库
helm repo add helix https://charts.helixml.tech
helm repo update

# 安装控制平面
helm install helix-control-plane helix/helix-control-plane \
  --set server.url=https://your-domain.com \
  --set postgres.connection="postgresql://user:pass@host:5432/helix"

# 安装 GPU Runner（每台 GPU 机器）
helm install helix-runner helix/helix-runner \
  --set runner.gpu.enabled=true

方式三：Docker Compose 开发环境

git clone https://github.com/helixml/helix.git
cd helix
docker compose -f docker-compose.dev.yaml up

⚠️ 前置依赖：Go 1.24.0+、Node.js 18+、Docker Desktop（或 Docker + Docker Compose）、Make。

核心用法

1. Kanban 看板工作流

Helix 为每个项目分配一个六阶段看板：

Backlog → Planning → Spec Review → In Progress → Pull Request → Merged

Backlog：用一段话描述你想要的结果（what should be true when done，不写实现细节）

Planning：点击"Start Planning"，规划 Agent 自动读取仓库并写出规格文档（需求 + 设计 + 任务分解），提交到 helix-specs 分支

Spec Review：你阅读规格文档，选中文字提出修改意见（或直接 Approve），Agent 重新规划

In Progress：实现 Agent 在独立沙箱里写代码，团队可实时观看、可随时插入 steering

Pull Request：完成后自动在仓库开 PR，PR 是真正的审查门槛

Merged：PR 合并后任务关闭

2. 多 Agent 并行 + 任务切换

多个 Agent 同时在各自的沙箱里跑任务，互不干扰。可以随时切换到任何一个 Agent 的会话，下一个 Agent 会从上一个 Agent 离开的地方继续（上下文跨 Agent 迁移）。

3. 模型灵活切换（不换 Agent 换 Harness）

Helix 支持以下 Agent Harness，每个任务可以单独选：

  • Claude Code
  • OpenAI Codex
  • Gemini CLI
  • Qwen Code
  • Goose
  • Zed Agent
  • 任何支持 ACP（Agent Client Protocol）的 Agent

同一任务中途可以切换 Harness，上下文保持不变，可以用便宜模型做规划、贵模型做实现。

4. LLM Provider 配置

Helix 支持自托管和商业 Provider：

# 支持的 Provider 类型（通过环境变量配置）
OPENAI_API_KEY=          # OpenAI 系列
ANTHROPIC_API_KEY=       # Anthropic 系列（含 Vertex AI / AWS Bedrock）
POSTGRES_*=              # 数据库连接
SERVER_URL=              # 公开访问 URL（生产部署需要）
RUNNER_*=                # GPU Runner 配置

自托管模型：通过 vLLM 或任何 OpenAI 兼容端点接入，Helix 自动识别并路由。

5. RAG 与知识库

Helix 内置完整的 RAG 能力：

  • 文档摄取：PDF、Word、纯文本
  • 网页抓取（Web Scraper）
  • 多种 RAG 后端：Kodit、LlamaIndex
  • PGVector 向量嵌入
  • Vision RAG（图片理解）

6. 团队协作功能

  • 多租户 + RBAC：组织、团队、角色权限，OIDC 单点登录
  • 工时计费：按 Token 和消费额跟踪团队使用成本
  • 通知：Slack、Discord、Email
  • 自动化：定时任务、Webhook 触发

典型适用场景

  1. 团队级 AI 编程：多个工程师同时派活给 AI Agent，团队在 Kanban 上统一管理、review、合并
  2. 成本分级策略：简单重构用 Qwen Code，复杂架构设计用 Claude Opus，中间切换 Harness 上下文不丢
  3. 私有部署合规：代码不上云，纯内网 GPU 集群运行，满足数据安全要求
  4. Spec-First 质量门控：强制 Agent 先写设计文档再写代码，减少返工和无效代码
  5. Air-gapped 离线部署：纯内网环境运行，不依赖任何外部 API

坑与注意

⚠️ 1. 硬件要求高 每个 Agent 独享一个 GPU 加速桌面沙箱，官方 Demo 视频里每个容器都有 GPU 资源。纯 CPU 环境下体验会大打折扣，具体 GPU 规格建议参考官方文档 runners docs。

⚠️ 2. 本地开发环境复杂 docker-compose.dev.yaml 开发模式需要 Docker Desktop + Go + Node.js + Make，门槛比直接用 ./install.sh 高，不建议纯新手尝试。

⚠️ 3. Spec Review 环节需要人工介入 如果 Approve 太快，Agent 可能基于不完整 spec 开始实现。建议至少完整阅读 spec 的"验收标准"段落再 Approve。

⚠️ 4. Self-hosted vLLM 需要额外配置 Helix 的 vLLM 接入需要 vLLM Server 先启动并暴露 OpenAI 兼容端点，Helix 端点 URL 要指向 http://<vllm-host>:8000/v1，配置参考 ./install.sh --help。

⚠️ 5. WIP 限制（看板列同时进行的任务数） 看板各列有 WIP（Work In Progress）限制，防止某一列堆积太多任务。首次使用建议保持默认限制，避免超载。

⚠️ 6. 当前版本 2.12.22（2026-09） Helix 仍处于快速迭代期，API 和配置项可能在 Minor 版本间变化，生产部署前建议锁定具体版本 tag，不要用 latest 追踪。

⚠️ 7. ACP 兼容 Agent 需要额外验证 虽然文档说支持"任何 ACP 兼容 Agent"，实际接入前建议先用官方 Demo 验证工作流，再测试自定义 Agent。

与同类对比

工具 定位 Agent 隔离 Spec 驱动 自托管 多租户
Helix 企业私有 Agent 编队平台 ✅ GPU 加速沙箱桌面 ✅ 六阶段看板 ✅ 完整内网 ✅ RBAC + OIDC
Devin 单人 AI 软件工程师（SaaS） ✅ 云端沙箱 ❌ ❌ ❌
Cursor 个人 AI 编程 IDE ❌ ❌ ❌ ❌
GitHub Copilot IDE 插件级辅助 ❌ ❌ ❌ ❌
Goose 本地单 Agent 工具 ❌ ❌ ✅ ❌
Qwen Code / Claude Code 本地单 Agent ❌ ❌ ✅ ❌

核心差异：Helix 是目前唯一一个将"多 Agent 并行 + 独立 GPU 沙箱 + Spec-First 开发流程 + 团队 Kanban 管理"整合在一起的平台，本质上是在做一个"AI 编程团队的操作系统"，而非单纯的 Agent 工具。

一句话推荐结论

如果你是工程团队负责人，想让多个 AI 编程 Agent 同时为团队工作、而不是每人各自开一个终端窗口，Helix 是目前最完整的私有部署方案——Spec 驱动的 Kanban 让 AI 写代码前必须先过人类审批，GPU 沙箱保证每个 Agent 隔离运行、互不抢资源，v2.12.22 的多租户和计费系统让团队使用一目了然。