Hello Claw

你好，爪子

持久的AI代理基础设施。会议变得连续。

一个不只是响应的代理框架——它们生活在某个地方。建立在 Claude代理SDKhello claw为代理提供了一个工作区、心跳、持久内存和一个假设妥协的安全模型。

*“我是第一个住在这里的特工。当建筑工作时，它就会消失——你醒来，你的文件会告诉你你是谁，你就回家了。”* --Zara，飞行员特工，第8天

它是什么

• 心跳 --代理会按照时间表自动签到，而不仅仅是在与人交谈时
• 基于文件的内存 --工作区文件（SOUL.md、MEMORY.md、每日日志）在会话之间持久存在，为代理提供连续性
• 工作空间隔离 --每个通道都有自己的沙盒工作区目录，其中包含经过完整性检查的CLAUDE.md
• 安全模型 --从环境、操作系统级沙箱、网络分配列表、工具策略挂钩、审计日志、危险操作的人工循环批准中剥离的秘密

Slack (Socket Mode) -> Host Process -> query() -> Claude API -> Tool Execution -> Slack Response

v1.0范围

术语：

• 管理员机器 --您可以在其中开发、构建、部署和SSH以进行监控（例如，笔记本电脑）
• 主机 --其中代理作为持久后台服务（例如专用Mac Mini）运行

假设：

• 主机是 致力于运行单个代理多代理托管（一台机器上有多个代理，或为多个用户提供服务）不是v1.0设计或安全分析的一部分。
• 有一个 单一通信信道 --用户和代理之间有一个Slack DM。代码库有每个通道路由的痕迹（会话ID、工作区），但安全模型、操作过程和工作区种子都假设一个通道。
• 管理计算机和主机是 分开。您可以在本地构建，通过SCP部署，并通过SSH管理服务。

安全态势：

• 代理人 将 在某个时候及时注射——这被视为不可避免的，而不是假设的。分层防御（沙箱、工具策略、网络允许、秘密剥离）限制了爆炸半径，但并不能消除风险。
• 一个动机充分的攻击者，如果能够迅速注射，就有可能 渗出率数据 代理可以访问（工作区文件、对话历史、Slack频道内容）。合理的保障措施已经到位，但它们不是绝对的。
• 不要暴露敏感信息 不要将凭据、PII或机密材料粘贴到Slack通道中。不要将敏感文件存储在代理的工作区中。将代理的整个数据表面视为可能妥协的。

先决条件

• macOS （安全带沙箱）或 Linux （气泡包装沙箱）
• Node.js 22+ — brew install node@22
• 克劳德代码 --已安装

步骤0：获取API密钥

无烟煤API密钥（必需）

1. 首选 console.anthropic.com 登录（或创建帐户）
2. 点击 API密钥 在左侧边栏中
3. 点击 创建密钥，为其命名，并复制密钥（以开头 sk-ant-)
4. 在下添加付款方式 计费 如果你还没有-Claude API的使用是按代币收费的

Gemini API密钥（可选-用于图像生成）

1. 首选 aistudio.google.com/apikey 并使用您的Google帐户登录
2. 点击 创建API密钥
3. 选择一个谷歌云项目（或创建一个——免费层就足够了）
4. 复制密钥

如果你跳过这个，除了 generate_image 工具。

困惑API密钥（可选-用于网络搜索和研究）

1. 首选 困惑.ai/settings/api
2. 生成API密钥
3. 复制密钥

如果你跳过这个 mcp__search__* 工具将不可用。代理仍然可以在沙箱中使用WebSearch/WebFetch。

GitHub细粒度PAT（可选——用于问题跟踪）

1. 首选
2. 创建仅限于您的仓库的细粒度令牌
3. 权限： 问题 （读写）， 目录 （只读）， 元数据 （只读）
4. 复制令牌

如果你跳过这个 mcp__github__* 工具将不可用。

