Skip to content

Leejaywell/welinker

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

51 Commits
.github/workflows
.github/workflows
 
 
Formula
Formula
 
 
docs
docs
 
 
scripts
scripts
 
 
src
src
 
 
web
web
 
 
.gitignore
.gitignore
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
build.rs
build.rs
 
 
install.sh
install.sh
 
 

Repository files navigation

Welinker

面向个人自动化工作流的消息中转服务。

Welinker 的核心不是某一个聊天入口，也不是某一个 AI Agent，而是一层可观测、可路由、可扩展的消息中转层。它把来自不同入口的消息标准化成统一事件，按规则转发给下游处理器，再把结果送回合适的出口。

当前实现里，微信是主要入口之一，Claude、Codex、Gemini、DeepSeek、Qwen、Kimi 等本地或远程 Agent 是主要处理器之一。它们都是 Welinker 消息中转能力的适配端。

内置 WebUI 提供一个本地消息中转台：可以查看运行状态、选择微信身份、向出口发送消息、直接调用处理器、编辑运行配置，并观察最近的中转事件。

长期产品方向见 Roadmap。

界面预览

Welinker 消息中转台

核心能力

  • 统一消息模型：把微信入站消息和 HTTP API 聊天请求转成统一消息事件。
  • 消息路由：支持默认路由、指定处理器、多处理器广播和运行时切换。
  • 生命周期记录：记录消息接收、路由、回复、忽略和失败结果，便于调试和审计。
  • 事件查询：通过 /api/messages 查看最近消息事件，并按来源、状态和数量过滤。
  • 入口适配：当前支持微信 iLink 和本地 HTTP API，后续可以扩展更多入口。
  • 处理器适配：当前支持 ACP、CLI、OpenAI 兼容 HTTP Agent。
  • 出口适配：当前支持回复微信消息和返回 HTTP API 响应。
  • 本地优先：默认只监听 127.0.0.1，配置、账号、日志保存在 ~/.welinker。

消息流

入口 -> 标准化消息 -> 中转事件 -> 路由 -> 处理器 -> 回复事件 -> 出口

当前典型链路：

微信消息 -> Welinker -> Agent -> 微信回复
HTTP /api/chat -> Welinker -> Agent -> HTTP 响应

中转层会记录最近消息事件，默认保留 200 条。事件可用于：

  • 确认消息是否进入系统。
  • 判断消息是被路由、忽略、回复还是失败。
  • 查看 Agent 不可用、Agent 执行失败、媒体保存失败、回复发送失败等结果。
  • 为 WebUI 或外部工具提供最近消息流。

正文保存策略由 message_events.body_mode 控制：

模式 行为
metadata 不保存正文，只保留元数据
preview 保存正文预览，默认模式
full 保存完整正文

full 会保留完整用户消息，只建议在本机可信环境中开启。

快速开始

1. 安装

构建依赖：

  • Git
  • Rust/Cargo
  • Node.js/npm，用于构建内置 WebUI

macOS / Linux

macOS 和 Linux 共用同一个一键安装脚本：

curl -fsSL https://raw.githubusercontent.com/Leejaywell/welinker/main/scripts/install.sh | bash

默认安装到 ~/.local/bin/welinker。如需指定位置：

curl -fsSL https://raw.githubusercontent.com/Leejaywell/welinker/main/scripts/install.sh | bash -s -- --prefix /usr/local

安装后如果 welinker 不在 PATH，把安装目录加入 shell 配置：

export PATH="$HOME/.local/bin:$PATH"

macOS 也可以使用 Homebrew：

brew install Leejaywell/tap/welinker

如果还没有添加 tap：

brew tap Leejaywell/tap
brew install welinker

安装最新开发版：

brew install Leejaywell/tap/welinker --HEAD

Windows

原生 Windows 安装。已安装 Git、Rust/Cargo、Node.js/npm 后，在 PowerShell 中运行：

$script="$env:TEMP\install-welinker.ps1"; iwr https://raw.githubusercontent.com/Leejaywell/welinker/main/scripts/install.ps1 -OutFile $script; powershell -ExecutionPolicy Bypass -File $script

默认安装到 %LOCALAPPDATA%\Programs\welinker\bin，并写入当前用户的 PATH。如需指定安装目录：

$script="$env:TEMP\install-welinker.ps1"; iwr https://raw.githubusercontent.com/Leejaywell/welinker/main/scripts/install.ps1 -OutFile $script; powershell -ExecutionPolicy Bypass -File $script -Prefix "$env:LOCALAPPDATA\Programs\welinker"

安装后直接启动 WebUI/API：

$script="$env:TEMP\install-welinker.ps1"; iwr https://raw.githubusercontent.com/Leejaywell/welinker/main/scripts/install.ps1 -OutFile $script; powershell -ExecutionPolicy Bypass -File $script -StartWebOnly

也可以通过 WSL 安装：

$script="$env:TEMP\install-welinker-wsl.ps1"; iwr https://raw.githubusercontent.com/Leejaywell/welinker/main/scripts/install-wsl.ps1 -OutFile $script; powershell -ExecutionPolicy Bypass -File $script

