启动

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

架构概述

Hermes Web UI 由两个组件组成: 前端:Vite + React (hermes-agent/web/) - 端口 5173 后端:Python Web 服务器 (hermes_cli/web_server.py) - 端口 9119 前端代理 /api/* 到后端的请求。

启动前端开发服务器

访问地址:http://localhost:5173

启动后端仪表板

访问地址:http://localhost:9119

问题 1:TypeScript 构建错误

症状:npm run build失败并出现 TS 错误,例如:修复:跳过 TypeScript 检查并直接启动开发服务器:

问题 2:Python 3.9 兼容性

症状:后端失败,原因:代码使用 Python 3.10+ 类型联合语法 (Path | None) 修复:

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
Node.js · Python >=3.9
检测到的文件与系统行为
  • 只读
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Hermes Web UI Startup & Troubleshooting

## Architecture Overview

Hermes Web UI consists of two components:
1. **Frontend**: Vite + React (`hermes-agent/web/`) - Port 5173
2. **Backend**: Python web server (`hermes_cli/web_server.py`) - Port 9119

Frontend proxies `/api/*` requests to the backend.

## Quick Start

### Start Frontend Dev Server
```bash
cd ~/.hermes/hermes-agent/web
npm run dev
# or directly: npx vite
```

Access at: `http://localhost:5173`

### Start Backend Dashboard
```bash
cd ~/.hermes
hermes dashboard
# or directly: python3 -m hermes_cli.web_server --port 9119
```

Access at: `http://localhost:9119`

## Common Issues & Fixes

### Issue 1: TypeScript Build Errors

**Symptom**: `npm run build` fails with TS errors like:
```
src/components/ModelPickerDialog.tsx(285,22): error TS2552: Cannot find name 'loadProviders'
```

**Fix**: Skip TypeScript check and start dev server directly:
```bash
# TypeScript errors don't prevent dev server from running
npx vite --no-open
```

### Issue 2: Python 3.9 Compatibility

**Symptom**: Backend fails with:
```
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
```

**Cause**: Code uses Python 3.10+ type union syntax (`Path | None`)

**Fix**:
```bash
# Option 1: Upgrade to Python 3.10+
brew install python@3.10

# Option 2: Use frontend only (some features may not work)
# Frontend dev server still works standalone
npx vite
```

### Issue 3: Backend Connection Warnings

**Symptom**: Browser console shows warnings about dashboard unreachable:
```
[hermes] Dashboard at http://127.0.0.1:9119 unreachable
```

**Fix**: Start the backend separately or ignore if you only need UI preview:
```bash
# In separate terminal
cd ~/.hermes && hermes dashboard
```

### Issue 4: Dependencies Not Installed

**Symptom**: `npm run dev` fails immediately

**Fix**:
```bash
cd ~/.hermes/hermes-agent/web
npm install
npm run sync-assets
```

## Verification Steps

1. **Check frontend running**:
   ```bash
   curl -s http://localhost:5173 | head -5
   # Should return HTML doctype
   ```

2. **Check backend running**:
   ```bash
   curl -s http://localhost:9119/health
   # Should return OK or JSON status
   ```

3. **Check processes**:
   ```bash
   ps aux | grep -E "(vite|hermes.*dashboard)" | grep -v grep
   ```

## Development vs Production

### Development
- Frontend: `npm run dev` (port 5173)
- Backend: `hermes dashboard` (port 9119)
- Hot reload enabled
- CORS handled via Vite proxy

### Production
- Build frontend: `npm run build` (outputs to `hermes_cli/web_dist/`)
- Backend serves static files directly
- Single port (9119) for both UI and API

## Troubleshooting Checklist

- [ ] Node.js 20+ installed (`node --version`)
- [ ] Python 3.10+ installed (`python3 --version`)
- [ ] npm dependencies installed (`cd web && npm install`)
- [ ] Assets synced (`npm run sync-assets`)
- [ ] No other process using ports 5173 or 9119
- [ ] Backend running before making API calls
- [ ] Session token properly injected (handled by Vite plugin)

## Background Process Management

When running in background:
```bash
# Start frontend in background
cd ~/.hermes/hermes-agent/web && npx vite --no-open &

# Verify startup (may take 2-3 seconds)
sleep 3 && curl -s http://localhost:5173 > /dev/null && echo "Frontend OK"
```

---
> Source: [54laowang/hermes-agent](https://github.com/54laowang/hermes-agent) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。