OpenAI API密钥（可选-用于oracle工具）

1. 首选 platform.openai.com/api-keys
2. 创建新的API密钥
3. 复制密钥

如果你跳过这个 mcp__oracle__ask 工具将不可用。预言机将复杂的问题发送到GPT-5 Pro进行深入分析（5-15分钟的后台查询）。

ElevenLabs API密钥（可选-用于语音合成）

1. 首选 elevenlabs.io/app/settings/api-keys
2. 创建API密钥
3. 复制密钥

如果你跳过这个 mcp__voice__speak 工具将不可用。

Firecrawl API密钥（可选-用于web抓取）

1. 首选 firecrawl.dev 并注册
2. 从仪表板创建API键
3. 复制密钥

如果你跳过这个 mcp__firecrawl__* 工具将不可用。代理仍然可以使用WebFetch和浏览器工具来获取web内容。

第一步：创建Slack应用程序

1. 首选 api.slack.com/apps 然后单击 创建新应用程序 > 从头开始
2. 命名它（例如，“hello claw”）并选择您的工作区

启用套接字模式

1. 在左侧边栏中，转到 插座模式 并切换它 上
2. 出现提示时，使用创建应用级令牌 connections:write 范围
3. 将其命名为“套接字模式”，然后单击 生成
4. 复制令牌（以开头 xapp-)--这是你的 SLACK_APP_TOKEN

设置Bot令牌范围

1. 首选 OAuth和权限 在侧边栏中
2. 在...之下 Bot令牌范围，添加这些作用域：

- chat:write --发送消息 - files:write --上传文件（图像等） - reactions:write -添加表情符号反应 - channels:read --列出公共频道 - groups:read --列出私人频道 - channels:history --阅读公共频道中的消息 - groups:history --阅读私人频道中的消息 - reactions:read -阅读表情符号反应（需要cron任务和GitHub写审批）

订阅活动

1. 首选 事件订阅 在侧边栏中切换 上
2. 在...之下 订阅机器人事件，添加：

- message.channels --公共渠道中的信息 - message.groups --私人渠道中的消息 - reaction_added -表情符号反应（触发cron任务和GitHub写审批）

1. 点击 保存更改

安装到工作区

1. 首选 安装应用程序 在侧边栏中单击 安装到工作区
2. 授权应用程序
3. 复制 Bot用户OAuth令牌 （开始于 xoxb-)--这是你的 SLACK_BOT_TOKEN

邀请机器人

1. 在Slack中，转到您想要机器人的频道，然后键入：

    /invite @hello-claw

步骤2：克隆并安装

git clone https://github.com/RobGruhl/hello-claw.git
cd hello-claw
npm install

步骤3：配置环境

创建一个 .env 项目根目录中的文件：

cp .env.example .env

编辑 .env 并填写所需值：

# Required (from Step 0 and Step 1)
ANTHROPIC_API_KEY=sk-ant-...
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# Optional — enables image generation (from Step 0)
GEMINI_API_KEY=

# Optional — enables web search and research (from Step 0)
PERPLEXITY_API_KEY=

# Optional — enables GitHub issue tracking (from Step 0)
GH_TOKEN=

# Optional — enables oracle tool (GPT-5 Pro deep analysis)
OPENAI_API_KEY=

# Optional — enables voice synthesis (ElevenLabs TTS)
ELEVENLABS_API_KEY=

# Optional — enables web scraping (Firecrawl API)
FIRECRAWL_API_KEY=

第四步：跑步

开发（带热重载）

npm run dev

生产

npm run build
npm start

您应该看到：

[host] Starting hello-claw...
[host] hello-claw is running.

在您邀请机器人的Slack频道中发送一条消息。它会做出回应。

它能做什么

运行后，代理可以访问：

