maxclaw - 本地 AI Agent App（Go开发省内存、完全本地、可视化 UI、开箱即用）

7×24 小时 AI 本地OpenClaw办公助理：Go 语言实现，对标OpenClaw，网关与会话全本地运行，带桌面 UI，安装后可立即上手。

Language: 中文 | English

maxclaw 是一款面向个人与团队的 Go 语言本地 AI Agent。
核心卖点是：省内存、完全本地、UI 化可视操作、开箱即用。

• Go 语言后端，资源占用更可控：单二进制网关 + 工具编排，长期运行更稳。
• 完全本地工作流：会话、记忆、工具执行、日志都在本机目录可追溯。
• 桌面 UI + Web UI：可视化配置、实时对话、文件预览、终端联动。
• 开箱即用：支持一键安装、默认工作区模板、可直接启动使用。

适合搜索关键词：Go AI Agent、本地 AI 助手、离线办公 AI、私有化 AI Agent、桌面 AI 工具、低内存 AI、OpenClaw。

---

📸 产品截图

图：maxclaw 桌面 UI（会话、设置、日志与工具联动界面）

---

✨ 核心亮点

🏠 本地优先，隐私至上

• 完全本地化 —— 会话、记忆、日志、工具调用在本机执行与保存
• 数据永不离开 —— 默认不依赖第三方托管工作流，适合机密文档和代码
• 私有可控 —— 支持私有模型网关或云模型，架构层保持本地自治

💻 精美的桌面应用

• 现代化 UI 设计 —— 优雅的圆角卡片、流畅动画、浅色/深色主题
• 实时流式对话 —— 打字机效果，边生成边看，支持智能打断
• 内置文件预览 —— PDF、Word、Excel、图片、代码，右侧直接预览
• 真终端集成 —— VS Code 同款 node-pty + xterm，按任务隔离会话

🤖 强大的 Agent 能力

• 工具自由调用 —— Web 搜索、文件操作、Shell 命令、浏览器自动化
• 多步骤浏览器控制 —— 自动登录、点击、填表、截图，轻松抓取需登录站点
• 定时任务调度 —— Cron/Every/Once 三种模式，支持编辑和执行历史追踪
• 智能记忆系统 —— 长期事实记忆 + 历史摘要，跨会话保持上下文

🔌 多渠道无缝接入

• 即时通讯 —— Telegram、Discord、WhatsApp、Slack、QQ、飞书
• 邮箱集成 —— IMAP/SMTP 收发自如
• WebSocket 实时推送 —— 替代轮询，即时响应

🛠️ 开发者友好

• 开源透明 —— Go 原生实现，Apache-2.0 许可证
• 技能系统 —— @技能名 快速加载，支持 GitHub 安装
• MCP 协议支持 —— 接入外部 MCP 服务器扩展能力
• 一键安装 —— curl | bash 即装即用，systemd/launchd 自动托管

🚀 为什么它适合长期生产使用

• 低门槛搭建：先用自然语言描述目标，再逐步细化 Skill/MCP，而不是一上来写复杂配置
• 全自动执行模式：executionMode=auto 可连续推进复杂任务，无需人工“继续”审批
• 子任务并发能力：spawn 子会话可独立上下文/模型/source 执行并回传状态
• Monorepo 友好：递归发现 AGENTS.md / CLAUDE.md，更容易命中子项目规则
• 可审计可追踪：完整日志、会话文件和执行结果都落盘，方便回溯与复盘

🧭 对标 OpenClaw 的概念映射

如果你熟悉 OpenClaw，可以把 maxclaw 理解为“同类理念下，更偏 Go 本地工程化与 UI 交付”的实现：

