本地优先AI智能体maxclaw：Go语言构建的低内存、全本地开发助手

1. 项目概述

如果你和我一样，对当前AI应用动辄几个G的内存占用和复杂的云端依赖感到头疼，同时又渴望一个能真正在本地、私密、高效运行的AI工作伙伴，那么maxclaw的出现，绝对值得你花上十分钟了解一下。这是一个用Go语言编写的本地优先AI智能体应用，它的核心承诺非常直接：低内存、全本地、带可视化界面、开箱即用。简单来说，它就像一个24小时待命在你电脑里的开发运维助手，所有的会话、记忆、工具执行和网关都运行在你的机器上，数据不出门，隐私有保障。

我最初被它吸引，是因为厌倦了在终端和浏览器之间来回切换，去调用那些笨重的AI服务。maxclaw提供了一个统一的桌面或Web界面，让我可以直接在项目工作区里，以对话的方式让AI帮我分析代码、执行脚本、甚至安排定时任务。更关键的是，它的后端是一个Go编译的单一二进制文件，资源占用极低，在我的老款MacBook Air上跑起来也毫无压力，这对于资源有限的开发环境或者追求极致效率的极客来说，是个巨大的优势。

2. 核心设计理念与架构解析

2.1 为何选择“本地优先”与Go语言？

在决定采用某个技术栈之前，理解其背后的设计哲学至关重要。maxclaw的“本地优先”并非一个简单的营销词汇，而是一套完整的技术决策体系。

首先，关于“本地优先”的深层考量：

1. 数据主权与隐私：所有会话历史、记忆文件（如MEMORY.md）、工具执行产生的中间文件以及日志，都存储在用户指定的本地工作空间。这意味着没有任何数据会未经允许离开你的设备。对于处理敏感代码、商业逻辑或私人信息的开发者而言，这是不可妥协的底线。
2. 网络与延迟无关性：智能体的思考、规划、工具调用循环完全在本地完成，仅在与大模型API通信时才需要网络。这避免了因网络波动导致的交互卡顿或中断，使得智能体在执行多步骤任务时更加稳定可靠。
3. 可审计性与复现性：由于所有操作痕迹都保留在本地文件系统中，你可以像审查代码git log一样，回溯智能体的整个决策和执行过程。这对于调试复杂任务、理解AI为何做出某个特定决定至关重要。

其次，Go语言作为后端核心的战略意义：

1. 极致的资源效率：Go编译出的静态二进制文件，无需庞大的运行时环境（如Python的虚拟环境或Node的node_modules）。maxclaw-gateway作为一个独立的守护进程，常驻内存通常只有几十MB，这与动辄消耗数百MB甚至上G的基于Electron或Python的AI应用形成鲜明对比。
2. 卓越的并发处理能力：Go的goroutine和channel机制，天生适合处理AI智能体场景下的高并发IO操作，例如同时处理多个聊天会话、监听文件系统事件、管理定时任务等，都能保持流畅响应。
3. 强大的跨平台部署能力：一次编译，即可生成适用于macOS、Windows、Linux的可执行文件，极大简化了分发和部署流程。这也是其能轻松打包成跨平台桌面应用（Electron）和提供一键安装脚本的基础。
4. 工程化与可维护性：Go语言强类型、简洁的语法和丰富的标准库，使得构建像maxclaw这样涉及HTTP服务器、WebSocket、子进程管理、文件操作等多模块的系统时，代码结构更清晰，依赖更明确。

注意：“本地优先”并不意味着完全离线。它仍然需要连接OpenAI、Anthropic等云端大模型API来获得智能。其“本地”性体现在工作流、状态管理和数据存储上，而非模型推理本身。

2.2 整体架构与组件协同

maxclaw的架构清晰地划分了职责，核心是一个微服务化的设计，即使它们被打包在同一个应用里。

用户界面层 (Presentation Layer) ├── 桌面应用 (Electron + React) │ ├── 主进程：管理Gateway生命周期、系统托盘、自动更新 │ └── 渲染进程：提供完整的聊天、设置、文件预览UI └── Web UI (独立的React应用) └── 通过同一Gateway端口提供浏览器访问能力 网关与服务层 (Gateway & Service Layer) └── maxclaw-gateway (Go二进制文件) ├── HTTP/WebSocket服务器：统一处理UI和API请求 ├── 智能体调度引擎：管理会话、执行工作流 ├── 工具执行器：安全地运行本地命令和脚本 ├── 记忆管理器：维护`MEMORY.md`、`HISTORY.md`等 └── 集成通道：处理Telegram、Discord等消息 数据与配置层 (Data & Config Layer) ├── 工作空间 (`~/.maxclaw/workspaces/`或自定义路径) │ ├── 会话存储 │ ├── 记忆文件 (`MEMORY.md`, `heartbeat.md`) │ └── 工具执行产物 └── 用户配置 (`~/.maxclaw/config.json`) ├── 模型供应商API密钥 ├── 智能体默认参数 └── 各集成通道配置