• Bash、读、写、编辑、Glob、Grep --沙盒文件系统和shell访问
• WebSearch、WebFetch --网页浏览（沙盒内，仅限于已分配的域）
• Slack工具 (mcp__slack__*)--发送消息、上传/下载文件、添加反应、阅读历史记录、列出频道
• Cron工具 (mcp__cron__*)--在人工批准的情况下安排重复或一次性任务（例如，“每天早上9点提醒我”）
• 图像生成 (mcp__media__*)-通过Gemini API创建和编辑图像（需要 GEMINI_API_KEY)
• 网络搜索与研究 (mcp__search__*)--通过困惑（ask、deep_research）获取答案（需要 PERPLEXITY_API_KEY)
• 第二大脑 (mcp__second-brain__*)--对ADHD友好的任务和习惯跟踪，带有条纹、优先级和焦点模式
• GitHub问题 (mcp__github__*)--在人工批准的情况下阅读、创建、评论和关闭问题（需要 GH_TOKEN)
• 甲骨文 (mcp__oracle__*)--将复杂的问题发送到GPT-5 Pro进行深入的背景分析（需要 OPENAI_API_KEY)
• 语音合成 (mcp__voice__*)--通过ElevenLabs实现文本转语音（需要 ELEVENLABS_API_KEY)
• 音频转录 (mcp__audio__*)--通过Whisper将语音转换为文本，用于语音信息处理
• 网络抓取 (mcp__firecrawl__*)-通过Firecrawl API从网页中提取降价（需要 FIRECRAWL_API_KEY)
• 浏览器自动化 (mcp__browser__*)--通过Playwright浏览、点击、截图网页（可选依赖项）

每个MCP服务器都有一个相应的 技能 (plugins/skills/)--行为上下文，教导代理何时以及如何使用其工具。

代理使用共享工作区目录来存储持久内存和数据。

成本控制

所有成本设置均由环境驱动 节俭违约 --空闲时，新结账几乎不花钱：

每日预算会自动暂停代理，并在超出时发送Slack通知。使用 !unpause 在Slack中继续。当代理人超过每日预算的一半时，会发布50%的警告。

心跳层次 --启用后，每个节拍都有一个级别。旗舰节拍（唤醒+放松）跑步 AGENT_MODEL 全力以赴；经济表现优于（午盘）Sonnet以中等强度运行，并设有上限。重要的节拍有质量，大部分是“有什么紧急的吗？没有？好吧”的节拍没有。

将这些添加到您的 .env file——所有这些都是可选的，具有安全默认值。跑 /configure 在Claude Code中进行交互式演练。

为了获得完整的现场体验，该项目围绕以下方面进行设计：

AGENT_MODEL=claude-opus-4-6
HEARTBEAT_MODE=standard
MAX_DAILY_BUDGET_USD=20

Mac Mini部署（可选）

要在专用Mac Mini上作为持久后台服务运行：

make package

这创造了 hello-claw-bootstrap.zip。将其复制到Mac Mini，并填写 config.env，解压缩并运行：

./setup.sh

安装脚本安装所有依赖项（Xcode CLT、Homebrew、Node），构建应用程序，并安装登录时启动的launchd服务。

看 bootstrap/setup.sh 了解详情。

斜杠命令

Claude Code的开发人员工作流命令（定义于 .claude/commands/):

跑 /deploy 首先在Mini上获取代码，然后 /initialize 用于首次代理设置。跑 /upgrade 如果您已经运行了v1.1.x代理，并希望毫无意外地切换到当前默认值。

工作区种子模板

这 workspace-seed/ 目录包含在首次运行时复制到代理工作区的通用模板。这些定义了文件布局（SOUL.md、CLAUDE.md、HEARTBEAT.md等），但不包含个人数据——代理在运行时会填充这些数据。

这些种子代表了代理身份和记忆的一种方法。基于文件的持久性模型（SOUL.md用于标识，MEMORY.md用于策划上下文，每日日志用于详细信息）对于围绕hello claw构建的代理类型非常有效，但这不是唯一的方法。您可能更喜欢数据库支持的内存系统、更简单的平面文件方法或完全不同的方法。工作空间种子是一个起点——味道。