• Local-first Agent：同样强调本地运行与私有数据边界，maxclaw 聚焦低资源占用与长时稳定运行
• Heartbeat Context：继承 heartbeat.md 思路，支持短周期任务状态注入
• Memory 分层：长期记忆（MEMORY.md）+ 历史归档（HISTORY.md）双层结构
• Autonomous Execution：executionMode=auto 面向复杂任务连续执行
• Sub-agent / Spawn：通过 spawn 子会话拆分任务，独立上下文并回传父会话状态
• Monorepo Context Discovery：递归发现 AGENTS.md / CLAUDE.md，更适合多模块仓库

---

中文

亮点

• Go 原生实现，单二进制网关，资源占用更可控
• 完全本地工作流：会话/记忆/日志/工具执行本机落盘
• 桌面 UI + Web UI + API（同一端口，打包后静态托管）
• 开箱即用：onboard 初始化模板，一键安装快速启动
• 全自动模式（executionMode=auto）适合长流程任务
• 子会话 spawn 支持独立上下文、模型和状态回传
• 会话标题自动总结：历史任务会生成独立标题，不再直接污染最后一条消息内容
• Monorepo 上下文发现：递归 AGENTS.md / CLAUDE.md
• 多渠道接入：Telegram、WhatsApp（Bridge）、Discord、WebSocket
• 定时任务（Cron/Once/Every）+ 每日 Memory 汇总
• 完整日志：~/.maxclaw/logs

快速开始

本地开发一键启动（all-in-one）

# 构建 + 启动 Gateway + 启动 Electron 桌面应用
make build && make restart-daemon && make electron-start

标准流程

1. 安装依赖：Go 1.24+，Node.js 18+
2. 构建：make build
3. 初始化：./build/maxclaw onboard
4. 配置：编辑 ~/.maxclaw/config.json
5. 启动：./build/maxclaw-gateway -p 18890

构建产物说明： - ./build/maxclaw：完整 CLI，包含 onboard、skills、telegram bind、gateway 等子命令 - ./build/maxclaw-gateway：独立后端二进制，适合桌面端打包或无 GUI 部署

开发期常用重启命令：

make dev-gateway
make backend-restart
make dev-electron
make electron-restart

Agent CLI 常用参数： - --session/-s 指定会话 ID（默认 cli:direct） - --markdown / --no-markdown 控制输出渲染 - --logs / --no-logs 控制是否显示日志目录提示

Linux / macOS 一键安装

可直接用自动分流安装器（会按系统选择 install_linux.sh 或 install_mac.sh）：

curl -fsSL https://raw.githubusercontent.com/Lichas/maxclaw/main/install.sh | bash

常用参数示例：

# 指定版本
curl -fsSL https://raw.githubusercontent.com/Lichas/maxclaw/main/install.sh | bash -s -- --version v0.1.0

# Linux 指定安装目录和端口
curl -fsSL https://raw.githubusercontent.com/Lichas/maxclaw/main/install.sh | bash -s -- --dir /opt/maxclaw --bridge-port 3001 --gateway-port 18890

# macOS 不安装 launchd（仅拷贝文件）
curl -fsSL https://raw.githubusercontent.com/Lichas/maxclaw/main/install.sh | bash -s -- --no-launchd

Linux 默认会安装并启动： - maxclaw-bridge.service - maxclaw-gateway.service

安装后请编辑 ~/.maxclaw/config.json 填写 API Key 与模型。

配置文件

路径：~/.maxclaw/config.json

最小示例：

{
  "providers": {
    "anthropic": { "apiKey": "your-anthropic-key" }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "workspace": "/absolute/path/to/your/workspace"
    }
  }
}

OpenAI 原生模型通过官方 openai-go SDK 接入，默认 API Base 为 https://api.openai.com/v1。 Anthropic 原生模型通过官方 anthropic-sdk-go 接入，默认 API Base 为 https://api.anthropic.com。

MiniMax 配置示例

maxclaw 通过 OpenAI 兼容接口使用 MiniMax：

{
  "providers": {
    "minimax": {
      "apiKey": "your-minimax-key"
    }
  },
  "agents": {
    "defaults": {
      "model": "minimax/MiniMax-M2"
    }
  }
}

