# 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`。**