WaLiAPI
本地 LLM API 网关 · 多协议接入 · 知识库 RAG · MCP 工具服务
把 OpenAI、Claude、DeepSeek、Gemini 等上游模型供应商统一为一个本地网关, 用一套密钥、一套协议、一份完整审计日志,接入 Claude Code、Codex CLI、Gemini CLI、WaLiCode 等 AI 编程工具。
Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
把 OpenAI、Claude、DeepSeek、Gemini 等上游模型供应商统一为一个本地网关, 用一套密钥、一套协议、一份完整审计日志,接入 Claude Code、Codex CLI、Gemini CLI、WaLiCode 等 AI 编程工具。
WaLiAPI 是一款本地运行的 LLM API 网关桌面软件(Tauri 2 + React + Rust)。支持各类 LLM 厂商渠道接入、Ollama 自部署模型、CPA 方式 ChatGPT 渠道接入,统一支持 Chat Completions / Responses / Anthropic Messages 三协议转换使用。内置安全审计引擎、知识库 RAG(HNSW + FTS5 混合检索)、Wiki 知识引擎和 MCP Server(29 个工具),配合 Codex、Claude Code、Gemini CLI 等 AI 编程工具使用。
🎁 免费渠道开箱即用:启动即内置 OpenCode 免费车道 与 Kilo 免费池 两条免 Key 渠道,零配置直接调用;另提供 11 个免费层渠道预设——国际(Groq / Cerebras / Mistral / NVIDIA NIM / OpenRouter / GitHub Models / Hugging Face / SambaNova / Cohere)与国内(ModelScope 魔搭 / SiliconFlow 硅基流动)——注册领取 API Key 即用,Google Gemini 与智谱 GLM 也提供免费层。详见 免费渠道。
下面这张图描述了 WaLiAPI 的完整工作流:左侧是发出请求的 AI 应用,中间是 WaLiAPI 网关的处理链路(含内置的 RAG 知识库与 LLM-Wiki 知识引擎),右侧是你配置的三类上游渠道——API 渠道(Key 接入)、免费渠道(免 Key / 免费层)与账号渠道(OAuth 登录的 Auth 账号)。
flowchart LR
subgraph Clients["💬 下游 AI 应用"]
direction TB
A1["Claude Code"]
A2["Codex CLI"]
A3["Gemini CLI"]
A4["WaLiCode"]
A5["OpenClaw"]
A6["ChatBox / NextChat"]
end
subgraph Gateway["🛡️ WaLiAPI 本地网关 127.0.0.1:8777"]
direction TB
B["① 多协议接入<br/>OpenAI Chat · Responses · Anthropic"]
C["② 安全审计<br/>敏感信息扫描 · 脱敏 / 阻断"]
D["③ 智能调度<br/>优先级 + 权重 · 多 Key 负载 · 故障切换"]
E["④ 协议转换 · 上游适配<br/>OpenAI · Claude · Gemini · DeepSeek · 自定义"]
B --> C --> D --> E
subgraph Knowledge["📚 内置知识服务(复用同一调度与审计)"]
direction LR
R["RAG 知识库<br/>解析 → 分块 → 向量化<br/>HNSW + FTS5 混合检索问答"]
W["LLM-Wiki<br/>Markdown 页面 · 知识图谱<br/>MCP 工具对外暴露"]
end
end
subgraph Channels["☁️ 上游渠道(三类)"]
direction TB
F1["🔗 API 渠道(Key 接入)<br/>OpenAI · Claude · DeepSeek · Gemini<br/>智谱 · 通义 · Moonshot · 豆包 · StepFun"]
F2["🎁 免费渠道<br/>OpenCode 车道 / Kilo 池(免 Key · 启动即内置)<br/>11 家免费层:Groq · Cerebras · Mistral · NIM · OpenRouter<br/>ModelScope · 硅基流动 · GitHub Models · HF · SambaNova · Cohere"]
F3["👤 账号渠道(OAuth 登录)<br/>Codex · Kimi · Antigravity<br/>Qoder · WorkBuddy · Grok"]
end
Clients -- "统一密钥<br/>sk-waliapi-*" --> B
E -- "HTTPS 转发" --> Channels
Clients -. "MCP /mcp · REST /api/kb<br/>RAG 检索 · Wiki 问答" .-> Knowledge
Knowledge -. "Embedding / 问答模型<br/>走网关调度" .-> D
style Clients fill:#f0f7ff,stroke:#4a90d9,color:#1a3a5c
style Gateway fill:#f6f0ff,stroke:#7c5cd6,color:#3a2a5c
style Knowledge fill:#fffbea,stroke:#d9a514,color:#5c4a1a
style Channels fill:#f0fdf4,stroke:#34a853,color:#1a4a2c
一句话总结:所有下游 AI 应用都指向 WaLiAPI —— 它完成协议翻译、安全审计、负载均衡与日志审计,再把请求转发给你配置的 API 渠道、免费渠道或账号渠道;某个渠道额度用尽或故障时自动切换到下一个,AI 工具全程无感。网关内置 RAG 知识库与 LLM-Wiki 知识引擎,Agent 可通过 MCP / REST 直接检索私有知识,知识服务的模型调用同样走渠道调度与审计。
不花一分钱也能跑起来。WaLiAPI 提供两类免费渠道:
1. 免 Key 内置渠道(零配置)
首次启动时自动预建进「渠道管理」,无需注册、无需 Key,保存密钥后即可调用:
种子渠道仅添加一次,删除后不会自动加回;你可以像普通渠道一样编辑、启停或参与调度。
2. 免费层渠道预设(注册领 Key)
「新建渠道」中选择以下预设,按界面上的「获取 API Key」链接注册即用,模型清单支持「同步上游模型」拉取(自动过滤免费可用模型):
此外,已有渠道也带免费层:Google Gemini(AI Studio 免费层,Flash 系列每日 100 万 token,15 RPM)与智谱 GLM(glm-4.7-flash 等 Flash 系列免费)的预设描述中已标注免费层说明与注册入口。
💡 免费渠道额度与速率各有约束,超额时上游返回 429,网关会自动切换到下一个可用渠道。此外,通过「Auth 账号」OAuth 登录的账号渠道(如 Antigravity、Codex、Kimi、Qoder)也可使用账号自带额度,部分供应商提供免费或订阅内额度。
💡 推荐配合 WaLiCode 编码使用:https://walicode.xiaofuge.cn
WaLiAPI 提供两种部署方式:桌面端安装(适合个人开发者在本地使用)和 Docker 部署(适合团队或云服务器长期运行)。
从 GitHub Releases 或网盘下载对应平台安装包:
打开 WaLiAPI →「渠道管理」→「新建渠道」→ 填写名称、Base URL、API Key、支持的模型 → 保存。
使用 Antigravity OAuth 时,在「Auth 账号」登录后可查看各模型的已用、剩余额度和上游返回的重置时间;点击「刷新额度」可立即更新。额度百分比来自 Antigravity 模型目录的 remainingFraction,不代表具体 Token 数量。
「API 密钥」→「新建密钥」→ 生成 sk-waliapi-* 格式的本地访问令牌。
在 ChatBox / NextChat / OpenAI SDK / WaLiCode 中配置:
http://127.0.0.1:8777/v1sk-waliapi-... 密钥在「应用配置」页面选择已安装的 AI 编程工具,一键写入网关地址和密钥,无需手动编辑配置文件。
其中 Claude Code 使用的是 WaLiAPI 数据面 Bearer 网关(写入单一
ANTHROPIC_AUTH_TOKEN,值为所选真实密钥;不会写入 ANTHROPIC_API_KEY):应用配置会增量更新
~/.claude/settings.json,保留已有环境变量、权限和模型选择,并在首次写入前
保留可恢复的原文件备份。重复应用不会覆盖该备份;点击恢复即可回到写入前的
原始内容,若文件原本不存在则会删除本次创建的文件。
Claude Code 的网关密钥不等于 Anthropic 账号登录状态;配置写入后请重启客户端并发送一条消息验证。
发送失败或出现「Not logged in」应按故障排查,不能忽略。只有
需要使用 Anthropic 账号直连时才应登录。对于 Claude Code 目录未知的非 Claude
模型,WaLiAPI 只会在已有可信模型元数据时写入上下文窗口;没有可信窗口时保留
Claude Code 默认值,不会把未知模型擅自声明为 1M。需要自定义窗口时,请在
settings.json 中明确设置 CLAUDE_CODE_MAX_CONTEXT_TOKENS 与不大于它的
CLAUDE_CODE_AUTO_COMPACT_WINDOW,用户值会优先于自动兼容值。
WaLiAPI 提供 Docker 镜像,适合部署到 Linux 云服务器长期运行。镜像采用多阶段构建:Node/pnpm 编译前端,Rust 编译服务端二进制,运行时使用非 root 用户;SQLite 数据持久化在 /data。
使用 Docker Hub 镜像 fuzhengwei/waliapi 一键部署:
# 拉取镜像
docker pull fuzhengwei/waliapi:latest
# 生成管理令牌
export WALIAPI_ADMIN_TOKEN="$(openssl rand -hex 32)"
export WALIAPI_MCP_TOKEN="$(openssl rand -hex 32)"
# 启动容器
docker run -d --name waliapi \
-p 127.0.0.1:8777:8777 \
-v waliapi-data:/data \
-e WALIAPI_ADMIN_TOKEN \
-e WALIAPI_MCP_TOKEN \
fuzhengwei/waliapi:latest
docker run -d --name waliapi \
-p 127.0.0.1:8777:8777 \
-v waliapi-data:/data \
-e WALIAPI_ADMIN_TOKEN \
-e WALIAPI_MCP_TOKEN \
registry.cn-hangzhou.aliyuncs.com/xfg-studio/waliapi:0.2.5-amd64
# 验证服务
curl http://127.0.0.1:8777/health
从源码构建部署(也可直接使用上面的镜像):
git clone https://github.com/fuzhengwei/WaLiAPI.git
cd WaLiAPI
export WALIAPI_ADMIN_TOKEN="$(openssl rand -hex 32)"
export WALIAPI_MCP_TOKEN="$(openssl rand -hex 32)"
docker compose up -d --build
curl http://127.0.0.1:8777/health
Web 管理面板的前端静态资源已内嵌进 waliapi-web 二进制(rust-embed),无需单独的静态资源目录。
Compose 默认只发布到宿主机 127.0.0.1(可用 WALIAPI_BIND / WALIAPI_PORT 变量覆盖),生产环境不要把端口直接暴露到公网。推荐使用 Caddy 或 Nginx 终止 HTTPS 后反代到 127.0.0.1:8777。Caddy 配置域名后会自动申请和续期证书,示例配置见 deploy/caddy/Caddyfile.example。
后台会话、管理 Token 和 API Key 的权限分别管理:
INITIAL_PASSWORD 文件)WALIAPI_ADMIN_TOKEN(Authorization: Bearer <token>);不接受普通 API Key。/mcp):已授权 API Key 可用无会话 HTTP POST 调用 5 个 RAG 查询工具,目标库还须开启 MCP;管理工具、Wiki 和旧版 SSE 继续使用 WALIAPI_MCP_TOKEN。/v1/*):后台创建的 sk-waliapi-* 密钥# 将已授权的 API Key 保存到 WALIAPI_API_KEY 环境变量
curl -H "Authorization: Bearer $WALIAPI_API_KEY" http://127.0.0.1:8777/api/kb
curl http://127.0.0.1:8777/api/kb/ask \
-H "Authorization: Bearer $WALIAPI_API_KEY" -H "Content-Type: application/json" \
-d '{"kb_id":"你的知识库 ID","question":"你的问题","model":"已授权的生成模型"}'
RAG 的“服务 → MCP”页可选择已授权 Key 测试 REST / MCP 连接;测试不调用模型。查询必须指定 kb_id,top_k 为 1–50,向量检索与问答的全部模型调用沿用该 Key 的模型、渠道限制和额度,Embedding 也会记录在该 Key 的日志中。API Key 暂不支持 deep_research,也不能读取或写入共享会话历史。
宽松 CORS 只作用于数据面 /v1/* 路由;KB/Wiki/MCP 服务路由与管理面板不附带跨域允许头,任意网页无法跨域读取知识资产。反向代理只负责 TLS 和转发,不得移除或绕过认证头。绑定非回环地址而缺少上述 token 时,启动日志会输出醒目告警。
先执行 pnpm build 和 cargo build --release --manifest-path src-tauri/Cargo.toml --bin waliapi-web --no-default-features --features embed-web。将 release 二进制和前端 dist/ 放到 /opt/waliapi/,创建 waliapi 系统用户。systemd 沙箱通过 StateDirectory=waliapi 创建并授权固定的数据目录 /var/lib/waliapi;若确需改到其他目录,必须同步修改 unit 的可写路径。
用仅 root 可读的权限安装环境文件,再填写管理员 token:
sudo install -Dm600 deploy/systemd/waliapi.env.example /etc/waliapi/waliapi.env
sudo chown root:root /etc/waliapi/waliapi.env
sudoedit /etc/waliapi/waliapi.env
然后安装服务:
sudo install -Dm644 deploy/systemd/waliapi.service /etc/systemd/system/waliapi.service
sudo systemctl daemon-reload
sudo systemctl enable --now waliapi
sudo systemctl status waliapi
release-web.yml 可以直接生成两类 Linux Web 产物:
waliapi-web-<version>-linux-x86_64.tar.gz:包含 waliapi-server、dist/、systemd 和 Caddy 示例;每次手动运行都会保存为 Workflow Artifact。ghcr.io/<owner>/<repository>:<version>:通过 GHCR 发布的 linux/amd64 Docker 镜像。推送 web-v* 标签会创建 GitHub Release、上传二进制包,并发布带版本号和 latest 标签的镜像:
git tag web-v0.2.1
git push origin web-v0.2.1
也可以从 Actions 页面手动运行;默认只构建和验证 Docker 镜像,勾选 publish_image 才会推送到 GHCR。工作流不需要、也不会读取管理员 token。镜像和二进制包都是无密钥的通用产物,必须在运行时注入。
/data(systemd 部署为 /var/lib/waliapi)WaLiAPI 作为本地网关,在下游 AI 应用和上游模型供应商之间做协议翻译、负载均衡、安全审计和日志记录。同时内置知识库引擎、Wiki 知识引擎和 MCP Server,让 AI Agent 能直接检索私有知识。
下面是完整的内部架构(含知识库 / Wiki / MCP 服务子系统):
graph TD
subgraph Downstream[下游 AI 应用]
A1[WaLiCode]
A2[Claude Code]
A3[Codex CLI]
A4[Gemini CLI]
A5[OpenClaw]
A6[ChatBox / NextChat]
end
Downstream -->|"OpenAI / Anthropic / Responses 协议<br/>Authorization: Bearer sk-waliapi-*"| Gateway
subgraph Gateway[WaLiAPI 本地网关]
B[协议转换层<br/>OpenAI Chat · Responses · Anthropic<br/>双向转换]
C[安全审计引擎<br/>风险扫描 · 脱敏/阻断 · 规则引擎]
D[渠道调度器<br/>优先级+权重 · 故障切换 · 模型映射]
E[适配器层<br/>OpenAI · Claude · DeepSeek<br/>Gemini · Custom]
F[审计日志记录<br/>请求/响应体 · Token 统计 · Trace ID]
B --> C --> D --> E
C --> F
subgraph KBService[知识库 & Wiki & MCP 服务]
G1[文档解析<br/>Markdown / Code / PDF]
G2[智能分块器<br/>滑动窗口 · 符号感知]
G3[向量化<br/>复用渠道 Embedding]
G4[HNSW 索引<br/>向量检索 + FTS5 混合]
G5[RAG 引擎<br/>混合检索 → 重排 → 生成回答]
G6["MCP Server<br/>Streamable HTTP + SSE<br/>29 个工具 [KB 13 + Wiki 16]"]
G7[Wiki 引擎<br/>结构化知识库 · frontmatter 标签<br/>wikilinks 图谱 · 摄入管道]
G1 --> G2 --> G3 --> G4
G4 --> G5
G4 -.-> G6
G7 -.-> G6
end
end
E -->|HTTPS| Upstream
subgraph Upstream[上游模型供应商]
U1[OpenAI]
U2[Claude]
U3[DeepSeek]
U4[Gemini]
U5[通义 · 智谱 · Moonshot · StepFun · 豆包 · Ollama]
end
flowchart TD
A[用户上传文档] --> B[文档解析器<br/>Markdown / Code / PDF / JSON / YAML]
B --> C[tree-sitter 代码符号提取<br/>函数 / 类 / 结构体 / 接口]
C --> D[智能分块器<br/>滑动窗口 + 重叠分块 · 符号感知]
D --> E[向量化引擎<br/>复用 WaLiAPI 渠道调度<br/>text-embedding]
E --> F
subgraph F[存储 + 索引]
F1[(SQLite<br/>chunks + FTS5)]
F2[(HNSW 向量索引<br/>文件存储)]
end
F --> G[检索阶段<br/>向量检索 HNSW + FTS5 全文检索<br/>→ 加权混合排序 Hybrid]
G --> H[RAG 生成阶段<br/>组装 Top-K 片段 + 对话历史<br/>→ 通过网关转发至 LLM<br/>→ 生成回答 + 来源引用]
WaLiAPI 内置 MCP (Model Context Protocol) Server,通过 Streamable HTTP + SSE 端点对外暴露 29 个工具(知识库 13 个 + Wiki 16 个),任何支持 MCP 的 AI Agent 均可接入:
flowchart LR
Agent[AI Agent<br/>Claude / OpenClaw / ...] -->|"POST /mcp<br/>JSON-RPC"| MCP
MCP -->|"SSE Stream"| Agent
subgraph MCP[MCP Server — WaLiAPI]
subgraph KBTools[知识库工具 ×13]
T1[search_knowledge_base<br/>语义搜索]
T2[ask_knowledge_base<br/>RAG 问答]
T3[read_document<br/>读取文档]
T4[list_knowledge_bases<br/>列出知识库]
T5[get_knowledge_base_stats<br/>知识库统计]
T6[create / update / delete<br/>知识库 CRUD]
T7[upload_document<br/>上传文档]
T8[list_documents<br/>文档列表]
T9[build_index<br/>构建索引]
T10[import_source<br/>多源导入]
T11[delete_document<br/>删除文档]
end
subgraph WikiTools[Wiki 工具 ×16]
W1[list / get / create<br/>delete_wiki_project]
W2[list / get / save<br/>delete_wiki_page]
W3[search_wiki<br/>页面搜索]
W4[ask_wiki<br/>Wiki 问答]
W5[get_wiki_tags<br/>标签列表]
W6[get_wiki_graph<br/>知识图谱]
W7[list / add / delete<br/>ingest_wiki_source]
end
end
MCP --> KB[(知识库 + Wiki<br/>SQLite + HNSW)]
sk-waliapi-* 格式的本地访问密钥~/.ssh、.env、云凭据)、Unicode 隐写字符(零宽字符、方向控制字符)、可疑工具调用(curl 外联、管道上传)、网络风险(公网 IP 探测、Webhook/隧道域名)、追踪像素与风控指纹[[wikilinks]] → 摄入状态机(pending / ingested / failed)/mcp 端点对外提供 29 个工具(知识库 13 + Wiki 16)WaLiAPI 在网关层做协议翻译,入口多协议,出口统一为 OpenAI Chat Completions,上游渠道无感知。
接入示例(以 OpenAI 协议为例):
curl http://127.0.0.1:8777/v1/chat/completions \
-H "Authorization: Bearer sk-waliapi-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}]
}'
接入示例(以 Anthropic 协议为例):
curl http://127.0.0.1:8777/v1/messages \
-H "x-api-key: sk-waliapi-xxxx" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}]
}'
💡 在「接入示例」页面可查看 cURL / Python / Node.js / TypeScript / Rust / Java 共 5 平台 × 3 协议 = 15 套代码示例。
WaLiAPI/
├── src/ # 前端源码
│ ├── pages/
│ │ ├── DashboardPage.tsx # 仪表盘
│ │ ├── ChannelsPage.tsx # 渠道管理
│ │ ├── AuthChannelsPage.tsx # Auth 账号管理
│ │ ├── ApiKeysPage.tsx # 密钥管理
│ │ ├── LogsPage.tsx # 审计日志
│ │ ├── KnowledgeBasePage.tsx # 知识库 + Wiki + MCP 服务
│ │ ├── UsagePage.tsx # 接入示例
│ │ ├── SettingsPage.tsx # 设置中心
│ │ └── AppConfigPage.tsx # 应用配置
│ ├── components/ # 通用组件
│ │ ├── ChannelForm.tsx # 渠道表单
│ │ ├── ImportDialog.tsx # 导入对话框
│ │ ├── MappingSection.tsx # 模型映射组件
│ │ ├── UpdateChecker.tsx # 应用更新检查
│ │ ├── auth/ # Auth 账号组件
│ │ ├── channel-form/ # 渠道表单子组件
│ │ └── layout/ # 布局组件
│ ├── hooks/ # 自定义 Hooks
│ ├── lib/ # 工具库 (api.ts, constants.ts)
│ └── types/ # TypeScript 类型定义
├── src-tauri/ # 后端源码
│ ├── src/
│ │ ├── server/ # HTTP 服务器
│ │ │ ├── router.rs # 路由定义 (含服务注册)
│ │ │ └── handlers.rs # 请求处理器
│ │ ├── adaptor/ # 渠道适配器
│ │ │ ├── mod.rs # Adaptor Trait + 配置
│ │ │ ├── openai.rs # OpenAI 适配器
│ │ │ ├── claude.rs # Claude 适配器
│ │ │ ├── deepseek.rs # DeepSeek 适配器
│ │ │ ├── gemini.rs # Gemini 适配器
│ │ │ └── custom.rs # 自定义适配器
│ │ ├── protocol/ # 协议转换层 (v0.2.1 结构化重构)
│ │ │ ├── mod.rs # 双向格式转换
│ │ │ ├── sse_bridge.rs # SSE 流桥接 (字节级重组 · CJK 安全)
│ │ │ ├── codec/ # 编解码器 (目录化)
│ │ │ │ ├── chat/ # Chat 协议编解码
│ │ │ │ ├── messages/ # Anthropic Messages 编解码
│ │ │ │ ├── responses_codec/ # Responses API 编解码
│ │ │ │ └── directions/ # 跨协议方向转换
│ │ │ │ ├── messages_to_responses/
│ │ │ │ └── responses_to_messages/
│ │ │ └── responses.rs # Responses SSE 流式
│ │ ├── core/ # 核心逻辑
│ │ │ ├── proxy.rs # 代理转发 + 安全扫描 + 重试
│ │ │ ├── dispatcher.rs # 渠道调度 (优先级/权重/故障切换)
│ │ │ ├── endpoint_executor/ # 端点执行器
│ │ │ │ ├── driver.rs # 请求驱动 (日志写入/重试/流式)
│ │ │ │ ├── sse.rs # SSE 流处理
│ │ │ │ └── estimate_usage.rs # Token 用量估算
│ │ │ └── auth_provider/ # Auth 账号管理
│ │ │ ├── service.rs # Auth 服务
│ │ │ ├── maintenance.rs # Token 维护/刷新
│ │ │ ├── codex_login.rs # Codex 登录流程
│ │ │ ├── codex_backend.rs # Codex 后端对接
│ │ │ ├── kimi_login.rs # Kimi 设备 OAuth 登录
│ │ │ ├── kimi_backend.rs # Kimi 后端对接
│ │ │ ├── spec.rs # Provider 元数据与协议快照
│ │ │ └── types.rs # Auth 通用类型
│ │ ├── security/ # 安全审计
│ │ │ ├── scanner.rs # 风险扫描引擎
│ │ │ ├── rules.rs # 规则定义
│ │ │ ├── redact.rs # 脱敏处理
│ │ │ └── mod.rs # 安全设置
│ │ ├── services/ # 服务层
│ │ │ ├── mod.rs # Service Trait + 注册表
│ │ │ ├── knowledge/ # 知识库服务
│ │ │ │ ├── parser.rs # 文档解析 (MD/Code/PDF/JSON)
│ │ │ │ ├── code_parser.rs # tree-sitter 代码符号提取
│ │ │ │ ├── splitter.rs # 智能分块器
│ │ │ │ ├── embedder.rs # 向量化 (复用渠道调度)
│ │ │ │ ├── index.rs # HNSW 向量索引
│ │ │ │ ├── retriever.rs # 混合检索 (HNSW + FTS5)
│ │ │ │ ├── rag.rs # RAG 问答引擎
│ │ │ │ ├── processor.rs # 文档处理流水线
│ │ │ │ ├── importer.rs # 多源导入 (Git/URL/目录)
│ │ │ │ ├── repository.rs # 数据访问层
│ │ │ │ └── routes.rs # 知识库路由
│ │ │ ├── wiki/ # Wiki 知识引擎
│ │ │ │ ├── mod.rs # WikiService 定义
│ │ │ │ ├── models.rs # 数据模型 (Project/Page/Source)
│ │ │ │ ├── repository.rs # 数据访问层
│ │ │ │ ├── project.rs # 项目目录管理
│ │ │ │ ├── ingest.rs # 文档摄入管道 (frontmatter/wikilinks)
│ │ │ │ ├── handlers.rs # Wiki 请求处理器
│ │ │ │ └── routes.rs # Wiki 路由
│ │ │ └── mcp/ # MCP Server
│ │ │ ├── mod.rs # MCP Service 定义
│ │ │ └── handlers.rs # JSON-RPC 工具处理 (29 个工具)
│ │ ├── commands/ # Tauri Commands
│ │ │ ├── channel.rs # 渠道管理
│ │ │ ├── api_key.rs # 密钥管理
│ │ │ ├── auth.rs # Auth 账号管理
│ │ │ ├── log.rs # 日志管理
│ │ │ ├── stats.rs # 统计数据
│ │ │ ├── settings.rs # 设置管理
│ │ │ ├── security.rs # 安全规则
│ │ │ ├── knowledge_base.rs # 知识库命令
│ │ │ ├── wiki.rs # Wiki 命令
│ │ │ ├── services.rs # 服务状态
│ │ │ ├── app_config.rs # 应用配置 (8 款工具)
│ │ │ ├── import_export.rs # 导入导出
│ │ │ └── server.rs # 服务控制
│ │ ├── db/ # 数据库层
│ │ │ ├── mod.rs # Database 初始化
│ │ │ ├── models.rs # 数据模型
│ │ │ └── repository.rs # 数据访问
│ │ ├── utils/ # 工具函数
│ │ ├── channel_presets.rs # 渠道预设注册表
│ │ ├── lib.rs # 入口 + 系统托盘
│ │ └── main.rs # main 函数
│ ├── migrations/ # 数据库迁移 (27 个)
│ └── tauri.conf.json # Tauri 配置
└── package.json
WaLiAPI 定位为本地 / 内网优先的 LLM 网关。公网部署前请先阅读本节,并确认边界假设与你的部署环境一致。
凭证与权限:
明文密钥存储(知情声明):上游渠道密钥与网关 API Key 以明文存储在本地 SQLite 数据目录中——数据目录的文件系统权限就是安全边界,本项目不提供静态加密。渠道导出文件包含明文密钥(界面有明示警告),请仅在受控环境操作。网关密钥在管理界面仅显示掩码,复制等显式动作才按需取回全量。
安全扫描的边界(尽力而为的 DLP):内置风险扫描引擎(敏感信息、路径、Unicode 隐写等规则)是启发式检测,按策略支持只审计 / 警告 / 脱敏 / 阻断,定位为「尽力而为的数据泄露防护」,不构成完整的内容安全方案。响应侧扫描覆盖非流式、流式与原生 Anthropic 路径,为尽力而为语义——扫描异常不阻断响应转发;扫描预算超限按 fail-closed 拒绝请求。
CORS 作用域:宽松 CORS(Access-Control-Allow-Origin: *)仅作用于数据面网关路由(API Key 鉴权的 /v1/*——跨域调用是网关的设计用法)。管理面、KB/Wiki REST 与 MCP 端点不附带宽松 CORS,浏览器跨域不可读取其响应;管理面另带 CSRF 防护(变更类请求要求 X-Requested-With 头)。
公网部署建议:Docker 默认仅绑定 127.0.0.1;确需公网暴露时,由 Caddy/Nginx 终止 TLS 后反代,注入强 WALIAPI_ADMIN_TOKEN / WALIAPI_MCP_TOKEN,不要移除认证头;SQLite 不支持多实例写同一数据目录,保持单实例。
视觉能力路由(长期方案,#15):当前版本对「请求含图片块而上游渠道以 400 拒绝」的场景,在错误信息中追加诊断提示(该渠道疑似不支持图片),不改变路由行为(fail-open)。基于渠道能力标记(supports_vision)的故障转移跳过是长期方案,见 docs/reliability-fixes-prd.md。
services/builtin_channels.rs),零配置即可调用;每实例仅种子一次,删除后不会自动加回,幂等兜底不产生重复渠道endpoint_executor/opencode_lane.rs,就地把请求整形为上游 v2 客户端指纹门禁接受的形状(公开令牌 public、固定 UA / 客户端头、会话 id 降序编码铸造 + 会话池轮换、read / shell 工具指纹逐字声明与同名工具改名),绕开 403 FreeTierErrorkey_signup_url「获取 API Key」跳转链接(前端在 Key 配置上方渲染注册提示),配套基线测试守护isFree == true 模型、OpenCode 同步只保留 -free 后缀模型(付费模型免 Key 调用必 401,同步进来只会误导),各自新增回归测试glm-4.7-flash 等免费)预设描述补充免费层说明并补注册链接docs/free-channel-integration-plan.md;全量 cargo fmt(无功能变化)services/wiki/rebuild.rs)——程序化重建索引 + LLM 语义归组 + log 一致性回溯services/wiki/backup.rs,将页面 Markdown、源文件、图片资产(含 token)与核心数据打包为 zip 备份;新增导出 / 导入命令与管理端路由,前端新增「导出 Wiki 备份」弹窗http:// 前缀、渠道导入导出图标方向max_output_tokens,旧转换硬编码 max_tokens=4096 导致长回答被静默腰斩(finish_reason=length,且预算含 reasoning tokens);现仅在请求显式携带时映射注入(修复 #162)<select> 替换为统一自定义 Select 组件,与整体 UI 语言一致services/mcp 演进为 services/software,侧边栏与知识库页新增 Link 入口(测试功能 · 开发迭代中);命令层、MCP handlers、服务端路由与 Admin 路由、知识访问控制同步适配/mcp 即可发现连接器、导入 OpenAPI、创建 / 更新 / 删除软件实例;删除需显式 confirm: true,实例级工具受审批策略闸门约束ClihubConnector(help / run 双工具);hub 未安装时回退内置精选目录mcp_online_call 命令由 Rust 侧代理请求本机 /mcp,绕开 WKWebView 对回环地址的混合内容 / CORS 限制auth_provider/qoder_backend.rs、qoder_cosy.rs、qoder_login.rs,Auth 账号体系接入 Qoder OAuth 登录、Token 刷新与模型发现;路由规划器识别 Qoder 渠道身份protocol/codec/qoder/(含聚合层)并注册进 codec registry,支持 Qoder 渠道请求/响应双向转换;前端登录弹窗、Provider 选项、Auth 渠道页同步接入services/wiki/ingest.rs,修复 Wiki PDF 摄入链路,OCR 渲染增强047_api_key_wiki_access),服务端访问控制同步收紧049)prompt_classify.rs,迁移 048),端点执行器在请求链路落库分类结果;新增可观测卡片组件RouteMapCard 渠道路由地图与 TokenHeatmap Token 热力图组件,Dashboard 配套重构047_request_log_client_name),日志页可按客户端筛选bg-gradient-to-* 因 in oklab 语法被静默丢弃导致的渐变丢失(典型症状:「网关路由」卡片 WaLiAPI 图标空白),详见 docs/adr/0002docs/mcp-gateway-feasibility.md 与 docs/mcp-gateway-plan.mdauth_provider/workbuddy_backend.rs 与 workbuddy_login.rs,Auth 账号体系接入 WorkBuddy 登录与凭证管理,路由规划器识别 WorkBuddy 渠道身份Select 组件;知识库连接面板、设置、日志、用量、应用配置等页面交互统一优化rag_embedding_batch_recovery.rs.gitattributes 锁定迁移文件行尾,新增升级诊断脚本与文档usage_stats 聚合表(迁移 046),按 (hour, model, channel_id, api_key_id) 四维主键持久化请求/成功/失败计数与 Token、耗时指标,create_log 同事务 UPSERT 累加;日志清理不再影响统计,彻底解决「清理日志后首页统计大幅缩水」dry_run 预览影响行数(前端两步确认);clear_usage_stats 支持独立清统计(不动日志);启动时自动从存量 request_logs 幂等回填聚合表usage_stats 行,不动日志)、重置失败计数(仅清 fail_count,成功率真实恢复);支持时间范围、dry_run 预览与含备份提醒的二次确认success/total 改为 success/(success+failed),重置失败计数后成功率真实回到 ~100%/v1/models 的渠道、模型黑白名单、映射别名与 Auth 账号聚合,再经 Chat 路由规划器过滤不可路由候选与仅 Embedding 渠道;保留「手动输入」与「刷新模型」,列表只读、不消耗额度;切换密钥/知识库自动清空旧选择与检测结果sqlite-compat/),启用修复版 WAL 并合并渠道状态写入,缓解并发写竞争wham/rate-limit-reset-credits),后端完整记录重置与消耗操作流水(迁移 045),重置结果即时反馈并刷新账号额度展示web_search 等 Anthropic 内置工具并跳过,不再因无法映射而拒绝整个请求,用户自定义工具正常保留转换;tool_choice 强制调用被跳过的内置工具时仍返回清晰的 unsupported feature 错误/v1 时自动补齐并清理末尾斜杠,修复智谱等 Anthropic 原生渠道因地址少 /v1 导致的 404;上游模型同步与相关集成测试约定同步更新(GET /v1/models)0.156.1),默认 0.162.0,每 6 小时从 npm registry 拉取最新版本并仅在更高时采用;支持 WALIAPI_CODEX_CLIENT_VERSION 环境变量覆盖;修复 ChatGPT 按 client_version 门控模型目录导致的模型缺失/过期问题docs/adr/0001)api_key_enabled 随渠道导出/导入透传,旧版本导出文件缺省视为启用/api/kb/ask 支持 diagnostics=true,按 permission / embedding / retrieval / answer / validation 各阶段返回状态与失败原因;健康检测不再仅凭 HTTP 200 冒充完整链路通过,需各阶段逐一校验(PR #140,@Zhengmingming1)test_api_key_knowledge_health 命令,经本机真实 HTTP 入口携带指定 API Key 请求 /api/kb/ask,验证 Key 权限、额度与完整 RAG 检测链路,返回耗时、答案、引用来源与诊断详情(PR #140,@Zhengmingming1)/embeddings 直连上游,改为复用网关的路由规划、渠道身份、Key 轮换与故障切换语义,模型匹配与端点能力判定与外部请求一致(PR #140,@Zhengmingming1)gemini_native 执行器固定调用 generateContent 无法发送 /embeddings,路由规划排除其 Embeddings 原生资格,向量请求由 OpenAI 兼容渠道承接(PR #140,@Zhengmingming1)rag_embedding_routing 等测试覆盖内部 Embedding 路由规划、渠道模式过滤与诊断响应(PR #140,@Zhengmingming1)response_format 正确映射到 Responses 协议的 text.format,JSON 输出约束跨协议生效(PR #136,@GululuCopa)fc_ 前缀,修复部分客户端解析失败(#129,@GululuCopa)modelPolicy.allow 避免主模型不可见(PR #135 / #136,@GululuCopa)stepfun,Base URL https://api.stepfun.com/v1),内置 5 条静态模型建议——step-5-preview / step-3.7-flash / step-3.5-flash / step-3.5-flash-2603 / step-1o-turbo-vision(旗舰在前,顺序即预填与连通性探测默认),预设仅声明 Chat Completions 端点与 Bearer 鉴权,模型建议可经「同步上游模型」拉取 GET /v1/models 覆盖;渠道导入导出的 v2 身份信任白名单、前后端图标与渠道类型定义同步接入(PR #127,@chyuan)/v1/models 聚合均跳过被关闭的映射;映射行点击开关即时切换,导入导出同步兼容request_headers 测试字段:修复 lib test 目标编译失败问题(PR #119)used/limit 字段(PR #92)kb.query_rewrite 开关)semantic_cache::clear 并补按模型/全清测试(迁移 035)codex login --device-auth),并处理 pending 授权状态轮询(PR #77)request_logs 表增加 detail_level(明细级别)与 started_at(开始时间)字段并建立索引,日志页与设置页同步接入策略配置,大数据量场景下日志查询与加载更高效(PR #75)chatgpt_user_id,避免导入失败或账号无法识别(PR #73)response.created 事件的处理,避免 Codex 大响应场景因 SSE 帧创建阶段异常导致 502 或流式中断(PR #66)v0.2.9 分支已并入 PR #70,包含 KB/Wiki/MCP 端点鉴权恢复、KB 上传与导入边界收紧、URL SSRF 防护、管理面认证加固、API Key 掩码展示与按需取全量等修复/health 版本号与日志目录等可观测性增强均已随 PR #70 合流auth.json 是否卡在 API Key 模式(auth_mode == "apikey" 或 OPENAI_API_KEY 非空且无 ChatGPT 登录态),命中时提示并支持一键重置为 ChatGPT 登录模式——原文件备份为 ~/.codex/auth.json.waliapi-backup,重置后运行 codex login 重新授权.waliapi-absent 标记,恢复时删除写入的配置而非尝试恢复不存在的备份;且仅在「未应用」状态下备份,避免重复应用时把已改写的配置当成原始配置覆盖备份,根治「恢复原配置永远切不回去」auth.json 不被改动STREAM_IDLE_TIMEOUT),上游长时间无数据(半开连接 / 静默挂死)时主动断开并向下游发送协议错误事件,不再无限等待Retry-After 头(支持 delta-seconds 与 RFC 7231 日期),重试前等待指定时间(上限 5 秒 + ±20% jitter),避免密集重试触发上游限流selectedKbId、由列表数据派生选中对象,保存成功后用接口返回值精准更新列表对应项,设置页即时展示最新配置(PR #60)prompt_cache_options:Codex 后端请求白名单有 prompt_cache_key 却缺配套的 prompt_cache_options,WaLiCode 走 Responses 协议必带该字段,导致整条 Responses 路径被 HTTP 400 拒绝、只能退回 Chat 协议;该字段仅作缓存提示,归入 STRIPPED 静默丢弃,与 Chat 路径行为对齐(PR #59)cached_tokens 字段(migration 026),适配器层(OpenAI / Claude / DeepSeek / Gemini / Custom)统一提取上游缓存命中用量,兼容 cached_tokens、cache_read_input_tokens、prompt_cache_hit_tokens 等多种上游字段格式reasoning_effort 字段(migration 027),流式 SSE 同步累积缓存用量failure_from_auth_upstream,仅调整 Auth 账号的状态码透传,FailureClass 分类不变,组内转移、不跨组的语义与渠道一致failure_class 字段:错误响应 body 新增 failure_class,便于客户端区分失败类型并做针对性处理continue 导致 Responses 流式事件累积代码不可达,流式 Responses 请求的响应内容从未被记录;重构为 Anthropic / Responses 统一 match 分发,并补上 response.function_call_arguments.delta 工具调用参数累积bundle.resources 的 glob 前缀使 pdfium 被打入 Contents/Resources/resources/pdfium/,运行时仅搜索 Contents/Resources/pdfium/ 导致 OCR_RENDER_FAILED,补上该落点,不改打包与签名(PR #56)ingest_wiki_source / search_wiki 在 Unicode 文本上按字节下标切片触发 core::str::slice_error_fail panic,release panic=abort 配置下导致整个 WaLiAPI 进程退出;新增 utils/text.rs 字符边界安全切片工具,覆盖 wiki ingest / repository / security scanner 路径(PR #58)401 Invalid API key,返回正确的 503 服务不可用store 字段,避免字段缺失或不一致导致的兼容性问题🔧 边框样式优化:优化界面边框视觉样式
🔧 版本号统一升级至 0.2.5(package.json / Cargo.toml / tauri.conf.json / Cargo.lock)
chatgpt_account_id 键名映射/v1/models 接口返回结果新增 Auth 账号类型模型,下游应用可发现并使用 Auth 账号提供的模型✨ Codex 卡片信息增强:卡片同时显示 5H 与周限额信息,操作按钮收为一行,提升信息密度与交互体验
🔧 版本号统一升级至 0.2.4(package.json / Cargo.toml / tauri.conf.json / Cargo.lock)
📝 README 文档完善:更新代码贡献者信息表(补齐 v0.2.2 Docker / Web 管理面板贡献者 Fla1337,同步各贡献者最新提交量与代码变更统计)
🔧 版本号统一升级至 0.2.3(package.json / Cargo.toml / tauri.conf.json / Cargo.lock)
waliapi-web 二进制(无桌面窗口),支持 Docker 和 systemd 两种部署方式,适合放在 Linux 服务器上长期运行waliapi-server → 运行时使用非 root 用户,SQLite 数据持久化到 /dataweb-v* 标签自动创建 Release、上传二进制包、发布 Docker 镜像到 GHCRapi.ts 绕过 runtime 适配层:api.ts 直接用 @tauri-apps/api/core 的 invoke,浏览器环境无 Tauri IPC 全部失败,改为统一走 runtime.ts 适配层runtime.ts 请求路径和格式不匹配后端:修正 fetch 路径、body 字段名、响应解析逻辑、补齐 CSRF 头、SSE 路径同步修正default-run 缺失导致 cargo run 报错:补上 default-run = "waliapi"reqwest 的 .timeout() 是整个请求总超时(含 SSE 传输),大量对话时 LLM 生成时间超过 timeout_secs 连接被掐断,客户端收到 502streaming_client()(仅 connect_timeout 10s,不设总超时)和 blocking_client()(connect_timeout + 总超时 timeout_secs),流式请求不再受总超时限制forward_stream + endpoint_executor + handlers.rs + embeddings 全部切换到对应 clientuseModelMappings 的 useEffect 在每次 prop 变化时重置内部状态,引入 skipNextSyncRef + markSynced() 跳过内部变更的 round-tripstore 和 stream_options 字段--help 参数路由修复🐛 Rust 基础镜像升级:rust 1.88 → 1.96
🐛 Dockerfile.tp 兼容国内镜像
🔧 tauri.conf.json 显式指定 mainBinaryName
版本号统一升级至 0.2.2(package.json / Cargo.toml / tauri.conf.json)
response_choices 字段此前始终为空,现已正确记录响应内容(content / reasoning_content / tool_calls),与非流式路径行为一致choices[].delta.content / reasoning_content / tool_calls)content_block_delta 的 text_delta / thinking_delta / input_json_delta)response.output_text.delta / response.completed)accumulated_reasoning、response_role、finish_reason、tool_calls_map 字段,build_response_choices() 方法从累积内容构建标准 JSONapi_key 作为主 Key(使用渠道级 weight),额外 Key 通过 channel_api_keys 表管理(migration 023),两者共同参与加权随机选择(副本) 后缀,密钥清空待填),免去重复配置的繁琐操作prefer_auth_accounts 与 prefer_same_protocol,所有候选混同按 priority → weight 排序auth_accounts 新增 model_mapping_json 列(migration 021),全链路支持映射名→实际模型名转换useModelMappings/MappingSection 共用组件,后端抽取 mapping_contains_source 通用函数[[wikilinks]] → 摄入状态机(pending / ingested / failed)sse_bridge.rs 新模块,修复 CJK 多字节边界帧泄漏问题(push 改 &[u8])ENDPOINT_PATHS/v1,端点只补 /messages/v1/models 接口,聚合启用渠道 + Auth 账号的完整模型列表models 列表与 model_mapping 源别名;Auth 账号模型来自同步快照中 available 且未 unavailable 的条目及其 model_mapping 源别名owned_by 归属渠道),账号模型 owned_by 为 provider;禁用 / 非活跃账号不参与聚合model_mapping 支持单目标→多目标数组映射,同优先级渠道间随机负载均衡isComposing + keyCode 229 双重防护,覆盖 ChannelForm / ApiKeysPage / KnowledgeBasePagedragDropEnabled 吞掉 HTML5 drop 事件,禁用后拖拽排序正常status >= 400 检查触发 failovertimeout_secs 字段(默认 60s,可配 1~600s),覆盖 5 个适配器 + handlers 3 处请求realSeen / mappedSeen 独立去重UserController.getUsers 这种级别workflow_run 触发,GitCode 镜像同步优化createUpdaterArtifacts: trueWaLiAPI 由一个热情的开源社区共同构建。感谢以下开发者的代码贡献(按贡献量排序)。
本项目基于 MIT 开源协议发布,具有以下权利和说明:
WaLiAPI 是一款本地运行的 LLM API 网关桌面软件(Tauri 2 + React + Rust)。支持各类 LLM 厂商渠道接入、Ollama 自部署模型、CPA 方式 ChatGPT 渠道接入,统一支持 Chat Completions / Responses / Anthropic Messages 三协议转换使用。内置安全审计引擎、知识库 RAG(HNSW + FTS5 混合检
Übersicht
WaLiAPI 是一款本地运行的 LLM API 网关桌面软件(Tauri 2 + React + Rust)。支持各类 LLM 厂商渠道接入、Ollama 自部署模型、CPA 方式 ChatGPT 渠道接入,统一支持 Chat Completions / Responses / Anthropic Messages 三协议转换使用。内置安全审计引擎、知识库 RAG(HNSW + FTS5 混合检索)、Wiki 知识引擎和 MCP Server(29 个工具),配合 Codex、Claude Code、Gemini CLI 等 AI 编程工具使用。
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
WaLiAPI läuft lokal über stdio.
Zuletzt geprüft: 2026-10-27. WaLiAPI 是一款本地运行的 LLM API 网关桌面软件(Tauri 2 + React + Rust)。支持各类 LLM 厂商渠道接入、Ollama 自部署模型、CPA 方式 ChatGPT 渠道接入,统一支持 Chat Completions / Responses / Anthropic Messages 三协议转换使用。内置安全审计引擎、知识库 RAG(HNSW + FTS5 混合检索)、Wiki 知识引擎和 MCP Server(29 个工具),配合 Codex、Claude Code、Gemini CLI 等 AI 编程工具使用。