ebd73e1c69
- Add install-launchagent.sh for auto-start on boot - Add uninstall-launchagent.sh for service removal - Update README.md with deployment instructions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
143 lines
4.5 KiB
Markdown
Executable File
143 lines
4.5 KiB
Markdown
Executable File
# 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/`
|