指定 WSL 发行版和安装目录：

$script="$env:TEMP\install-welinker-wsl.ps1"; iwr https://raw.githubusercontent.com/Leejaywell/welinker/main/scripts/install-wsl.ps1 -OutFile $script; powershell -ExecutionPolicy Bypass -File $script -Distro Ubuntu -InstallDir "~/welinker" -Prefix "~/.local"

WSL 安装后在 WSL 里启动：

export PATH="$HOME/.local/bin:$PATH"
welinker start --foreground --web-only

如果只把 Welinker 当作本地消息中转 API 使用，Windows、macOS、Linux 上的客户端都可以直接调用运行中的 HTTP API。

2. 启动中转服务

welinker start --foreground --web-only

--foreground 是前台运行模式，会一直占用当前终端；保持这个终端打开即可使用服务，按 Ctrl-C 停止。--web-only 会启动 WebUI 和 HTTP API，不要求先登录微信。

Welinker 会读取 ~/.welinker/config.json 里的 api_addr，所以实际端口可能不是默认的 18011。启动完成后以终端输出的 WebUI 地址为准，例如：

http://127.0.0.1:18011/

启动成功后终端会输出运行摘要。初始化配置和检测本地 Agent 可能需要几秒钟，摘要出现前终端会保持占用状态：

Welinker started
  WebUI:  http://127.0.0.1:18011/
  API:    127.0.0.1:18011
  Mode:   web-only, WeChat clients disabled
  Config: ~/.welinker/config.json
  Log:    terminal
  Agents: 3
  WeChat: 0 account(s)
  Status: listening for API requests and relay events

Next:
  open http://127.0.0.1:18011/
  keep this terminal open; press Ctrl-C to stop
  idle mode is quiet; new log lines appear on requests, messages, or errors

start 会自动检测常见本地 Agent，并把检测到的配置写入 ~/.welinker/config.json。

如果想临时指定端口：

welinker start --foreground --web-only --api-addr 127.0.0.1:18012

如果希望启动后立刻回到命令行，使用后台模式：

welinker start --web-only

3. 接入微信入口

welinker login
welinker start --foreground

按终端提示扫码登录。账号信息会保存到 ~/.welinker/accounts/。

开发时可以使用：

cargo run -- login

入口和出口

HTTP API 入口

不经过微信，直接向配置好的处理器发送消息：

curl -s http://127.0.0.1:18011/api/chat \
  -H 'content-type: application/json' \
  -d '{"message":"总结一下当前项目","agent":"codex"}'

查看最近消息事件：

/api/messages?limit=50
/api/messages?source=wechat&status=failed
/api/messages?source=api_chat

source 支持 wechat、api_chat；status 支持 received、routed、replied、ignored、failed。

微信入口和出口

微信适配用于把微信消息接入中转层，并把处理结果发回微信。

/help
/info
/new
/clear
/cwd /path/to/project
/cc 解释这个报错
/cx 帮我改这个函数
@gemini 总结这段内容
@claude @codex 对比两个实现方案

收到的图片、语音、文件和视频会保存到 save_dir，再作为消息附件进入中转事件。

处理器适配

Welinker 当前支持三类处理器：

类型 用途
ACP 接入支持 Agent Client Protocol 的本地 Agent
CLI 调用本地命令行 Agent
HTTP 调用 OpenAI 兼容或自定义 HTTP Agent

路由方式：

  • 默认处理器：未指定目标时使用 default_agent。
  • 指定处理器：通过微信别名、@agent 或 /api/chat 的 agent 字段指定。
  • 广播处理器：微信里同时 @claude @codex，分别调用多个处理器。

内置常用微信别名：

别名 Agent
/cc claude
/cx codex
/gm gemini
/cs cursor
/km kimi
/oc openclaw
/zc zeroclaw
/ocd opencode
/cp copilot
/qw qwen
/hm hermes
/hh hermes-http

其他内置别名还包括 /pi、/dr、/if、/kr。

HTTP API

内置 API 服务默认监听：

127.0.0.1:18011

如果配置文件、环境变量或命令行参数指定了其他地址，以运行时输出为准。常见覆盖方式：

welinker start --foreground --web-only --api-addr 127.0.0.1:18012
WELINKER_API_ADDR=127.0.0.1:18012 welinker start --foreground --web-only

常用接口：

方法 路径 用途
GET /api/status 查看服务状态
GET /api/accounts 查看已登录微信账号
POST /api/send 发送微信消息，多账号时可传 account_id
POST /api/chat 向中转层提交聊天消息并路由到处理器
GET /api/config 读取 ~/.welinker/config.json
PUT /api/config 校验并保存完整配置 JSON
GET /api/messages 查看最近消息事件

PUT /api/config 成功后返回：

{
  "reload_required": true
}

通过 WebUI 保存的配置会立即写入磁盘。默认处理器、别名、API 地址、保存目录等运行时配置不会热重载，修改后需要重启 Welinker 生效。

命令速查

welinker start --foreground --web-only
welinker login
welinker start --foreground
welinker start
welinker status
welinker stop
welinker restart
welinker version
welinker accounts list
welinker accounts remove "bot_id@im.bot"

