Umbrel 代理管理器

一项用于高效管理 Umbrel 代理服务（面向 Docker 容器）的技能。可自动发现正在运行的服务，将内部 Docker IP 映射至可用的宿主机端口，并自动更新 OpenClaw 配置。

解决的问题

Umbrel 以内部网络（10.21.0.x）方式运行 Docker 容器，并通过运行在 localhost 端口上的 app-proxy 容器对外暴露这些服务。本技能可：

1. 发现所有 Umbrel 代理服务
2. 映射内部 Docker IP 至可用的宿主机端口
3. 自动更新 OpenClaw 配置
4. 测试 连通性，确保服务正常运行

适用场景

• Docker 容器重启后
• 服务变得不可访问时
• OpenClaw 初始化设置或配置过程中
• 新增 Umbrel 应用时
• 排查服务连通性问题时

快捷命令

# 简单同步（推荐）——仅检查与 OpenClaw 相关的服务
bash scripts/simple_umbrel_sync.sh

# 高级发现（扫描全部服务）
python3 scripts/discover_umbrel_services.py

# 测试连通性
python3 scripts/test_connectivity.py

文件说明

• scripts/discover_umbrel_services.py — 发现 Umbrel 代理服务
• scripts/update_openclaw_config.py — 更新 OpenClaw 配置
• scripts/test_connectivity.py — 测试服务连通性
• scripts/umbrel_proxy_sync.sh — 一次性同步脚本

集成方式

该技能可自动集成至 OpenClaw 的插件系统。运行同步脚本后，请重启网关：

openclaw gateway restart

示例输出

=== Umbrel 代理发现 ===
发现 2 个代理服务：
1. perplexica: 10.21.0.x:3000 → localhost:3444（经由 app proxy）
2. searxng: 10.21.0.x:8080 → localhost:8182（经由 app proxy）

=== OpenClaw 配置更新 ===
已更新 perplexica.baseUrl: http://localhost:3444 ✓
已更新 searxng.baseUrl: http://localhost:8182 ✓

=== 连通性测试 ===
perplexica: ✓ (200 OK)
searxng: ✓ (200 OK)

自动发现逻辑

1. 查找代理容器：docker ps | grep app-proxy
2. 映射内部服务：检查 Docker 网络及端口映射关系
3. 更新配置：对每个服务执行 openclaw config set
4. 验证结果：对各端点发起 HTTP 连通性测试

常见服务映射

验证测试

验证该技能是否正常工作：

cd skills/umbrel-proxy
bash scripts/simple_umbrel_sync.sh

预期输出如下：

• Docker 正在运行 ✓
• 已检查服务数量：4 + matrix
• perplexica: http://localhost:3444 ✓
• searxng: http://localhost:8182 ✓
• synapse: http://localhost:8008 ✓
• OpenClaw 配置已按需完成更新

故障排查

若未发现服务，请检查：

1. 确认 Docker 正在运行：docker ps
2. 确认 Umbrel app-proxy 容器存在：docker ps | grep app-proxy
3. 检查网络连通性：ping 10.21.0.1（Umbrel Docker 网关地址）

若配置更新失败，请检查：

1. 确保 OpenClaw 未运行：openclaw gateway stop
2. 检查权限：ls -la ~/.openclaw/openclaw.json（或您的 OpenClaw 配置路径）
3. 启用详细日志模式：python3 scripts/update_openclaw_config.py --verbose

示例测试结果

✅ 技能验证通过：

• 所有脚本均可执行且功能正常
• 成功发现多个 Umbrel 服务并完成映射
• 已为相关插件正确更新 OpenClaw 配置
• 已确认所发现服务的连通性