OneClaw 如何设置代理：从 proxy 配置报错到端口 17890 的完整排查实践
前言
很多人在使用 OneClaw 或 OpenClaw 时，都会遇到一个看似简单、实际容易绕路的问题：
“
为什么模型连不上网络？
为什么配置了代理却无效？
为什么会出现Unrecognized key: "proxy"报错？
OneClaw 到底应该在哪里设置代理？”
如果你正在使用 OneClaw，同时依赖本地代理工具（例如可可加速），又希望模型请求稳定访问 API，那么本文会基于一次真实配置排查过程，把整个问题讲清楚。
本文不讨论复杂网络原理，而是从实际使用角度出发，用一种尽可能容易理解的方式解释：
-
OneClaw 为什么不能直接写 proxy -
为什么系统代理和环境变量更有效 -
端口应该如何填写 -
为什么改了配置却没生效 -
使用 17890端口时应该如何正确设置
全文基于实际配置内容整理，不扩展额外技术背景，重点是帮助你快速定位问题并真正解决。
先看问题：为什么代理设置会失败？
一个典型场景如下：
用户在 OneClaw 配置文件中加入：
{
"proxy": {
"enabled": true,
"proxyUrl": "http://127.0.0.1:17890"
}
}
随后日志出现：
[reload] config reload skipped (invalid config):
Unrecognized key: "proxy"
这意味着：
“
当前版本的 OneClaw/OpenClaw 配置结构并不识别
proxy字段。”
换句话说：
不是你写错了，而是程序本身不接受这个配置项。
这是许多人第一次设置代理时最容易踩的坑。
很多人会继续：
-
修改 JSON 格式 -
调整字段顺序 -
重启程序 -
复制其他人的配置
但问题不会消失，因为根本原因不是语法错误，而是：
“
配置 schema 不支持这个键。
”
所以排查方向需要立即改变。
理解 OneClaw 的网络路径
先看一个实际配置片段：
"gateway": {
"mode": "local"
}
这里的重点是：
"mode": "local"
这意味着：
“
OneClaw 运行在本地 Gateway 模式。
”
因此：
-
模型请求不是通过某个单独代理模块出去 -
实际联网行为依赖本机环境 -
网络请求更容易受系统代理影响
这也是为什么：
“
写
proxy配置没效果，但系统代理却能立即生效。”
为什么推荐使用系统代理？
如果你使用的是本地代理工具，例如可可加速，那么最容易成功的方法通常是：
“
直接让系统接管代理。
”
而不是在 OneClaw 内部寻找“代理设置入口”。
原因很简单：
OneClaw 的运行方式决定了：
“
它通常更容易继承操作系统网络环境。
”
所以：
如果系统已经可以科学上网，那么 OneClaw 通常也能。
实际操作通常是：
-
打开代理工具 -
开启系统代理 -
或开启 TUN 模式 -
重启 OneClaw
注意：
“
重启非常重要。
”
因为很多应用只会在启动时读取网络环境。
如果只是关闭窗口而没有真正退出：
代理可能不会刷新。
为什么环境变量常常比配置文件更有效？
在这次排查中，一个关键发现是：
“
OneClaw 不识别
proxy配置。”
所以代理需要放到系统环境层。
最直接的方法：
“
设置环境变量。
”
环境变量可以理解为：
“
提前告诉程序：
“如果你要联网，请先走这里。”
”
对于本地代理工具来说，本机地址通常写成：
127.0.0.1
意思是：
“
当前这台电脑自己。
”
而端口则代表：
“
代理服务监听的位置。
”
端口从 7897 改成 17890 后，应该如何调整？
在实际排查中，代理端口后来被改成：
17890
这意味着：
之前所有：
7897
都需要同步修改。
否则：
程序仍然会尝试连接旧端口。
结果通常就是：
-
网络超时 -
模型无响应 -
请求失败
使用端口 17890 的正确代理写法
如果你的代理监听地址是：
127.0.0.1:17890
那么 HTTP/HTTPS 代理应写成：
http://127.0.0.1:17890
而 SOCKS 代理通常写成：
socks5://127.0.0.1:17890
需要注意的是：
“
地址和协议不要混用。
”
例如：
错误写法：
http://127.0.0.1:17890
却被当成 SOCKS 使用。
或者：
socks5://127.0.0.1:17890
却被当成 HTTP 使用。
这会导致：
“
明明端口正确，但代理仍然失败。
”
macOS 用户如何设置代理？
如果你是 macOS 用户，推荐方式是：
使用系统环境变量。
可以执行：
launchctl setenv HTTP_PROXY http://127.0.0.1:17890
launchctl setenv HTTPS_PROXY http://127.0.0.1:17890
launchctl setenv ALL_PROXY socks5://127.0.0.1:17890
设置完成后：
不要直接最小化 OneClaw。
正确步骤是：
-
完全退出程序 -
再重新打开
这样程序才能重新读取代理配置。
Windows 用户如何设置？
如果你使用 Windows，可以通过 PowerShell：
setx HTTP_PROXY http://127.0.0.1:17890
setx HTTPS_PROXY http://127.0.0.1:17890
setx ALL_PROXY socks5://127.0.0.1:17890
执行完成后：
建议：
“
重启 OneClaw。
”
必要时重新登录系统。
因为某些环境变量需要刷新。
为什么重启之后还是不生效？
这是很多用户第二个常见问题。
通常原因只有几类。
1. OneClaw 没有真正退出
很多桌面程序：
关闭窗口 ≠ 退出程序。
你以为已经关闭：
实际上后台还在运行。
所以：
它依旧在使用旧配置。
正确方法：
“
完全退出。
”
而不是点关闭按钮。
2. 代理客户端没开启系统代理
如果你使用的是可可加速：
需要确认：
-
系统代理已开启 -
或 TUN 模式已开启
否则：
即使环境变量正确：
请求依然可能直连。
最终表现就是：
“
配置看起来都对，但网络还是失败。
”
3. 端口没有同步修改
这是非常常见的问题。
例如：
之前配置：
7897
后来代理软件改成：
17890
但环境变量仍然是：
7897
结果：
程序仍然访问旧地址。
自然无法联网。
如何判断代理是否真的生效？
一种简单方式是：
查看程序是否恢复联网。
如果之前模型：
-
一直超时 -
无法返回结果 -
API 请求失败
而设置代理后恢复正常：
通常说明已经成功。
另一种思路：
检查当前代理地址是否正确：
127.0.0.1:17890
确认：
“
本地代理客户端确实监听这个端口。
”
否则：
程序会连接一个不存在的服务。
为什么不建议继续尝试 proxy 配置？
因为已经出现：
Unrecognized key: "proxy"
这说明：
“
当前版本根本不支持。
”
继续修改：
例如：
"proxyUrl"
或者：
"network"
本质上是在猜测配置结构。
成功率很低。
而且容易造成：
“
配置反复失效。
”
更稳妥的做法是：
“
回到系统层解决。
”
常见问题 FAQ
OneClaw 支持在 JSON 配置里写代理吗？
当前排查结果显示：
“
当前版本不识别
proxy字段。”
因此直接写：
"proxy": {}
会导致：
Unrecognized key: "proxy"
为什么我的代理设置了还是超时？
优先检查：
-
是否真正退出并重启 OneClaw -
是否开启系统代理 -
代理客户端是否运行正常 -
端口是否还是旧值 -
是否填写成：
127.0.0.1:17890
端口 17890 应该填在哪里？
取决于你如何设置。
如果是环境变量：
需要写：
http://127.0.0.1:17890
或者：
socks5://127.0.0.1:17890
为什么之前是 7897，现在变成 17890？
因为代理客户端监听端口发生变化。
这意味着：
“
所有旧端口都必须同步更新。
”
否则 OneClaw 会继续访问旧地址。
为什么关闭窗口后设置没变化？
因为：
“
应用可能还在后台运行。
”
正确方法：
“
完全退出再重启。
”
最后的建议
当 OneClaw 无法联网时，优先排查顺序建议如下：
-
确认代理工具正常运行 -
确认监听端口 -
确认是否开启系统代理 -
使用环境变量 -
彻底退出 OneClaw 后重启 -
不要继续尝试不被识别的 proxy配置
尤其当你已经看到：
Unrecognized key: "proxy"
时，方向应该立即调整。
因为这已经明确说明：
“
当前配置结构不支持这种写法。
”
与其不断修改 JSON：
不如直接从系统代理和环境变量入手。
通常更快，也更稳定。