Qwen（DashScope）配置示例

{
  "providers": {
    "dashscope": {
      "apiKey": "your-dashscope-key"
    }
  },
  "agents": {
    "defaults": {
      "model": "qwen-max"
    }
  }
}

默认 API Base：https://dashscope.aliyuncs.com/compatible-mode/v1（可在 providers.dashscope.apiBase 覆盖）。

智谱 GLM（编码套餐端点）配置示例

{
  "providers": {
    "zhipu": {
      "apiKey": "your-zhipu-key",
      "apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"
    }
  },
  "agents": {
    "defaults": {
      "model": "glm-4.5"
    }
  }
}

提示：如果你使用中国大陆站点密钥（minimaxi.com），可显式设置：

{
  "providers": {
    "minimax": {
      "apiKey": "your-minimax-key",
      "apiBase": "https://api.minimaxi.com/v1"
    }
  }
}

Workspace 设置

默认工作区：~/.maxclaw/workspace

建议使用绝对路径，也支持 ~ 或 $HOME 自动展开：

{
  "agents": {
    "defaults": {
      "workspace": "~/maxclaw-workspace"
    }
  }
}

限制文件/命令只能在工作区内执行：

{
  "tools": {
    "restrictToWorkspace": true
  }
}

执行模式（safe / ask / auto）

你可以通过 agents.defaults.executionMode 控制任务执行策略： - safe：保守探索模式（更偏只读） - ask：默认模式 - auto：全自动模式，不需要人工输入“继续”来恢复计划执行

{
  "agents": {
    "defaults": {
      "executionMode": "auto",
      "maxToolIterations": 200
    }
  }
}

说明：auto 模式会放大单次执行预算；若仍达到上限会自动停止，不会等待人工审批。

Heartbeat（短周期状态）

受 OpenClaw 的 heartbeat.md 思路启发，maxclaw 会在每轮对话自动加载： - <workspace>/memory/heartbeat.md（优先） - <workspace>/heartbeat.md（兼容）

用于记录当前优先级、阻塞项、下一步检查点。onboard 会自动创建模板文件。

每日 Memory 汇总

Gateway 启动后会开启每日汇总器（每小时检查一次），自动把“前一天会话摘要”追加到： - <workspace>/memory/MEMORY.md 的 ## Daily Summaries 小节

特性： - 幂等：同一天只写一次（按 ### YYYY-MM-DD 去重） - 无会话不写入 - 用于长期记忆沉淀与跨天回顾

两层内存系统（重构版）

• memory/MEMORY.md：长期事实与偏好，始终注入系统上下文。
• memory/HISTORY.md：追加式历史摘要日志，不自动注入上下文，适合用 grep 检索。

行为： - 当会话消息达到阈值时，会自动把旧消息摘要归档到 HISTORY.md。 - 执行 /new 时，会先归档当前会话再清空会话上下文。

Skills 支持

技能目录位于 <workspace>/skills，支持两种结构： - skills/<name>.md - skills/<name>/SKILL.md

触发语法： - @skill:<name>：只加载指定技能 - $<name>：只加载指定技能 - @skill:all / $all：加载全部技能 - @skill:none / $none：本轮禁用技能加载

管理命令：

./build/maxclaw skills list
./build/maxclaw skills show <name>
./build/maxclaw skills validate
./build/maxclaw skills add https://github.com/vercel-labs/agent-skills --path skills --skill react-best-practices
./build/maxclaw browser login https://x.com

在聊天里让 Agent 安装 skills 时，请明确说“调用 exec 执行 maxclaw skills add ...”；skills 安装位置固定为 <workspace>/skills，不是 Python 包安装。

Web UI

Web UI 与 API 同端口，默认 18890：

1. 构建：make webui-install && make webui-build
2. 启动：./build/maxclaw-gateway -p 18890
3. 访问：http://localhost:18890