手动发送微信消息：

welinker send --to "user_id@im.wechat" --text "hello"
welinker send --account "bot_id@im.bot" --to "user_id@im.wechat" --text "hello"

开发时可把 welinker 替换成 cargo run --。

配置

主配置文件：

~/.welinker/config.json

示例：

{
  "api_addr": "127.0.0.1:18011",
  "save_dir": "/Users/me/WeChat",
  "route_tag": "optional-sk-route-tag",
  "allowed_senders": ["user_id@im.wechat"],
  "allow_all_senders": false,
  "message_events": {
    "capacity": 200,
    "body_mode": "preview"
  },
  "default_agent": "gemini",
  "agents": {}
}

常用字段：

  • api_addr：内置 API 和 WebUI 监听地址。
  • save_dir：收到的图片、语音、文件和视频保存目录。
  • allowed_senders：允许驱动处理器的微信发送者 ID 列表。默认空列表会忽略微信入站消息，避免陌生联系人触发本地能力。
  • allow_all_senders：设为 true 时允许所有微信发送者触发处理器。
  • message_events.capacity：内存中保留的最近消息事件数量；默认 200。
  • message_events.body_mode：事件正文保留策略，支持 metadata、preview、full；默认 preview。
  • default_agent：默认处理器名称。
  • agents：处理器配置，支持 ACP、CLI 和 HTTP 形式。
  • route_tag：可选路由标签。

可用环境变量覆盖：

  • WELINKER_API_ADDR
  • WELINKER_SAVE_DIR
  • WELINKER_ROUTE_TAG
  • WELINKER_ALLOWED_SENDERS，多个发送者用英文逗号分隔。
  • WELINKER_ALLOW_ALL_SENDERS=1
  • WELINKER_DEFAULT_AGENT
  • WELINKER_HERMES_HTTP_URL
  • WELINKER_HERMES_HTTP_KEY
  • WELINKER_HERMES_HTTP_MODEL
  • WELINKER_ALLOW_REMOTE_API=1

运行时文件

默认保存在 ~/.welinker：

  • ~/.welinker/config.json
  • ~/.welinker/accounts/*.json
  • ~/.welinker/welinker.log
  • ~/.welinker/welinker.pid

安全说明

GET /api/config、PUT /api/config 和 POST /api/chat 会暴露敏感的本地能力：配置文件可能包含处理器 API key，聊天接口也可以调用本地命令或远程模型。因此 API 服务默认拒绝绑定到非回环地址。

微信入站消息默认只接受 allowed_senders 里的发送者。确实需要对所有联系人开放时，再显式设置 allow_all_senders: true 或 WELINKER_ALLOW_ALL_SENDERS=1。

通过 URL 发送或保存媒体时，单个下载默认限制为 25 MiB。

安全默认配置：

{
  "api_addr": "127.0.0.1:18011"
}

如确需在局域网或远程环境访问，需要显式开启：

WELINKER_ALLOW_REMOTE_API=1 welinker start --foreground --api-addr 0.0.0.0:18011

只应在可信网络或自有访问控制之后使用远程绑定。

排错

查看服务状态：

welinker status

确认当前执行的是哪个 Welinker：

which welinker
welinker version

如果刚更新过代码但命令仍然没有新日志，通常是系统 PATH 里还在执行旧安装版本。重新运行一键安装脚本，或确认 which welinker 指向刚安装的位置。

前台启动时如果暂时没有输出，先等待几秒；启动摘要只有在配置加载、Agent 检测和 API 监听完成后才会打印。摘要里的 WebUI 地址是浏览器应打开的地址：

Welinker started
  WebUI:  http://127.0.0.1:18012/
  API:    127.0.0.1:18012

如果浏览器打不开，优先检查服务实际监听端口：

lsof -nP -iTCP -sTCP:LISTEN | grep welinker

也可以直接请求状态接口：

curl -i http://127.0.0.1:18012/api/status

如果端口和 README 示例不同，说明本机 ~/.welinker/config.json、WELINKER_API_ADDR 或 --api-addr 已经覆盖了默认值，继续使用启动摘要里的地址即可。

后台模式日志位于：

~/.welinker/welinker.log

如果端口已被占用或 API 服务绑定失败，前台模式会在 tracing 日志中输出错误；后台模式会写入 ~/.welinker/welinker.log，常见日志格式如下：

api server stopped error=...

如果保存 WebUI 配置或本地聊天失败，先确认 API 是否仍在运行、api_addr 是否仍为本机可访问地址，并在修改运行时配置后重启 Welinker。

开发

常用检查：

cargo test
cargo fmt -- --check

About

面向个人自动化工作流的消息中转服务：统一消息事件、路由和生命周期记录，支持微信/API 入口与本地/HTTP Agent 处理器。

Topics

bot agent rust cli chatbot gemini bridge openai weixin wechat webui acp wechat-bot codex claude welink rust-cli ilink ai-agent deepseek

Resources

Readme

License

MIT license
Activity

Stars

5 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 1

v0.1.0 Latest
May 19, 2026

Packages

 
 
 

Contributors

Languages