openclaw-ollama-toolcall-proxy/README.md

OpenClaw Ollama Toolcall Proxy

提供在 OpenClaw 和 Ollama 之间的一个轻量级本地兼容 HTTP 代理层，专门修复部分大模型直接把函数调用（Tool Call）作为 XML 文本输出在 content 里，而无法触发本地 Agent 的问题。

背景原理

当我们使用诸如 OpenClaw 这类 Agent 框架连接 Ollama 提供的开源大模型时：

• 大模型（如特定微调版本）由于对齐方式，有时会在回答（content）中使用形如 <function=xxx> 的 XML/标记格式呼叫工具。
• 下游的客户端（如 OpenClaw）通常只认标准结构化的 JSON tool_calls。
• 本项目由此诞生：代理接收这些含有未解析标记的流，抽取并清洗后，重新组装为符合标准 OpenAI/Ollama 协议的结构化 tool_calls。
• 如果下游本身正常输出了 tool_calls，本代理不仅会透明无痕放行，甚至兼容 <thinking> 这类原生字段体。

技术栈与特性

• 跨平台部署：Node.js + TypeScript 编写，可以在 Linux (包括 WSL)、macOS 和 Windows 上以极小资源开销跑起来。
• Fastify 核心：高性能 HTTP 代理。内部直接由内置 Fetch 转发，不携带额外重量级依赖。
• 自动修正：内置独立的 xml-toolcall 解析器重写响应体。
• 环境变量控制：利用 .env 对外暴漏服务映射控制。

---

快速上手

1. 前置要求

• 安装 Node.js (推荐 v18+)
• npm / yarn / pnpm

2. 获取代码与安装

```bash

克隆代码

git clone ssh://git@gitea.jmsu.top:2222/lingyuzeng/openclaw-ollama-toolcall-proxy.git cd openclaw-ollama-toolcall-proxy

安装依赖

npm install ```

3. 环境配置

复制环境变量样本： ```bash cp .env.example .env ``` 打开 .env 文件，你可以配置如下属性：

• OLLAMA_PROXY_TARGET=http://你的OllamaIP:11434 （代理将会将请求路由至此，例如你在局域网内部机器）
• PROXY_PORT=11435 （本代理的监听端口，为了避开 Ollama 默认的 11434）
• OLLAMA_DEFAULT_MODEL= （如果请求中不带 model 参数，可以强行兜底一个模型名）

4. 运行服务

开发或者调试模式启动（带有热更新重载）： ```bash npm run dev ``` 生产运行模式： ```bash

预先进行 TypeScript 编译构建

npm run build

从产物运行

npm run start ```

---

自定义测试说明

对于环境和转发规则是否工作，可以使用本仓库里提供好的范例 JSON 对你的新端口进行验证：

```bash

目标确保对准代理监听（默认 11435）

curl -s http://127.0.0.1:11435/api/chat
-H 'Content-Type: application/json'
-d @test/fixtures/openclaw-like-request.json ```

随后你应该能在控制台以及返回结果中观察到结构化完毕的调用了。代理在识别时会打印：[INFO] Rewriting response: found 1 tool calls in XML content。

单元与集成测试验证

项目中提供了由 Vitest 构建的测试脚本。 ```bash npm run test ``` 将会进行 xml-toolcall 解析用例和端到端整合测试。

---

macOS 开机自启动部署

本项目提供了 LaunchAgent 安装脚本，可将代理服务配置为开机自动启动。

安装步骤

1. 确保已完成前面的「获取代码与安装」和「环境配置」步骤

2. 运行安装脚本： ```bash ./install-launchagent.sh ```

3. 验证服务状态： ```bash

检查服务是否运行

launchctl list com.openclaw.ollama-proxy

测试代理响应

curl http://127.0.0.1:11435/ ```

常用命令

操作	命令
查看状态	launchctl list com.openclaw.ollama-proxy
停止服务	launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.ollama-proxy.plist
启动服务	launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.ollama-proxy.plist
查看日志	tail -f ~/Library/Logs/OpenClawOllamaProxy/stdout.log
查看错误日志	tail -f ~/Library/Logs/OpenClawOllamaProxy/stderr.log

卸载服务

```bash ./uninstall-launchagent.sh ```

多机器部署

如需在多台机器上部署，只需在每台机器上执行以下步骤：

```bash

1. 克隆代码

git clone ssh://git@gitea.jmsu.top:2222/lingyuzeng/openclaw-ollama-toolcall-proxy.git cd openclaw-ollama-toolcall-proxy

2. 安装依赖

npm install

3. 配置环境变量

cp .env.example .env

编辑 .env 配置目标 Ollama 地址

4. 安装开机自启动服务

./install-launchagent.sh ```

日志位置：~/Library/Logs/OpenClawOllamaProxy/