agent-easy-http

agent-easy-http

• Version: 1.0.2
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/html-tool-suite (skill dir: skills/agent-easy-http)

把 OpenClaw 的 agent 能力通过 HTTP(S) + 网络 IP 暴露给其它系统调用。

⚠️ 安全须知（部署前必读）

本 skill 会启动一个常驻代理，把你的 OpenClaw agent 暴露成可远程调用的 HTTP 接口。agent 具备文件、shell、消息发送等本机能力，因此这是一个对外开放的远程控制面，请理解以下风险边界：

• /agent/run 是通用入口：任何通过鉴权的调用方都能向 agent 发送任意 prompt，由 agent 自行决定调用哪些 Skill——包括发消息、改数据等有副作用的操作。请确保端口只对可信调用方开放。
• 默认 HTTP 不加密：默认模式下 X-API-Key、prompt、执行结果均明文传输。仅 localhost / 可信内网可接受；监听 0.0.0.0 或跨主机调用务必启用 HTTPS，切勿在生产用 curl -k 跳过证书校验。
• 会修改全局配置：init / watchdog 会写入并自愈 ~/.openclaw/openclaw.json 的 hooks 配置（可选还会同步到 OPENCLAW_CONFIG_SYNC_PATHS 外部配置源）。这是平台级改动，管理员手动回退后 watchdog 可能重新应用，请知悉其持久化行为。
• 保护好 API Key：Key 是 bearer 凭证，泄露即等同交出 agent 调用权。注意别进入 shell history、日志、截图或权限过宽的文件。

一句话：把它当作暴露内部 agent 服务来对待，务必配好鉴权、绑定与 TLS，而非零风险的便捷封装。

📐 下文的 "v3.0 架构" 指本 skill 内部的架构代号（v3.0 = 基于 OpenClaw 原生 /hooks/agent 的轻代理实现，取代早期 v2.0 的 openclaw agent CLI 冷启动方案），与开源发布版本号 1.0.0 是两个维度。

典型场景：在 OpenClaw 容器/Pod 上部署，团队内其它服务通过 http://:7720 调用你的 OpenClaw agent 跑任务。

默认 HTTP 模式（零门槛）：v3.0 起 TLS 默认关闭，先跑通再升级。需要 HTTPS 时跑 python3 scripts/gen_cert.py --san auto + 改 config 即可切回。

---

v3.0 重大重构

仍然保留的核心层

• ✅ HTTP（默认）/ HTTPS（按需开启）+ SAN 证书
• ✅ API Key 强制鉴权（X-API-Key）
• ✅ deny_skills 黑名单（外层防火墙）
• ✅ Prompt 注入加固（分隔符 + 反注入指令）
• ✅ workspace 内持久化（PVC 安全）
• ✅ 环境变量覆盖（容器友好）

---

与 skill-to-http-flash 的定位区分

→ 两个 skill 互补，不重叠。

---

快速开始

cd ~/.openclaw/workspace/skills/agent-easy-http

# 安装依赖（一次性）
pip install fastapi uvicorn pydantic httpx

# 交互式初始化（会引导启用 OpenClaw hooks）
python3 scripts/server.py init

# 启动服务（默认 https://0.0.0.0:7720）
python3 scripts/server.py start

init wizard 会：

1. 配监听端口
2. 自动检测 + 启用 OpenClaw hooks（写 ~/.openclaw/openclaw.json，热加载，无需重启）
3. 生成 API Key
4. 询问是否启用 HTTPS（默认关闭，需要时再生成证书）
5. 配 deny_skills 黑名单

---

API 端点

/agent/run 响应

{
  "success": true,
  "run_id": "6457f48c-78b0-4896-97e4-a55830d9a972",  // 用这个查 /result
  "agent_id": "(default)",
  "_openclaw": { "ok": true, "runId": "..." }       // OpenClaw 内部 cron job id
}

run_id 由 agent-easy-http 自生成（= hook session uuid 后缀），用它去 /result/{run_id} 拿 agent 输出。

/result/{run_id} 响应

{
  "status": "done",                    // pending | done | not_found
  "run_id": "6457f48c-...",
  "output": "agent 的完整回复文本",
  "messages": [{"role": "user", "text": "..."}, {"role": "assistant", "text": "..."}]
}

实测时序：触发 → 4-6s session 文件可读 → /result 返回 done。建议客户端 4s 后首次查询，每 1.5s 轮询。

请求示例

API_KEY=$(cat /.http/secrets/api-keys/agent-easy-http.key)
CERT=/.http/certs/server.crt

# 跑指定 skill
curl --cacert $CERT -H "X-API-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"message":"运行 hello-env"}' \
     https://192.168.1.10:7720/skills/hello-env/run

# 通用 agent 入口
curl --cacert $CERT -H "X-API-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"message":"帮我查下今天的天气"}' \
     https://192.168.1.10:7720/agent/run

响应

{
  "success": true,
  "skill": "hello-env",
  "run_id": "acf07e6a-d792-434c-98c3-7d738c5d6e94",
  "_openclaw": {
    "ok": true,
    "runId": "acf07e6a-d792-434c-98c3-7d738c5d6e94"
  }
}

✨ 毫秒级返回。agent 在后台跑（在 agent:main:hook: session 里），完全隔离不影响你的主会话。