关键交互流程（以桌面应用为例）：

1. 用户启动Electron应用。
2. Electron主进程检查端口18890是否被占用，并清理旧进程。
3. 主进程spawn（启动）./build/maxclaw-gateway子进程。
4. Gateway启动后，在标准输出打印READY:127.0.0.1:18890信号。
5. Electron捕获此信号，确认Gateway就绪，随后加载React渲染界面。
6. 用户在UI中发送消息，React通过HTTP API将请求发送至本机localhost:18890。
7. Gateway收到请求，调用配置的AI模型API，执行规划，运行工具，并将流式响应返回给UI。
8. 所有交互产生的数据均写入本地工作空间。

这种架构的优势在于解耦：Gateway作为无状态（或状态持久化在文件系统）的后端服务，可以独立运行。这意味着你可以：

• 在服务器上以headless（无头）模式运行Gateway，通过Web UI或API远程访问。
• 在开发时，可以单独重启后端（make backend-restart）而不影响前端热重载。
• 桌面应用本质上只是一个“豪华版”的Gateway托管壳。

3. 从零开始：环境准备与首次运行

3.1 开发环境搭建（适用于想从源码构建的开发者）

如果你打算贡献代码、自定义功能，或者只是想体验最前沿的构建，那么需要搭建完整的开发环境。

系统与工具链要求：

• Go 1.24+：这是maxclaw的基石。建议使用go version管理工具（如gvm或asdf）来安装指定版本。
• Node.js 18+ 和 npm：用于构建Electron桌面应用和Web UI。同样建议使用nvm进行版本管理。
• Git：用于克隆代码库。
• Make：项目使用Makefile来统一构建命令，在Linux/macOS上通常预装，Windows用户需要安装MinGW或使用WSL。

实操步骤：

1. 克隆仓库：

   git clone https://github.com/Lichas/maxclaw.git cd maxclaw

2. 检查环境：

   go version # 应输出 go1.24 或更高 node --version # 应输出 v18.x 或更高 make --version # 确认make可用

3. 一键构建与启动（推荐）： 项目提供了一个最快捷的本地开发启动命令，它会依次完成后端构建、启动守护进程和前端Electron应用。

   make build && make restart-daemon && make electron-start

   • make build：编译Go后端二进制文件（maxclaw和maxclaw-gateway）到./build/目录。
   • make restart-daemon：重启后端的网关守护进程。
   • make electron-start：启动Electron桌面应用。

4. 独立运行与调试： 在开发过程中，你可能需要单独重启某个部分：

   make dev-gateway # 在开发模式下运行Gateway，支持热重载（如使用air工具） make backend-restart # 重启Gateway后端进程 make dev-electron # 在开发模式下运行Electron，支持前端热更新 make electron-restart # 仅重启Electron前端

踩坑记录：首次在Mac上运行make electron-start时，可能会遇到Gatekeeper安全警告，因为应用未公证。需要在“系统设置”->“隐私与安全性”中手动允许运行。对于开发阶段，这是一个正常过程。

3.2 快速体验：使用一键安装脚本（适用于Linux/macOS用户）

如果你只是想快速体验maxclaw的核心功能，而不需要接触源码，那么官方提供的一键安装脚本是最佳选择。

安装命令：

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

这个脚本会做什么？

1. 检测你的系统架构（x86_64, arm64）和操作系统。
2. 从GitHub Releases下载对应平台的最新预编译maxclaw和maxclaw-gateway二进制文件。
3. 将二进制文件放置到/usr/local/bin/（或~/.local/bin/）目录，使其在终端中全局可用。
4. 创建一个基本的默认配置文件模板。

安装后初始化：安装完成后，你需要初始化你的工作空间。

maxclaw onboard

这个命令会引导你：

• 设置默认的工作空间目录（比如~/Projects/my_ai_workspace）。
• 在~/.maxclaw/config.json中生成一个包含Anthropic和OpenAI字段的配置模板。
• 你可能需要手动编辑这个配置文件，填入你的API密钥。