如果访问显示 Web UI not built，请先运行 make webui-build。

WhatsApp（Bridge）

WhatsApp 通过 bridge/（Baileys）接入，Go 侧通过 WebSocket 连接 Bridge。

1. 构建 Bridge：make bridge-install && make bridge-build
2. 启动 Bridge：BRIDGE_PORT=3001 BRIDGE_TOKEN=your-secret make bridge-run
3. 绑定（命令行扫码）：

./build/maxclaw whatsapp bind --bridge ws://localhost:3001

1. Web UI：状态页显示二维码

代理（部分地区需要）： - 设置 BRIDGE_PROXY 或 PROXY_URL/HTTP_PROXY/HTTPS_PROXY/ALL_PROXY

如果使用个人 WhatsApp 账号，希望手机发消息也触发机器人回复：

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "bridgeUrl": "ws://localhost:3001",
      "allowSelf": true
    }
  }
}

Telegram

1. 使用 @BotFather 创建 Bot，获取 Token
2. 绑定（命令行输出 QR）：

./build/maxclaw telegram bind --token "123456:AA..."

1. Web UI：状态页显示打开聊天的二维码
2. 如网络需要代理，可在配置中设置 channels.telegram.proxy（例如 http://127.0.0.1:7897）

频道配置示例

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-bot-token",
      "allowFrom": [],
      "proxy": ""
    },
    "discord": {
      "enabled": true,
      "token": "your-discord-token",
      "allowFrom": []
    },
    "whatsapp": {
      "enabled": true,
      "bridgeUrl": "ws://localhost:3001",
      "bridgeToken": "shared-secret-optional",
      "allowFrom": [],
      "allowSelf": false
    },
    "websocket": {
      "enabled": false,
      "host": "0.0.0.0",
      "port": 18791,
      "path": "/ws",
      "allowOrigins": []
    },
    "slack": {
      "enabled": false,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "allowFrom": []
    },
    "email": {
      "enabled": false,
      "consentGranted": false,
      "imapHost": "imap.example.com",
      "imapPort": 993,
      "imapUsername": "bot@example.com",
      "imapPassword": "your-imap-password",
      "smtpHost": "smtp.example.com",
      "smtpPort": 587,
      "smtpUsername": "bot@example.com",
      "smtpPassword": "your-smtp-password",
      "allowFrom": []
    },
    "qq": {
      "enabled": false,
      "wsUrl": "ws://localhost:3002",
      "accessToken": "",
      "allowFrom": []
    },
    "feishu": {
      "enabled": false,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "verificationToken": "",
      "listenAddr": "0.0.0.0:18792",
      "webhookPath": "/feishu/events",
      "allowFrom": []
    }
  }
}

Docker

仓库已内置 Dockerfile，可直接构建运行：

make docker-build
make docker-run

安全建议：生产环境为 Go 与 Bridge 配置相同的 bridgeToken，启用共享密钥认证。

Web Fetch（浏览器/Chrome 模式）

适合需要真实浏览器行为或复用登录态的站点：

{
  "tools": {
    "web": {
      "fetch": {
        "mode": "chrome",
        "scriptPath": "/absolute/path/to/maxclaw/webfetcher/fetch.mjs",
        "nodePath": "node",
        "timeout": 30,
        "waitUntil": "domcontentloaded",
        "chrome": {
          "cdpEndpoint": "http://127.0.0.1:9222",
          "profileName": "chrome",
          "userDataDir": "~/.maxclaw/browser/chrome/user-data",
          "channel": "chrome",
          "headless": true,
          "autoStartCDP": true,
          "launchTimeoutMs": 15000
        }
      }
    }
  }
}

