更新于 2026-06-19

安装与本地环境

本页说明 AgentHub Desktop、Local Edge、Hub Server、Web 和 runtime adapter 的本地开发环境。第一次运行 AgentHub 前，先读本页，再进入快速上手。

NOTE

范围这里描述开发工作站，不写私有部署主机、SSH alias、provider key 或生产回滚路径。

支持的环境

AgentHub 是多产品面的系统。完整本地工作站通常需要：

区域	要求	作用
源码	Git	克隆 AgentHub 仓库并检查分支
Desktop/Web/Mobile	Node.js 20+ 和 pnpm	安装三个客户端的前端依赖并运行本地预览
Edge/Hub	Go 1.25+	运行本地 Edge 和 Hub 服务
Runtime	先 mock，再 Claude Code、Codex 或 OpenCode	先验证 UI，再接真实凭据
浏览器	Chromium、Edge 或 Chrome	测试 Desktop/Web preview 和文档页

第一次设置建议使用 mock runtime。真实 runtime 会引入 CLI 登录、provider quota、shell、workspace policy 等额外失败面，应在 mock 链路健康后再接入。

克隆源码仓库并运行仓库设置脚本：

git clone https://github.com/TokenDanceLab/AgentHub.git
cd AgentHub
.\scripts\setup.ps1

如果 setup 脚本发生变化，以 AgentHub 仓库 README 为准。公开官网描述预期结构，不复制每一条可能快速变化的本地命令。

设置后检查仓库结构：

路径	作用
`app/desktop`	Tauri 2 Desktop UI，连接 Local Edge
`app/web`	Hub 驱动的 Web 工作台（端口 5174），与 Desktop 共享工作台 UI
`app/mobile`	Expo React Native 移动客户端（端口 5177）
`app/shared`	Desktop 和 Web 共享的工作台 UI 组件
`edge-server`	本地执行、adapter registry、事件日志、diff、产出、approval
`hub-server`	OIDC PKCE session、project、message、agent 协作、routing、audit
`api`	公开契约词汇、OpenAPI 和事件参考

Runtime adapter 包装已有编码 Agent 工具。只准备你要测试的 runtime：

Runtime	准备方式
Mock	不需要 provider credential，适合第一次验证
Claude Code	在用户 shell 里安装并完成本地鉴权
Codex	在用户 shell 里安装并完成本地鉴权
OpenCode	在用户 shell 里安装并完成本地鉴权
Custom	提供本地 adapter 实现和安全 profile

真实 key 放在本地 shell 环境或 server-side secret store。

推荐本地端口形状：

进程	默认形状	说明
Local Edge	`127.0.0.1:3210`	本地执行建议只绑定 loopback
Desktop dev server	Vite 分配，默认 `localhost:5173`	Tauri 2 原生客户端；dev 使用 5173
Web dev server	Vite 分配，默认 `localhost:5174`	Web 与 Desktop 共享工作台 UI；调用 Hub，不直接调 Edge
Mobile Expo	Expo 分配，默认 `localhost:5177`	Expo React Native；仅连接 Hub
Hub Server	仓库定义的本地端口	仅在测试 session、project、agent 协作、audit、routing 时需要

如果端口被占用，选择另一个本地端口并同步客户端配置。

运行真实任务前，先确认基础工具：

git --version
go version
node --version
pnpm --version

然后启动 mock Local Edge 并检查 health：

cd edge-server
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile agenthub-runner-mock
curl.exe http://127.0.0.1:3210/health

Edge 收敛过程中，具体 health endpoint 可能变化。稳定要求是：Local Edge 以安全可检查的方式暴露进程状态、runtime profile 状态和 workspace policy 状态。

现象	先检查
`pnpm install` 失败	Node.js 主版本和 `package.json` 里的 package manager
Edge 启动失败	Go 版本、runtime profile、端口占用
Desktop 连接不上	Desktop 是否指向同一个 loopback Edge URL
Mock 正常但真实 runtime 失败	Runtime CLI 安装和本地登录
浏览器看到旧文档	使用 cache-busting URL，并检查线上 `sitemap.xml` / `llms.txt`

工作站能启动 Local Edge 和 Desktop 后，继续快速上手。