---

配置文件

默认位置：/.agent-easy-http/config.json

Hook 端点解析优先级

1. AGENT_EASY_HTTP_HOOK_URL / AGENT_EASY_HTTP_HOOK_TOKEN  (env)
2. config.json 的 hook_url / hook_token
3. 自动从 ~/.openclaw/openclaw.json 推导（推荐）

用户通常不需要配 hook_url/token——init wizard 会自动启用 OpenClaw hooks 并设置好。

---

子命令

python3 scripts/server.py init              # 交互式初始化
python3 scripts/server.py setup-hooks       # 只启用 OpenClaw hooks
python3 scripts/server.py start             # 启动
python3 scripts/server.py stop              # 停止
python3 scripts/server.py status            # 状态
python3 scripts/server.py paths             # 查看所有路径
python3 scripts/server.py restart           # 重启
python3 scripts/gen_cert.py --san auto      # 重新生成证书

检测 hooks 状态（独立工具）

python3 scripts/init_wizard.py --check-hooks    # 只检测不修改
python3 scripts/init_wizard.py --setup-hooks-only  # 只启用 hooks
python3 scripts/init_wizard.py --setup-hooks-only --force-new-token  # 重置 token

自愈守护（watchdog）

# 前台跑（容器场景推荐）
bash scripts/watchdog.sh run

# 后台跑
bash scripts/watchdog.sh start
bash scripts/watchdog.sh status
bash scripts/watchdog.sh stop

watchdog 每 30s 检查 server，挂了自动重启。

---

环境变量

---

数据路径（workspace 内，PVC 安全）

/.agent-easy-http/   # 本 skill 数据
  config.json
  server.pid / server.port
  logs/server.log / watchdog.log

/.http/              # 三个 HTTP skill 共享
  certs/server.{crt,key}        # TLS（SAN 支持多 IP）
  secrets/api-keys/agent-easy-http.key  # API Key

跑 python3 scripts/server.py paths 一键查所有路径 + 存在性。

---

OpenClaw hooks 启用机制

agent-easy-http v3.0+ 依赖 OpenClaw 的原生 /hooks/agent 端点，需要 4 项配置：

init wizard 自动完成全部配置：

1. 读 ~/.openclaw/openclaw.json 检测 4 项配置完整性
2. 缺失 → 询问用户是否启用（默认 Y）+ 提示影响范围
3. 写入 openclaw.json + 可选同步到 OPENCLAW_CONFIG_SYNC_PATHS 指定的外部配置源（托管/容器环境防被外部 config 中心覆盖；普通部署无需设置）
4. 等待 Gateway 热加载（3s）+ POST 一个 ping 验证

⚠️ 如果发现 hooks 失效（外部 config 中心覆盖等情况）：

• 自动：watchdog 30s 内检测到任一配置缺失，自动调 init_wizard 修复
• 手动：跑 python3 scripts/server.py setup-hooks

⚠️ 安全说明：allowRequestSessionKey=true 是 OpenClaw 全局配置，会影响所有 /hooks/agent 调用方（不只 agent-easy-http）。受 allowedSessionKeyPrefixes=["hook:"] 限制，外部只能用 hook: 前缀，无法污染其他 session（如 webui/cron）。

---

安全模型

⚠️ GET /agents 信息披露：该接口需 API Key 鉴权，但返回内部所有 agent 的 ID 与名称。 API Key 泄露时外部可枚举所有 agent 存在。建议在不需要动态查询时，将 allowed_agent_ids 设为固定白名单而非 ["*"]，以减小攻击面。

---

切到 HTTPS（按需）

默认 HTTP 模式跑通后，跨主机调用或暴露在不太信任的网络段时建议切到 HTTPS。三步：

# 1. 生成自签 SAN 证书（自动嗅探本机 IP 写入 SAN）
python3 scripts/gen_cert.py --san auto

# 2. 编辑 config，把 tls_enabled 改成 true
#    路径: /.agent-easy-http/config.json

# 3. 重启服务
python3 scripts/server.py restart

调用方需要信任自签证书：

# 方式 A：curl --cacert 临时信任
curl --cacert /.http/certs/server.crt -H "X-API-Key: $KEY" ...

# 方式 B：导入系统信任库（Linux 示例）
sudo cp /.http/certs/server.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

详细客户端信任指引见 references/deployment.md。

---

文件结构

agent-easy-http/
├── SKILL.md
├── scripts/
│   ├── server.py            主服务（FastAPI + hook 代理）
│   ├── tls_auth.py          TLS/API Key/HMAC 模板（callback HMAC 保留备用）
│   ├── gen_cert.py          自签 SAN 证书生成
│   ├── init_wizard.py       交互式初始化 + hooks 自动启用
│   └── watchdog.sh          自愈守护脚本
└── references/
    ├── design.md            v2.0 架构设计（保留作历史参考）
    ├── tls-auth-standard.md 三 skill 共用规范
    └── deployment.md        客户端/反代/FAQ

---

与 skill-to-http(-flash) 后续对齐

skill-to-http 和 skill-to-http-flash 仍使用 openclaw agent --local（embedded 90s+ 启动）。后续可以参考本 skill 的改造把它们也切到 /hooks/agent，但作为独立项目（Phase 5）评估。