mineclaw-gateway

mineclaw 的本地 HTTP/WebSocket 网关，把 coding agent 的会话能力暴露为一组 REST + WebSocket API，并附带一个用于鉴权和模型管理的 CLI。

适合：

• 给浏览器端 / 桌面端（如 Electron）做后端，提供 chat、工具调用、流式输出。
• 在本机长期跑一个常驻进程，多个客户端共享同一份会话历史、凭证和模型注册表。

安装

npm i -g mineclaw-gateway
# 或
pnpm i -g mineclaw-gateway

安装后获得 mineclaw 命令。部分可选能力（图片处理、系统剪贴板）依赖原生模块，会按平台尽力安装；装不上不影响主体功能。

快速开始

# 启动网关（默认监听 127.0.0.1:3000）
mineclaw

# 登录一个模型提供方（OAuth 订阅或 API key）
mineclaw model login

# 看一下当前已授权的模型
mineclaw model list

启动后访问：

• http://127.0.0.1:9999 —— 健康检查

官方 npm 包默认内置了 Web UI 静态产物，根路径 / 会直接 serve 出来，开箱即用。

CLI

Usage: mineclaw [command] [options]

Commands:
  (none)         启动网关（等价于 `mineclaw server start`）
  status         访问 /health 并打印当前实例信息
  stop           向 /health 报告的 pid 发 SIGTERM 优雅停止
  model <sub>    模型鉴权与注册表管理
  server <sub>   显式启动子命令（start）

Server options:
  --port <n>     监听端口（默认 3000 或 $MINECLAW_GATEWAY_PORT）
  --host <addr>  绑定地址（默认 127.0.0.1 或 $MINECLAW_GATEWAY_HOST）

model 子命令

mineclaw model login [provider]      OAuth 登录或粘 API key（无参时交互选）
mineclaw model logout [provider]     删除某个 provider 的本地凭证
mineclaw model list [--provider <p>] [--all] [--json]
                                     列出已授权模型，按 provider 分组

凭证存放在 <agentDir>/auth.json，模型注册表存放在 <agentDir>/models.json。

后台运行

CLI 本身默认前台运行，需要后台时用平台原生方式：

• Linux/macOS：nohup mineclaw > ~/.mineclaw/agent/gateway.log 2>&1 &，或写 systemd user unit。
• Windows PowerShell：Start-Process mineclaw -WindowStyle Hidden -RedirectStandardOutput ...。
• 跨平台：pm2 start mineclaw --name mineclaw-gateway。

环境变量

| 变量 | 作用 | 默认 | |---|---|---| | MINECLAW_GATEWAY_PORT | 监听端口 | 3000 | | MINECLAW_GATEWAY_HOST | 绑定地址 | 127.0.0.1 | | MINECLAW_WEB_DIST | 静态前端目录的绝对路径 | 自动探测 dist/web | | MINECLAW_AGENT_DIR | agent 数据目录（凭证、模型、会话等） | ~/.mineclaw/agent |

许可证

MIT