257 lines
6.5 KiB
Markdown
257 lines
6.5 KiB
Markdown
# 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`
|
||
- 未来新增海外服务
|
||
|
||
---
|
||
|
||
## 五、执行准则（Val 网络排查与配置决策规则）
|
||
|
||
这部分不是背景说明，而是后续遇到网络问题时应优先执行的规则。
|
||
|
||
### 规则 1：默认假设“直连优先”，不要先入为主全局挂代理
|
||
除非已有明确证据，否则先不要把问题归因为“必须全局代理”。
|
||
|
||
优先排查：
|
||
- 是本地问题？
|
||
- 是目标服务本身问题？
|
||
- 是单一能力链路问题？
|
||
- 是海外访问问题？
|
||
|
||
### 规则 2：按“能力”排查，不按“OpenClaw 整体”排查
|
||
正确拆法应是：
|
||
- 主聊天模型链路
|
||
- Telegram 链路
|
||
- Gmail / Google 链路
|
||
- web_search / web_fetch / browser 链路
|
||
- 其它外部集成链路
|
||
|
||
不要把“某个能力失败”直接等同为“OpenClaw 都需要代理”。
|
||
|
||
### 规则 3：新增服务前，先做直连/代理双测
|
||
至少做两种测试：
|
||
1. 直连是否成功
|
||
2. 经 `127.0.0.1:7897` 是否成功
|
||
|
||
然后再归类为：
|
||
- 必须代理
|
||
- 建议直连
|
||
- 视场景而定
|
||
|
||
### 规则 4：新增 provider / channel / integration 后，立即更新本文件
|
||
每次新增能力后，补充：
|
||
- 服务名称
|
||
- 类型（模型 / channel / API / web / 集成）
|
||
- 地域属性（国内 / 海外 / 中转）
|
||
- 直连结果
|
||
- 代理结果
|
||
- 最终推荐策略
|
||
|
||
### 规则 5：优先做能力级分流，不做粗暴全局翻墙
|
||
目标是：
|
||
- 降低复杂度
|
||
- 降低误判
|
||
- 提高稳定性
|
||
- 让网络问题更容易定位
|
||
|
||
### 规则 6：遇到“体感上全部坏了”，先检查三件事
|
||
1. 当前会话实际使用的模型/provider 是什么
|
||
2. 当前失败的是模型链路，还是工具链路 / channel 链路
|
||
3. 代理切换过程中是否出现端口无人监听、服务重启、短时超时
|
||
|
||
### 规则 7：Telegram / Google 作为已知高优先级代理对象优先处理
|
||
当相关能力异常时，优先检查：
|
||
- mihomo 是否运行
|
||
- `127.0.0.1:7897` 是否可用
|
||
- 相关配置是否显式指向代理
|
||
|
||
---
|
||
|
||
## 六、后续维护原则
|
||
|
||
### 原则 1：不要把“OpenClaw 要不要走代理”当成全局问题
|
||
正确问题应当是：
|
||
|
||
> **OpenClaw 的哪些能力需要代理，哪些能力不需要？**
|
||
|
||
### 原则 2：新增模型 / 渠道 / 集成时，及时更新本文件
|
||
每次新增能力后，补充：
|
||
- 服务名称
|
||
- 是否必须代理
|
||
- 测试结论
|
||
- 推荐策略
|
||
|
||
### 原则 3：优先做能力级分流，不做粗暴全局翻墙
|
||
目标是：
|
||
- 降低复杂度
|
||
- 降低误判
|
||
- 提高稳定性
|
||
- 让网络问题更容易定位
|
||
|
||
---
|
||
|
||
## 七、建议的后续扩展字段（以后可加）
|
||
|
||
后面如果服务和模型越来越多，可以在本文件中追加表格字段：
|
||
|
||
| 名称 | 类型 | 地域属性 | 直连结果 | 代理结果 | 结论 | 备注 |
|
||
|------|------|----------|----------|----------|------|------|
|
||
|
||
适合记录：
|
||
- 新模型 provider
|
||
- 新 channel
|
||
- 新 skill 的外部 API
|
||
- 新 webhook / SaaS 集成
|
||
|
||
---
|
||
|
||
## 一句话总纲
|
||
|
||
> **OpenClaw 默认直连；Telegram、Google 和部分海外访问按需走 mihomo `127.0.0.1:7897`。**
|