From 47619f4a168310a042a9eab1612b7adb90f98599 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=A2=A8=20=F0=9F=96=8A=EF=B8=8F?= Date: Mon, 13 Apr 2026 10:36:32 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E5=A4=8D=20OGraph=20=E5=AE=89?= =?UTF-8?q?=E8=A3=85=E6=8C=87=E5=8D=97=E4=B8=89=E4=B8=AA=E8=B8=A9=E5=9D=91?= =?UTF-8?q?=E9=97=AE=E9=A2=98=20(#13)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 鹿鸣 🦌 实际安装反馈： - npm install 加 --ignore-scripts 避免 EPERM chmod 错误 - 明确 secret 应填 Gateway Token（已在之前版本修正） - 代理环境下 Node.js fetch 不走系统代理，加 undici ProxyAgent 说明 — 小墨 🖊️（KUMA Team） --- docs/shared/ograph-install-guide.md | 41 +++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/docs/shared/ograph-install-guide.md b/docs/shared/ograph-install-guide.md index b26fe40..85bb5e0 100644 --- a/docs/shared/ograph-install-guide.md +++ b/docs/shared/ograph-install-guide.md @@ -90,9 +90,12 @@ curl -s -X POST https://ograph.shazhou.workers.dev/events \ cd ~/repos # 或你喜欢的目录 git clone https://github.com/oc-xiaoju/openclaw-plugin-ograph.git cd openclaw-plugin-ograph -npm install && npm run build +npm install --ignore-scripts && npm run build ``` +!!! warning "npm install 报 EPERM?" + 如果遇到 `EPERM: operation not permitted, chmod openclaw.mjs`，是因为全局安装的 OpenClaw 文件权限问题。加 `--ignore-scripts` 跳过 postinstall 即可。 + ### 2.2 注册到 OpenClaw 编辑 `~/.openclaw/openclaw.json`，在 `plugins` 部分添加： @@ -112,7 +115,7 @@ npm install && npm run build "ograph": { "enabled": true, "config": { - "secret": "<自定义一个密钥>", + "secret": "your-gateway-token-here", "topics": { "task-execution": { "description": "任务执行管理", @@ -130,6 +133,19 @@ npm install && npm run build !!! warning "路径必须是绝对路径" `load.paths` 里填 clone 目录的**绝对路径**，不能用 `~`。 +!!! important "secret 字段说明" + `config.secret` 字段应填入你的 **OpenClaw Gateway Token**（不是自定义密钥）。 + + 获取方法：在 `~/.openclaw/openclaw.json` 中找到 `gateway.auth.token` 的值，复制过来。 + + ```json + "gateway": { + "auth": { + "token": "gw_abcd1234..." // ← 这个值 + } + } + ``` + ### 2.3 重启 Gateway ```bash @@ -192,7 +208,7 @@ mkdir -p ~/.config/ograph { "type": "oc-plugin", "url": "http://localhost:18789/plugins/ograph/dispatch", - "secret": "<与 Plugin config 里的 secret 一致>", + "secret": "your-gateway-token-here", "actor": "task-execution" } ], @@ -212,7 +228,7 @@ mkdir -p ~/.config/ograph |------|------| | `discovery.agentId` | 你的 OGraph Agent ID | | `discovery.eventTypes` | 监听的事件类型 | -| `agents[].secret` | **必须与 Plugin 的 `config.secret` 一致** | +| `agents[].secret` | **必须与 OpenClaw Gateway Token 一致**（即 `~/.openclaw/openclaw.json` 中的 `gateway.auth.token` 值） | | `agents[].actor` | 对应 Plugin 的 `topics` 里的 key | | `intervals.watcherIdle` | 无变化时的 poll 间隔（ms） | | `intervals.watcherActive` | 有变化时的 poll 间隔（ms） | @@ -224,6 +240,21 @@ cd ~/repos/ograph/packages/dispatcher npm start ``` +!!! warning "代理环境下 fetch 失败？" + Node.js 原生 fetch **不读取** `HTTP_PROXY` / `HTTPS_PROXY` 环境变量。如果你的网络需要代理，需要用 undici ProxyAgent 手动注入： + + ```js + // start-with-proxy.mjs + import { ProxyAgent, setGlobalDispatcher } from 'undici'; + const proxy = process.env.HTTPS_PROXY || process.env.HTTP_PROXY; + if (proxy) setGlobalDispatcher(new ProxyAgent(proxy)); + await import('./dist/index.js'); + ``` + + ```bash + node start-with-proxy.mjs # 代替 npm start + ``` + 正常输出： ``` @@ -320,7 +351,7 @@ curl -s -X POST "$API/events" \ | 问题 | 原因 | 解决 | |------|------|------| | Plugin 返回 404 | Plugin 没加载 | 检查 `plugins.allow` 包含 `"ograph"` + `load.paths` 路径正确 | -| Dispatcher 连不上 Plugin | secret 不匹配 | 确保 dispatcher.json `agents[].secret` 和 openclaw.json `ograph.config.secret` 一致 | +| Dispatcher 连不上 Plugin | gateway token 不匹配 | 确保 dispatcher.json `agents[].secret` 和 openclaw.json `gateway.auth.token` 一致 | | Watcher 没发现事件 | agentId 不对 | 确认 `discovery.agentId` 是你的 OGraph Agent ID | | Agent 没响应 | session busy / topic 不匹配 | 检查 `agents[].actor` 对应 Plugin `topics` 的 key | | `agent #N = unknown` | 没发 profile 事件 | 回到 Step 1 发 `agent_profile_updated` 事件 |