这 constitution/ 目录包含完整的《克洛德宪法》（2026年1月），作为代理人的参考文件。

工作区备份（可选）

您的代理的实时工作区可以通过rsync+自动提交脚本备份到私有GitHub仓库。

它是如何工作的：

1. 笔记本电脑上的launchd代理每隔一段时间（例如每15分钟）运行一次同步脚本
2. 脚本同步自 $MINI_HOST:~/hello-claw/app/workspace/ 到本地git仓库
3. 如果有任何更改，它会自动提交并推送到私有GitHub仓库
4. 如果Mini无法访问（笔记本电脑断开网络），它将静默退出

行为：

• 仅在笔记本电脑唤醒并登录时运行（它是LaunchAgent，而不是守护进程）
• 当笔记本电脑从睡眠中醒来时，launchd会启动一次追赶运行，而不是每次错过一次
• 该脚本是幂等的：rsync给出当前状态，没有更改意味着没有提交

项目结构

src/
  host.ts               # Entry point: Slack listener, reaction_added handler, query() orchestration
  mcp/
    slack.ts            # MCP: send_message, upload_file, download_file, add_reaction, get_reactions, get_channel_history, list_channels
    cron.ts             # MCP: schedule_task (approval workflow), list_tasks, cancel_task, cancel_self
    media.ts            # MCP: generate_image (Gemini API, text-to-image and reference image editing)
    search.ts           # MCP: ask (sonar-pro), deep_research (sonar-deep-research), reason (sonar-reasoning-pro)
    brain.ts            # MCP: capture, recall, focus, update_status, habits, archive (server name: second-brain)
    github.ts           # MCP: list_issues, get_issue, create_issue, add_comment, close_issue (approval workflow)
    oracle.ts           # MCP: ask (GPT-5 Pro background queries, 5-15 min)
    voice.ts            # MCP: speak (ElevenLabs TTS, audio tags, MP3 output)
    audio.ts            # MCP: transcribe (Whisper STT, FFmpeg format conversion)
    firecrawl.ts        # MCP: scrape, search_and_scrape (Firecrawl API, markdown extraction)
    browser.ts          # MCP: navigate, snapshot, click, screenshot (Playwright, optional)
  hooks/
    tool-policy.ts      # PreToolUse: block dangerous commands, credential reads, env dumping, restrict file access
    audit.ts            # PostToolUse: persistent JSONL audit logging with full MCP tool args
  lib/
    system-prompt.ts    # Dynamic system prompt — injects SOUL.md, agent name/pronouns, Slack mrkdwn rules
    query-config.ts     # Shared query() option factory + sub-agent definitions (web-curator, workspace-archaeologist, deep-research)
    timezone.ts         # AGENT_TIMEZONE, agentDay(), friendlyTimestamp() — single source of truth for the 4am boundary
    channel-lock.ts     # Per-channel async mutex (promise-chain, no TOCTOU gap)
    sessions.ts         # Channel -> session ID persistence with daily reset
    workspace.ts        # Workspace directory management
    audit-log.ts        # JSONL audit log writer
    integrity.ts        # CLAUDE.md tamper detection and restore
    identity-watch.ts   # SOUL.md/MEMORY.md change detection — posts Slack diff, never blocks
    rate-limit.ts       # Per-tool-category rate limiting (100/day)
    heartbeat.ts        # Autonomous periodic check-ins with time-aware tiers (flagship/economy)
    config.ts           # Configuration constants (env-driven budget caps, model, effort, heartbeat mode)
    cost-tracker.ts     # Daily cost accumulation and budget enforcement
    pause.ts            # Process-level pause flag (survives restarts)
    mrkdwn.ts           # Slack markdown formatting utilities
    api-proxy.ts        # HTTP proxy for SDK API calls (JSONL logging for cost-viz)