说明： - mode=browser：临时无状态 Chromium（不复用登录态）。 - mode=chrome：优先使用 chrome.cdpEndpoint 接管现有 Chrome；若不配置 cdpEndpoint，则使用持久化 profile 目录。 - chrome.autoStartCDP=true：cdpEndpoint 不可用时自动拉起 Host Chrome 并重连。 - 若要复用你正在使用的 Chrome 登录态，请先以远程调试端口启动 Chrome（示例：--remote-debugging-port=9222）。 - 推荐登录流程（X/Twitter 等需登录站点）： - 先运行 maxclaw browser login https://x.com，在打开的受管 profile 里手动登录一次。 - 登录完成后返回对话，继续使用 web_fetch（mode=chrome）即可复用该 profile 登录态。 - chrome.takeoverExisting 已废弃，不再用于 AppleScript 接管本地标签页。 安装 Playwright：make webfetch-install

Browser 工具（交互式页面控制）

browser 工具用于多步骤页面交互，支持： - navigate：打开页面 - snapshot：抓取页面文本与可交互元素引用（[ref]） - act：点击、输入、按键、等待 - tabs：列出/切换/关闭/新建标签页 - screenshot：保存截图

推荐流程（X/Twitter）： 1. 先执行 ./build/maxclaw browser login https://x.com 并手动登录受管 profile。 2. 在聊天中让 agent 使用 browser 工具： - action="navigate", url="https://x.com/home" - action="snapshot" - action="act", act="click", ref=3 3. 需要证据时使用 action="screenshot" 保存截图路径。

完整操作手册：BROWSER_OPS.md

MCP（Model Context Protocol）

支持把外部 MCP 服务器工具接入为原生 Agent 工具，配置格式兼容 Claude Desktop / Cursor 的 mcpServers 条目（可直接复制每个 server 的配置块）。

{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "remote-http": {
        "url": "https://mcp.example.com/sse"
      }
    }
  }
}

兼容写法：也支持将 mcpServers 放在配置文件顶层（Claude Desktop/Cursor 风格），启动时会自动合并到 tools.mcpServers。

一键启动

前台启动（Bridge + Gateway）：

make up

make up 会自动尝试清理占用 BRIDGE_PORT（默认 3001）和 GATEWAY_PORT（默认 18890）的旧进程，避免端口冲突导致启动失败。

后台常驻：

make up-daemon

重启：

make restart-daemon

停止后台服务：

make down-daemon

可用环境变量： - BRIDGE_PORT（默认 3001） - GATEWAY_PORT（默认 18890） - BRIDGE_TOKEN（可选，Bridge 认证密钥） - BRIDGE_PROXY（代理）

日志

日志目录：~/.maxclaw/logs

文件包括： - gateway.log - session.log - tools.log - channels.log - cron.log - webui.log

架构说明

详见 ARCHITECTURE.md。

维护与排障

统一维护手册：MAINTENANCE.md

English

Highlights

• Go-native agent loop and tool system
• Multi-channel: Telegram, WhatsApp (Bridge), Discord, WebSocket
• Web UI + API on the same port (static bundle served by gateway)
• Cron/Once/Every scheduler
• Heartbeat context (memory/heartbeat.md)
• Daily memory digest written to memory/MEMORY.md
• Optional browser fetch (Node + Playwright)
• Structured logs in ~/.maxclaw/logs

Quick Start

1. Install Go 1.24+ and Node.js 18+
2. Build: make build
3. Init: ./build/maxclaw onboard
4. Configure: edit ~/.maxclaw/config.json
5. Run: ./build/maxclaw-gateway -p 18890

Built binaries: - ./build/maxclaw: full CLI for onboarding, skills, channel binding, and maintenance commands - ./build/maxclaw-gateway: standalone backend for desktop packaging or headless deployment

One-Command Install (Linux / macOS)

Use the auto-switch installer (it dispatches to install_linux.sh or install_mac.sh):

curl -fsSL https://raw.githubusercontent.com/Lichas/maxclaw/main/install.sh | bash

Common examples:

```bash

Pin a specific release tag

curl -fsSL https://raw.githubusercontent.com/Lichas/maxclaw/main/install.sh | b