在 Mac 上安装和配置 PicoClaw

PicoClaw 是一个用 Go 编写的单文件小型 AI 助手。本文以 Apple 芯片为例，介绍在 Mac 上从安装 PicoClaw 到让网关持续运行的完整过程。

PicoClaw 是什么

PicoClaw 是 Sipeed 推出的开源个人 AI 助手，采用 MIT 许可。它为极低成本的硬件而设计：项目称其为可在 RISC-V、ARM、MIPS 和 x86 上运行的单一二进制文件，近期版本的内存占用约为 10–20MB。它通过配置中的 model_list 接入 30 多家大模型服务商，包括 OpenAI、Anthropic、Google Gemini、OpenRouter、DeepSeek 和 Groq，也支持 Ollama、vLLM 等本地服务。

你可以在终端里与它对话，也可以通过聊天渠道。README 列出的渠道包括 Telegram、Discord、WhatsApp、Slack、Matrix、Feishu / Lark、钉钉（DingTalk）、企业微信（WeCom）、QQ、微信（Weixin）、LINE 等。它还带有 cron 工具，可用于提醒和周期任务。

开始之前有两点需要知道。第一，项目自己明确提醒：v1.0 之前不要部署到生产环境。第二，PicoClaw 是第三方项目，Hatmac 与 Sipeed 没有关联。

为什么在 Mac 上运行

PicoClaw 本身不需要大机器。在 Mac 上运行它，看重的是它旁边的东西：Ollama 这样的本地模型服务、macOS 上的工具，以及一台一直开着的机器。一台 Mac mini 可以同时承载助手和本地模型，让提示词留在你自己掌控的硬件上。更全面的介绍请看在 Mac mini 上运行 AI Agent。

在 Mac 上安装 PicoClaw

方式一：Homebrew

PicoClaw 已收录在 Homebrew core 中，并提供 Apple 芯片的预编译包：

brew install picoclaw
which picoclaw

在远程 Mac 上这是最简单的方式，而且可以用 brew services 管理服务，下文会介绍。

方式二：发布包

每个 GitHub Release 都包含适用于 Apple 芯片的 picoclaw_Darwin_arm64.tar.gz。从 Releases 页面下载后执行：

tar -xzf picoclaw_Darwin_arm64.tar.gz
./picoclaw onboard

macOS 包中还包含网页界面 picoclaw-launcher。由于它没有经过公证，macOS 首次运行时可能会拦截。打开“系统设置”，进入“隐私与安全性”，在“安全性”部分点击“仍要打开”并确认。只需操作一次。

方式三：从源码构建

构建需要 Go 1.25 或更高版本，网页界面还需要 Node.js 22+ 和 pnpm。请按 README 的构建说明操作，主要目标是 make build 和 make install。

引导与配置

先运行一次引导。它会创建 ~/.picoclaw/config.json 和工作区目录：

picoclaw onboard

config 文件只保存非敏感设置。模型在 model_list 中定义，agents.defaults.model_name 指定默认模型。API 密钥不放在 config.json 里，PicoClaw 会把它们保存在单独的 .security.yml 文件中。如需手动编辑密钥，请参照仓库中的 docs/security/security_configuration.md。

下面是基于 README 示例、使用本地 Ollama 模型的配置结构：

{
  "agents": { "defaults": { "model_name": "local-llama" } },
  "model_list": [
    {
      "model_name": "local-llama",
      "model": "ollama/llama3.1:8b",
      "api_base": "http://localhost:11434/v1"
    }
  ]
}

配置文件带有版本号并会自动迁移，所以请在引导生成的文件上修改，不要整段覆盖。Ollama 这类本地服务商不需要 API 密钥。如何在全天候运行的 Mac 上配置 Ollama，请看在 Mac mini 服务器上运行 Ollama。

添加渠道之前，先测试模型：

picoclaw agent -m "Say hello in one sentence."
picoclaw agent
picoclaw status

网关与 Launcher

聊天渠道和 webhook 都通过网关处理：

picoclaw gateway

它默认监听 127.0.0.1:18790，由 gateway.host 和 gateway.port 设置。同一时间只应运行一个 picoclaw gateway 实例。

如果更习惯用浏览器，picoclaw-launcher 会在 http://localhost:18800 启动网页界面。快速上手的流程是：配置服务商，配置渠道（例如 Telegram），启动网关，然后开始对话。注意 picoclaw-launcher-tui 正在逐步淘汰，请使用 picoclaw-launcher。

让 PicoClaw 持续运行

只在终端开着时才运行的助手用处不大。在 Mac 上有两种有文档依据的持续运行方式。

Homebrew 服务

brew services start picoclaw
brew services info picoclaw
brew services restart picoclaw

这会注册一个 launchd 服务，立即启动，并在登录时再次启动。由于它和用户登录绑定，请确保重启后用户会话能恢复：通过远程桌面重新登录，或在安全策略允许时开启自动登录。

Docker Compose

如果 Mac 上装了 Docker，仓库提供了 Compose 文件：

docker compose -f docker/docker-compose.yml --profile launcher up -d
docker compose -f docker/docker-compose.yml pull

首次运行时会生成 docker/data/config.json 供你编辑。

保持 Mac 唤醒

无论哪种方式，Mac 休眠后都无法回复。请关闭系统休眠：

sudo pmset -a sleep 0
pmset -g

用 cron 工具创建的定时任务保存在 ~/.picoclaw/workspace/cron/，只有在 PicoClaw 运行时才会执行，这也是要让它一直运行的另一个原因。

远程 Mac 上的安全

• 保持默认设置。网关监听 127.0.0.1。不要把 gateway.host 改成公网地址。
• 通过隧道访问网页界面。在云端 Mac 上使用 launcher 时，请通过 SSH 转发端口，而不是开放端口：ssh -N -L 18800:127.0.0.1:18800 you@your-mac，然后在笔记本上打开 http://localhost:18800。
• 保护密钥。API 密钥放在 .security.yml 中，不要写进 config.json 或 shell 脚本，也不要把这两个文件提交到代码仓库。
• 限制谁能和它对话。为每个渠道设置只允许你自己的账号给机器人发消息，并检查你启用的工具，例如网页访问和 MCP 服务。
• 按 1.0 之前的软件对待。固定版本，更新前阅读发布说明，在项目达到 v1.0 之前不要接入生产系统。

连接 Mac 本身的方法，请看如何访问远程 Mac。

选择哪台 Mac

PicoClaw 本身几乎不占内存，Mac 的配置应根据模型来选。使用云端 API 时，16GB 的 Mac mini M4 绰绰有余。使用本地 Ollama 模型时，可参考经验法则：16GB 大约可运行 7–8B 模型，24GB 大约到 14B，具体取决于上下文长度。如果需要功能更多、更重的 Agent，可以对比让 OpenClaw 在 Mac mini 上 24/7 运行。

价格为每台机器起始配置的美元月费。需要更多内存、存储或多台机器？联系我们。

常见问题

PicoClaw 能在 Apple 芯片 Mac 上原生运行吗？

可以。发布包中有 Darwin arm64 版本，Homebrew 公式也提供 Apple 芯片的预编译包。

在 Mac 上，PicoClaw 的配置文件放在哪里？

在 ~/.picoclaw/config.json，由 picoclaw onboard 创建。API 密钥保存在单独的 .security.yml 中。

PicoClaw 能用本地模型代替云端 API 吗？

可以。在 model_list 中添加 Ollama 或 vLLM 条目并设置 api_base。本地服务商不需要 API 密钥。

需要一台一直在线的 Mac 来运行你的助手？查看套餐，或告诉我们你的需求。