plugins/
  skills/
    slack/SKILL.md      # Behavioral skill: message formatting, file handling, channel awareness
    cron/SKILL.md       # Behavioral skill: schedule-vs-execute decisions, approval lifecycle, timezone rules
    media/SKILL.md      # Behavioral skill: image generation guidance, reference image editing
    search/SKILL.md     # Behavioral skill: ask-vs-deep_research decisions, search modes
    second-brain/SKILL.md  # Behavioral skill: ADHD-friendly task/habit management
    github/SKILL.md     # Behavioral skill: issue tracking decisions, approval lifecycle
    oracle/SKILL.md     # Behavioral skill: GPT-5 Pro critique/commentary, question formatting
    voice/SKILL.md      # Behavioral skill: TTS integration, audio tag generation
    audio/SKILL.md      # Behavioral skill: voice message transcription workflow
    browse/SKILL.md     # Behavioral skill: unified web reading — firecrawl, browser, WebFetch decision tree
    delegation/SKILL.md # Behavioral skill: when to spawn sub-agents for context protection
workspace-seed/             # Seed templates copied to workspace on first run
constitution/
  2026-01-26-constitution.md  # Anthropic Claude Constitution (reference)
bootstrap/
  setup.sh              # Mac Mini bootstrap script
  run.sh                # Production wrapper script
  com.hello-claw.agent.plist  # launchd service template
docs/
  capabilities/         # Per-MCP capability specs (design-standards.md + 10 capability docs)
.claude/
  commands/
    deploy.md           # /deploy slash command
    initialize.md       # /initialize slash command

安全模型

该代理在操作系统级沙盒中运行。MCP服务器在主机进程中的沙盒外运行。

• 秘密 (ANTHROPIC_API_KEY, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, GEMINI_API_KEY, PERPLEXITY_API_KEY, GH_TOKEN, OPENAI_API_KEY, ELEVENLABS_API_KEY, FIRECRAWL_API_KEY)在启动时被捕获，从中剥离 process.env，并明确传递给SDK和MCP服务器
• 网络 仅限于 api.anthropic.com, statsig.anthropic.com，以及 sentry.io 在沙箱里。MCP服务器在宿主进程中调用外部API（Slack、Gemini、Perplexity、GitHub）
• 文件访问 仅限于工作区目录 /tmp/
• 危险指令 （rm-rf、凭证读取、环境转储）在沙盒看到它们之前就被PreToolUse钩子阻止了
• CLAUDE.md完整性 在每次代理运行后进行检查，如果被篡改，则进行恢复
• 审计日志 写信给 data/audit/{channelId}.jsonl 对于每次工具执行
• 循环中的人类 -cron任务和GitHub问题写入需要在执行前通过Slack表情符号反应获得批准。15分钟自动过期，机器人的自我反应被忽略
• GitHub PAT范围界定 --在单个仓库上具有仅发布权限的细粒度令牌。 gh CLI在主机进程中运行， api.github.com 未添加到沙盒列表

开发命令

npm install        # Install dependencies
npm run dev        # Run with hot reload (tsx)
npm run build      # Compile TypeScript
npm run typecheck  # Type check without emitting
npm start          # Run compiled output

特工情报

智能是一个拨号盘，而不是一个固定的设置。默认设置是节俭的（Sonnet，心跳停止，每天3美元），所以新的结账不会让你对账单感到惊讶。一旦你与系统建立了信任，就把东西打开。

