OpenClaw代理和网络设置教程

前言

在许多网络环境中，直接访问 OpenAI、Claude 等 AI 服务的 API 可能会受到限制。通过正确配置代理，你可以让 OpenClaw 在受限网络中正常工作。本文将详细介绍 HTTP 代理、SOCKS5 代理以及按模型分别设置代理的方法。

环境变量方式配置代理

最简单的方式是通过环境变量设置全局代理。OpenClaw 会自动读取以下标准环境变量：

环境变量	说明	示例
`HTTP_PROXY`	HTTP 请求代理	`http://127.0.0.1:7890`
`HTTPS_PROXY`	HTTPS 请求代理	`http://127.0.0.1:7890`
`ALL_PROXY`	所有请求的代理（优先级最低）	`socks5://127.0.0.1:1080`
`NO_PROXY`	不走代理的地址列表	`localhost,127.0.0.1,.local`

Linux / macOS 设置

在终端中启动 OpenClaw 之前，先导出环境变量：

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

openclaw up

如果希望每次自动生效，可以将这些变量写入 ~/.bashrc 或 ~/.zshrc：

echo 'export HTTP_PROXY="http://127.0.0.1:7890"' >> ~/.bashrc
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.bashrc
source ~/.bashrc

Windows 设置

在 PowerShell 中：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

openclaw up

若需持久化，可在系统环境变量中添加。

配置文件方式设置代理

除了环境变量，你还可以在 OpenClaw 的配置文件中直接设置代理。编辑 ~/.config/openclaw/openclaw.json5：

{
  // 全局代理设置
  proxy: {
    // HTTP/HTTPS 代理地址
    url: "http://127.0.0.1:7890",
    // 不走代理的主机名列表
    bypass: ["localhost", "127.0.0.1", "192.168.*"]
  }
}

SOCKS5 代理配置

如果你使用的是 SOCKS5 代理（例如 SSH 隧道或 Shadowsocks），配置如下：

{
  proxy: {
    url: "socks5://127.0.0.1:1080",
    // 如果代理需要认证
    username: "your-username",
    password: "your-password"
  }
}

也可以通过环境变量使用 SOCKS5：

export ALL_PROXY="socks5://127.0.0.1:1080"
openclaw up

按模型单独设置代理

不同的 AI 模型 API 可能需要不同的代理策略。例如，你可能希望 OpenAI 走海外代理，而 Ollama 本地模型不走代理。在配置文件中可以这样设置：

{
  // 全局默认代理
  proxy: {
    url: "http://127.0.0.1:7890"
  },

  models: {
    openai: {
      apiKey: "sk-xxxx",
      // OpenAI 使用全局代理（继承上面的设置）
    },
    claude: {
      apiKey: "sk-ant-xxxx",
      // Claude 使用单独的代理
      proxy: {
        url: "http://127.0.0.1:8080"
      }
    },
    ollama: {
      baseUrl: "http://localhost:11434",
      // Ollama 是本地服务，不需要代理
      proxy: {
        url: null  // 显式禁用代理
      }
    }
  }
}

代理优先级

当同时存在多种代理配置时，OpenClaw 按以下优先级应用：

模型级别代理 - 最高优先级，仅对指定模型生效
配置文件全局代理 - 次优先级
环境变量代理 - 最低优先级

代理认证

如果你的代理服务器需要用户名和密码认证，有两种配置方式：

方式一：URL 中包含认证信息

{
  proxy: {
    url: "http://username:[email protected]:8080"
  }
}

方式二：单独字段指定

{
  proxy: {
    url: "http://proxy.example.com:8080",
    username: "your-username",
    password: "your-password"
  }
}

建议使用方式二，避免密码中的特殊字符导致 URL 解析问题。

测试代理连接

配置好代理后，可以使用 openclaw doctor 命令来验证网络连通性：

openclaw doctor

该命令会依次检测：

代理服务器是否可达
通过代理能否连接到各个 AI 模型的 API 端点
DNS 解析是否正常
TLS 证书是否有效

输出示例：

[✓] 代理服务器 http://127.0.0.1:7890 可达
[✓] OpenAI API (api.openai.com) 连接正常 (延迟: 320ms)
[✓] Claude API (api.anthropic.com) 连接正常 (延迟: 280ms)
[✓] Ollama (localhost:11434) 连接正常 (延迟: 2ms)
[✓] 所有检查通过

常见连接问题排查

问题一：代理超时

如果出现 ETIMEDOUT 或 ECONNREFUSED 错误：

# 先确认代理服务是否运行
curl -x http://127.0.0.1:7890 https://httpbin.org/ip

# 检查端口是否监听
netstat -tlnp | grep 7890

问题二：SSL 证书错误

某些代理会替换 TLS 证书，导致证书验证失败：

{
  proxy: {
    url: "http://127.0.0.1:7890",
    // 仅在开发环境使用，生产环境不建议关闭
    rejectUnauthorized: false
  }
}

更安全的做法是导入代理的 CA 证书：

export NODE_EXTRA_CA_CERTS="/path/to/proxy-ca.crt"
openclaw up

问题三：公司内网需要 PAC 文件

OpenClaw 不直接支持 PAC 文件，但你可以手动解析 PAC 文件的规则，然后配置对应的代理地址。或者使用本地代理工具（如 Privoxy）将 PAC 转换为标准 HTTP 代理。

问题四：WSL 环境代理设置

在 WSL 中，需要将代理地址指向 Windows 主机的 IP：

# 获取 Windows 主机 IP
WIN_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export HTTP_PROXY="http://${WIN_HOST}:7890"
export HTTPS_PROXY="http://${WIN_HOST}:7890"

openclaw up

Docker 环境下的代理配置

如果你用 Docker 运行 OpenClaw，可以通过 docker-compose.yml 传递代理变量：

services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - HTTP_PROXY=http://host.docker.internal:7890
      - HTTPS_PROXY=http://host.docker.internal:7890
      - NO_PROXY=localhost,127.0.0.1,ollama
    ports:
      - "18789:18789"

注意 Docker 中应使用 host.docker.internal 来访问宿主机的代理服务。

总结

代理配置是在受限网络中使用 OpenClaw 的关键步骤。推荐的做法是：

个人使用：通过环境变量设置即可满足需求
多模型场景：在配置文件中按模型分别设置代理
企业部署：结合 Docker 环境变量和配置文件，做统一管理
排查问题：善用 openclaw doctor 快速定位连接问题

配置完成后，别忘了用 openclaw restart 重启服务使配置生效。