diff --git a/NETWORK.md b/NETWORK.md new file mode 100644 index 0000000..0f283fe --- /dev/null +++ b/NETWORK.md @@ -0,0 +1,194 @@ +# NETWORK.md - OpenClaw 网络访问分层与规则 + +更新时间:2026-03-15 + +这份文件用于记录 OpenClaw 在当前机器上的网络访问原则,避免以后在“哪些能力该走代理、哪些能力该直连”上反复排查。 + +核心原则: + +> **默认直连;Telegram、Google 和部分海外访问按需走 mihomo `127.0.0.1:7897`。** + +--- + +## 一、当前代理基础设施 + +### mihomo +- 本地代理端口:`127.0.0.1:7897` +- 用途:作为当前机器统一的按需代理出口 +- 备注:Clash Verge 已停用,mihomo 接管 `7897` + +### OpenClaw 当前网络思路 +- **不追求 OpenClaw 全局强制走代理** +- 采用“按能力分流”策略: + - 能直连的尽量直连 + - 明确依赖海外链路的能力显式走代理 + +--- + +## 二、当前分类 + +## A. 必须代理 + +这些在当前网络环境下,应默认视为必须走代理: + +### 1. Telegram channel +- 原因:Telegram API / 连接在当前网络环境下通常无法稳定直连 +- 当前状态:已在 OpenClaw 配置中显式指定代理 +- 配置形态: + - `channels.telegram.proxy = socks5://127.0.0.1:7897` + +### 2. Gmail / Google Workspace 相关 +- 包括但不限于: + - Gmail + - Google Calendar + - Google Drive + - Google Docs + - 其它 Google API +- 原因:当前环境下直连容易超时或不可达 +- 结论:应优先走 mihomo 代理 + +--- + +## B. 建议直连 + +这些目前更适合默认直连: + +### 1. OpenClaw 主聊天链路 +- 当前主会话:`agent:main:main` +- 当前实测模型:`sub2api/gpt-5.4` +- 直连实测结果:成功 +- 代理实测结果:也成功 +- 结论:**可直连,不依赖代理** + +### 2. `sub2api` +- 性质:国内中转端点 +- 当前结论:走代理反而可能更不稳 +- 策略:默认直连 + +### 3. `lkeap` +- 性质:国内链路 provider +- 策略:默认直连 + +### 4. OpenClaw 本地能力 +- 文件读写 +- `exec` +- `gateway` +- `sessions` +- `subagents` +- `memory` +- 本地工作流与控制面 +- 策略:不需要代理 + +--- + +## C. 视场景而定 + +这些不应简单归为“全都代理”或“全都直连”,而应根据目标站点决定: + +### 1. `web_search` +- 搜索本身通常可用 +- 但搜索结果指向的目标网页如果是海外站,后续访问可能受影响 + +### 2. `web_fetch` +- 抓国内站:一般直连即可 +- 抓海外站:可能需要代理 + +### 3. `browser` +- 打开国内站:直连 +- 打开海外站(如 GitHub、Google、海外文档站):视情况走代理 + +### 4. 未来新增海外服务 +可能包括: +- Discord +- Slack(部分场景) +- X / Twitter +- OpenAI / Anthropic 直连 +- 海外 webhook / SaaS API +- 结论:新增后单独归类,不要默认混进“全局代理” + +--- + +## 三、当前判断规则 + +以后遇到新服务 / 新模型 / 新应用时,按下面顺序判断: + +### Step 1:先判断链路属性 +这个服务是: +- 本地能力? +- 国内服务? +- 海外服务? +- 国内中转? + +### Step 2:优先实测,不靠印象 +至少做两种测试: +- 直连是否成功 +- 经 `127.0.0.1:7897` 是否成功 + +### Step 3:按结果归类 +- 直连稳定,代理更差 → 归入“建议直连” +- 直连失败/明显不稳 → 归入“必须代理” +- 两者都可,但目标站点不同 → 归入“视场景而定” + +--- + +## 四、当前已确认结论(可直接复用) + +### 已确认必须代理 +- Telegram +- Gmail / Google Workspace + +### 已确认建议直连 +- `sub2api` +- `lkeap` +- OpenClaw 主聊天(当前 `sub2api/gpt-5.4`) +- OpenClaw 本地能力 + +### 已确认需要按场景判断 +- `web_search` +- `web_fetch` +- `browser` +- 未来新增海外服务 + +--- + +## 五、后续维护原则 + +### 原则 1:不要把“OpenClaw 要不要走代理”当成全局问题 +正确问题应当是: + +> **OpenClaw 的哪些能力需要代理,哪些能力不需要?** + +### 原则 2:新增模型 / 渠道 / 集成时,及时更新本文件 +每次新增能力后,补充: +- 服务名称 +- 是否必须代理 +- 测试结论 +- 推荐策略 + +### 原则 3:优先做能力级分流,不做粗暴全局翻墙 +目标是: +- 降低复杂度 +- 降低误判 +- 提高稳定性 +- 让网络问题更容易定位 + +--- + +## 六、建议的后续扩展字段(以后可加) + +后面如果服务和模型越来越多,可以在本文件中追加表格字段: + +| 名称 | 类型 | 地域属性 | 直连结果 | 代理结果 | 结论 | 备注 | +|------|------|----------|----------|----------|------|------| + +适合记录: +- 新模型 provider +- 新 channel +- 新 skill 的外部 API +- 新 webhook / SaaS 集成 + +--- + +## 一句话总纲 + +> **OpenClaw 默认直连;Telegram、Google 和部分海外访问按需走 mihomo `127.0.0.1:7897`。**