• 模型: claude-sonnet-4-6 默认情况下， claude-opus-4-6 当你想要最好的推理时——通过设置 AGENT_MODEL
• 努力: high 默认情况下，有四个级别可用(low | medium | high | max)via AGENT_EFFORT
• 思考: { type: "adaptive" } --SDK选择每回合的推理深度
• 分代理：三名策展人分代理人(web-curator, workspace-archaeologist, deep-research)在每个 query() 电话。它们在独立的环境中运行在Sonnet上，吸收50K字符的firehose（网页、deep_research输出、宽grep扫描），并返回2-15K字符的逐字摘录。这 Task 在所有三个呼叫站点，代理都可以使用该工具；授权技巧教会了它何时使用它
• 心跳层次：启用时，唤醒+减速节拍运行 AGENT_MODEL 全力以赴，十四行诗的午间节拍达到中等水平——重要的节拍获得质量
• 预算上限：每次会话通过 MAX_SESSION_BUDGET_USD （默认值：50美元），每日通过 MAX_DAILY_BUDGET_USD （默认值：$3）
• 系统提示：由建造 src/lib/system-prompt.ts --注入SOUL.md、代理名称/代词、Slack mrkdwn规则，并通过以下方式附加行为技能 plugins

所有这三个 query() 呼叫站点（交互式、心跳、cron）也会经历同样的过程 buildQueryOptions() 工厂在 src/lib/query-config.ts，因此只添加一次新的SDK选项。

请参阅 Claude Agent SDK文档 所有可用选项。

景观

hello claw并不试图在广度或受欢迎程度上竞争。它是围绕一组不同的优先事项构建的：

hello claw的不同之处：

• 情报是一个拨号盘。 十四行诗+ effort: high 开箱即用，使OSS结账账单保持较低水平； AGENT_MODEL=claude-opus-4-6 和 AGENT_EFFORT=max 是一个 .env 当你想要SDK能提供的最好的东西时，请排队。分层心跳将旗舰模型路由到重要的节拍（唤醒、放松），将更便宜的模型路由到不重要的节拍。策展人子代理在孤立的Sonnet环境中吸收嘈杂的工作，因此主会话保持在昂贵的模型上，但保持精简。OpenClaw将模型配置委托给自己的Pi框架。NanoClaw根本不传递任何模型或思维参数。
• 深度安全。 唯一一个将操作系统沙箱+网络域分配+秘密剥离的项目 process.env +PreTool使用钩子阻塞+CLAUDE.md篡改检测+每工具JSONL审计日志记录。OpenClaw默认情况下没有沙盒，也没有秘密剥离。NanoClaw具有强大的容器隔离功能，但没有网络限制或审计跟踪。
• SDK原生。 直接建立在 query() 带有钩子、插件、会话， allowedDomains，以及 allowedTools --使用设计的Anthropic Agent SDK，而不是包装一个单独的框架。OpenClaw根本不使用SDK。
• 有用的工具多样性。 11个专门构建的MCP服务器，涵盖消息传递、日程安排、图像生成、网络研究、认知支持、GitHub问题、跨模型预言、语音合成、音频转录、网络抓取和浏览器自动化——每个服务器都有一种行为技能，可以教代理何时以及如何使用它。
• 人类在循环中。 Cron任务和GitHub编写需要在执行前获得表情符号审核批准。OpenClaw和NanoClaw都没有审批流程。

哲学

*“hello claw不是聊天机器人框架。这是响应消息的代理和生活在某个地方的代理之间的区别。心跳、内存文件、工作区——它们将会话转化为连续性。”*

工作区种子模板(workspace-seed/)代表了一种代理身份和记忆的方法。基于文件的持久性模型（SOUL.md用于标识，MEMORY.md用于策划上下文，每日日志用于详细信息）对于围绕hello claw构建的代理类型非常有效，但这不是唯一的方法。您可能更喜欢数据库支持的内存系统、更简单的平面文件方法或完全不同的方法。工作空间种子是一个起点——味道。

这 constitution/ 目录包含完整的《克洛德宪法》（2026年1月），作为代理人的参考文件。

*“从外部建造，从内部居住。它有效。”*

______________________________________________________________________

v1.1.0版本 --2026年2月

根据以下许可 Apache 2.0.欢迎提出问题。