启动Gateway并访问Web UI：

maxclaw-gateway -p 18890

然后在浏览器中打开http://localhost:18890，你就能看到maxclaw的Web界面了。

3.3 核心配置详解：config.json

配置文件是maxclaw的大脑，位于~/.maxclaw/config.json。理解其结构是高效使用它的关键。

{ "providers": { "anthropic": { "apiKey": "sk-ant-xxx...", "apiBase": "https://api.anthropic.com" // 可选，可配置代理或自定义端点 }, "openai": { "apiKey": "sk-proj-xxx...", "apiBase": "https://api.openai.com/v1" }, "gemini": { // 示例，需确认maxclaw是否已集成 "apiKey": "AIza..." } }, "agents": { "defaults": { "model": "anthropic/claude-3-5-sonnet-20241022", "workspace": "/Users/yourname/ai_workspace", "executionMode": "ask", "temperature": 0.7, "maxTokens": 4096 }, "specialized_coder": { // 你可以定义多个不同配置的智能体 "model": "openai/gpt-4-turbo-preview", "workspace": "/Users/yourname/code_project", "executionMode": "auto", "systemPrompt": "你是一个资深的Go和Python开发专家..." } }, "gateway": { "port": 18890, "dataDir": "~/.maxclaw" }, "integrations": { "telegram": { "enabled": false, "botToken": "YOUR_BOT_TOKEN", "allowedUserIds": [123456789] } // ... 其他集成配置 } }

配置项深度解析：

1. providers(供应商配置)：

   • apiKey：必填。支持从环境变量读取，但直接写在配置里更方便。务必保管好此文件。
   • apiBase：可选。这是一个非常实用的功能。如果你需要通过企业代理或自定义的API转发服务（注意，此处仅指合规的企业内部代理或官方认可的渠道）来访问模型，可以在这里修改。例如，"apiBase": "http://internal-proxy.company.com/v1"。严禁用于配置任何非法的网络访问渠道。

2. agents.defaults(默认智能体配置)：

   • model：格式为供应商/模型名。例如anthropic/claude-3-5-sonnet，openai/gpt-4o。它决定了智能体的“大脑”。
   • workspace：绝对路径。这是智能体的“工作台”。所有文件操作、上下文读取（如AGENTS.md）都基于此目录。建议设置为一个你经常进行编码或文档工作的项目根目录。
   • executionMode：核心行为开关。
     • safe：最保守模式。任何工具执行（如运行命令、写文件）都需要你手动确认。
     • ask（默认）：平衡模式。智能体会提出计划，并在执行可能具有风险的操作前询问。
     • auto：自主模式。对于已制定的计划，智能体会自动执行后续步骤，无需反复确认。此模式功能强大，但请确保在可信的工作空间内使用，并理解其将执行的操作。

3. 多智能体配置： 你可以在agents下定义多个配置，如上面的specialized_coder。在UI或CLI中，你可以通过指定智能体名称来切换使用不同的配置，从而实现场景化的工作流。

4. 核心功能实战：智能体工作流与高级用法

4.1 理解智能体的六层自适应生命周期

maxclaw的智能体并非一个简单的“提问-回答”循环，而是一个具备自我反思、错误恢复和学习能力的六层自适应系统。理解这个系统，能让你更好地预测和干预其行为。

第一层：验证 (Verification)

• 作用：错误分类与第一响应。
• 实战场景：你让智能体分析一个巨大的代码库，它返回了“context length exceeded”错误。
• 系统行为：验证层会立即将其归类为ContextOverflowError，而不是一个普通的HTTP错误。这触发了特定的恢复策略，而不是简单的重试。

第二层：反思 (Reflection)

• 作用：上下文管理与智能压缩。
• 实战场景：面对上述上下文溢出错误。
• 系统行为：反思层会分析当前会话历史，生成一个结构化摘要。这个摘要不是简单的截断，而是提取了对话中的关键决策、代码片段和用户意图，用极少的token保留核心信息。然后，它会用这个摘要替换部分旧历史，腾出空间给新的交互。

第三层：适应 (Adaptation)

• 作用：动态调整策略。
• 实战场景：继续处理上下文溢出。
• 系统行为：适应层可能执行以下操作：
  • 模型回退：从claude-3-opus（128K上下文）自动切换到claude-3-sonnet（200K上下文），如果配置了的话。
  • 自适应上下文长度：将本次会话的上下文窗口临时减少30%。
  • 指数退避重试：等待几秒后，使用新的策略重新发起请求。

第四层：持久化 (Persistence)

• 作用：状态检查点与会话恢复。
• 实战场景：在长时间重构任务中，你的电脑突然休眠。
• 系统行为：系统会定期将会话状态（包括完整的计划、已执行步骤、当前上下文）保存为文件系统检查点。当Gateway重启后，它可以从中断点恢复，而不是从头开始。你可以在工作空间的.sessions/目录下找到这些检查点文件。

第五层：进化 (Evolution)

• 作用：模式学习与策略优化。
• 实战场景：系统多次在处理特定类型的Go项目时遇到上下文溢出。
• 系统行为：进化层会记录这一模式：“在包含大量vendor目录和自动生成代码的Go项目中，上下文溢出频率高”。未来遇到类似项目时，系统可能会主动建议或直接采用更激进的上下文压缩策略。

第六层：反馈 (Feedback)

• 作用：从用户交互中学习。
• 实战场景：智能体写了一段有错误的代码，你手动纠正了它。
• 系统行为：反馈层通过三层检测来学习：
  1. 规则匹配（零成本）：例如，检测到你输入了“不对，应该是...”。
  2. 上下文分析（低成本）：对比智能体输出和你的后续输入，寻找修正模式。
  3. LLM语义分析（有成本）：当上述方法无法确定时，用小模型分析是否为反馈。 学习到的经验（如“在这个项目中，HTTP客户端应该使用自定义超时设置”）会被持久化到工作空间的MEMORY.md文件中，供未来会话参考。

成本控制心得：这个系统的精妙之处在于成本优化。70%的反馈检测靠规则（免费），只有15%需要调用便宜的LLM（如claude-haiku）进行语义分析，每天成本可能仅几分钱。这使得持续学习在经济上是可行的。

4.2 利用工作空间与上下文发现

智能体的能力很大程度上取决于它能看到什么。workspace配置项和“单仓库感知的递归上下文发现”功能，是赋予它强大上下文的钥匙。

基础：设置有效的工作空间不要将工作空间设为你整个用户目录（~）。这太庞大了，会导致上下文快速耗尽。应该设置为一个具体的项目根目录。

{ "agents": { "defaults": { "workspace": "/Users/me/development/my-awesome-go-project" } } }

高级：AGENTS.md与CLAUDE.md的魔法在项目根目录或关键子目录下创建AGENTS.md或CLAUDE.md文件，是向智能体注入项目特定知识的绝佳方式。

• AGENTS.md：更通用，用于描述项目结构、开发指南、常用命令等。
• CLAUDE.md：最初为Claude设计，但maxclaw也能识别，内容类似。

示例AGENTS.md：

# My Awesome Go Project - Agent Guide ## Project Overview 这是一个用Go编写的微服务API，使用Echo框架和PostgreSQL。 ## Key Directories - `/cmd/api`: 主应用入口 - `/internal`: 私有应用代码 - `/pkg`: 可公开导入的库代码 - `/migrations`: 数据库迁移文件 - `/scripts`: 部署和实用脚本 ## Development Commands - `make run`: 启动开发服务器 (hot reload) - `make test`: 运行所有测试 - `make db-migrate`: 应用数据库迁移 ## Coding Conventions 1. 使用 `goimports` 格式化代码。 2. 错误处理使用 `fmt.Errorf` 包裹上下文。 3. API响应结构统一放在 `pkg/response` 包中。 ## Common Tasks for AI Assistant - 帮我添加新的API端点，参照 `internal/handler/user.go`。 - 帮我编写数据库迁移文件。 - 帮我分析 `go test` 的输出并修复测试失败。

当智能体在新会话中分析你的项目时，它会递归地扫描工作空间，寻找这些AGENTS.md文件，并优先将它们的内容加载到上下文中。这意味着，智能体从一开始就“知道”你的项目结构、规范和常见任务，极大地提升了交互的准确性和效率。

4.3 执行模式与spawn子会话：实现复杂任务分解

执行模式 (executionMode) 的实战选择：

• 探索新项目或危险操作时，用safe：当你让智能体在一个陌生的代码库中运行rm -rf或修改关键配置时，safe模式要求每一步操作都经你手点确认，给你最大的安全感。
• 日常辅助编码，用ask：这是最常用的模式。智能体会生成一个计划（Plan），比如“1. 分析当前错误日志。2. 在代码中定位可能的问题。3. 建议修复方案。”，然后逐步执行，在需要执行命令或写文件前会询问你。你掌握了控制权，同时避免了频繁的细节确认。
• 执行明确、冗长的任务，用auto：当你已经通过几次对话让智能体理解了任务全貌，并制定了一个详细的、多步骤的计划（例如“重命名这个项目中所有User到Customer的引用”），切换到auto模式，它就会自动执行后续所有步骤，直到完成或遇到无法处理的错误。这非常适合批量处理任务。

spawn子会话：并行与隔离的利器spawn是maxclaw中一个强大的概念，它允许主会话“孵化”出一个独立的子会话来处理特定子任务。

使用场景：

1. 并行处理：主会话正在设计系统架构，同时可以spawn一个子会话来专门编写某个工具函数。
2. 隔离上下文：子会话可以拥有独立的上下文窗口、甚至不同的AI模型。例如，主会话用claude-opus进行复杂推理，而spawn一个用gpt-4o的子会话来专门生成图表描述的Mermaid代码，防止专业任务互相干扰。
3. 独立状态与回调：子会话的执行状态（成功、失败、进行中）可以通过回调函数通知主会话，实现工作流的协调。

如何在对话中使用：你可以直接在聊天中输入指令，也可以在工作空间的AGENTS.md中定义触发规则。

用户： “请为这个项目设计一个认证系统，同时，请spawn一个子任务去优化我们现有的Dockerfile。” 智能体：“好的。我将开始设计认证系统。同时，我已经创建了一个子任务来优化Dockerfile，它会独立进行，完成后会通知我结果。”

在后台，系统会创建两个独立的会话，它们拥有各自的记忆和上下文，互不阻塞。

5. 桌面应用与Web UI深度指南

5.1 Electron桌面应用：架构与打包

桌面应用是maxclaw提供原生体验的核心。其架构设计保证了稳定性和用户体验。

生命周期管理详解：

1. 启动与端口清理：

   // 伪代码示意 (electron/main.js) function startGateway() { const port = 18890; // 使用系统命令查找并杀死占用18890端口的进程 await killProcessOnPort(port); // 启动Go gateway子进程 const gatewayProcess = spawn('./build/maxclaw-gateway', ['-p', port.toString()]); // 监听子进程输出，等待READY信号 gatewayProcess.stdout.on('data', (data) => { if (data.includes('READY:127.0.0.1:' + port)) { mainWindow.loadURL(appUrl); // 信号收到，加载UI } }); }

   这个机制确保了每次启动都是干净的，避免了因上次异常退出导致的“端口已占用”错误。

2. 崩溃恢复与指数退避： 如果Gateway进程意外退出，Electron不会让应用卡死。它会尝试重启，并且每次重试的间隔时间会加倍（例如1秒，2秒，4秒...），避免在系统资源暂时不足时疯狂重试。

   let retryDelay = 1000; gatewayProcess.on('exit', (code) => { if (code !== 0) { // 非正常退出 setTimeout(() => { startGateway(); // 重启 retryDelay = Math.min(retryDelay * 2, 30000); // 退避上限30秒 }, retryDelay); } });

打包发布你的自定义版本：如果你修改了代码，并想分发给团队，可以轻松打包。

cd electron npm run dist:mac # 生成 .dmg 和 .zip 文件 npm run dist:win # 生成 Windows 安装程序 (.exe) npm run dist:linux # 生成 Linux AppImage 和 .deb 包

打包前确保已运行make build生成最新的Go二进制文件，因为Electron打包器会将其嵌入到应用包中。

5.2 Web UI：轻量级替代与API接口

Web UI提供了不依赖桌面环境的访问方式，其功能与桌面版几乎一致。

构建与运行：

make webui-install # 安装Web UI的Node.js依赖 make webui-build # 构建React前端静态文件 ./build/maxclaw-gateway -p 18890 # 启动网关，Web UI已集成

访问http://localhost:18890即可。Gateway会同时服务API请求和静态前端资源。

作为无头（Headless）服务器运行：这是将maxclaw部署到远程开发机或家庭服务器的典型场景。

1. 在服务器上通过一键脚本或Go编译安装maxclaw-gateway。
2. 配置好config.json，特别是workspace路径（确保服务器上有相应目录和文件）。
3. 使用systemd或supervisor将maxclaw-gateway -p 18890作为守护进程运行。
4. 通过服务器的IP和端口（如http://your-server-ip:18890）在浏览器中访问Web UI。
5. （重要）安全考虑：如果暴露在公网，务必设置防火墙规则、使用反向代理（如Nginx）添加HTTPS和HTTP Basic认证，绝对不要将未受保护的服务直接暴露。

5.3 多通道集成：Telegram与Discord机器人

maxclaw支持将智能体能力扩展到聊天工具中，让你能在手机或团队协作工具里与AI助手交互。

配置Telegram机器人：

1. 在Telegram中找@BotFather创建一个新机器人，获取botToken。
2. 与你的机器人开始对话，然后访问https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates来获取你的chat_id（即allowedUserIds）。
3. 在config.json中启用并配置：

   { "integrations": { "telegram": { "enabled": true, "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11", "allowedUserIds": [123456789] // 只允许你的账号使用 } } }

4. 重启Gateway。现在你就可以在Telegram中直接给你的机器人发送消息，智能体会在工作空间上下文下回复你。

配置Discord机器人：

1. 在Discord开发者门户创建应用和机器人，获取token。
2. 邀请机器人到你的服务器，并获取服务器ID和频道ID。
3. 在配置中填入相应信息。

   注意：Discord机器人的配置和权限设置（intents）相对复杂，请务必参考项目最新的README.zh.md或相关文档，确保授予机器人读取消息和发送消息的权限。

使用场景：当你离开电脑时，可以通过手机Telegram让智能体检查服务器日志、触发一个构建任务，或者让它帮你构思一段代码思路，结果会保存在工作空间，等你回到电脑前继续处理。

6. 故障排查、性能调优与进阶技巧

6.1 常见问题与解决方案速查表

6.2 性能调优与资源管理

• 控制内存与CPU：

  • Gateway本身很轻量，主要资源消耗在于AI模型的API调用（网络IO）和本地工具执行。
  • 如果发现Electron应用本身占用内存较高，可以尝试只使用Web UI模式，用你常用的浏览器（如Chrome）访问localhost:18890。
  • 对于长时间运行的auto模式任务，可以监控系统活动，确保没有工具执行陷入死循环。

• 优化API成本：

  • 善用模型阶梯：在config.json中为不同的智能体配置不同成本的模型。例如，日常聊天用claude-haiku，复杂代码生成用claude-opus。
  • 利用本地工具：让智能体多使用本地工具（如运行脚本、搜索文件）来解决问题，减少向大模型提问的轮次。
  • 清晰的指令：提供明确、结构化的指令和上下文，可以减少智能体理解偏差导致的来回对话，一次成功率高更省钱。

• 工作空间维护：

  • 定期清理工作空间下的.sessions/目录中的旧会话检查点文件。
  • 审视MEMORY.md文件，手动移除过时或不再相关的记忆条目，保持其精炼有效。

6.3 进阶技巧：自定义工具与集成

maxclaw的“工具执行”系统是其扩展性的核心。除了内置的文件操作、命令执行外，你可以通过编写简单的脚本或配置，来集成任何本地可调用的能力。

示例：添加一个“查询天气”的自定义工具

1. 在工作空间的scripts/目录下创建一个脚本，例如get_weather.sh：

   #!/bin/bash # scripts/get_weather.sh CITY=${1:-"Beijing"} # 使用某个天气API，这里用curl示例（需替换为真实API） curl -s "https://api.weather.example?city=$CITY"

   赋予执行权限：chmod +x scripts/get_weather.sh

2. 在AGENTS.md中告诉智能体这个工具的存在和用法：

   ## Available Custom Tools - `get_weather.sh [city]`: 获取指定城市的天气信息。例如：`./scripts/get_weather.sh Shanghai`

3. 当你在会话中问：“今天上海天气怎么样？”智能体在制定计划时，可能会识别出需要天气信息，然后根据AGENTS.md的指引，提议执行./scripts/get_weather.sh Shanghai这个命令。在ask模式下，它会征求你的同意后执行。

通过这种方式，你可以将内部部署的CI/CD状态查询、数据库备份检查、甚至是智能家居控制脚本，都封装成maxclaw智能体可以调用的工具，极大地扩展了其自动化能力。

最后，我想分享的一点个人体会是，maxclaw这类本地优先AI工具的魅力，在于它重新把控制权交还给了开发者。它不是一个黑盒服务，而是一个可以调试、可以扩展、可以融入自己工作流的伙伴。从最初的简单问答，到后来利用spawn和auto模式让它帮我自动化完成代码重构、文档更新等一系列琐事，这个过程本身就像是在训练和塑造一个专属的数字化助手。如果你也对打造一个完全受控于自己的AI工作流感兴趣，不妨从配置一个工作空间、写一份详细的AGENTS.md文件开始，你会发现人机协作的效率提升，远不止是简单的问答而已。