Pipiclaw

Pipiclaw 是一个 AI 助手运行时（AI assistant runtime），以 pi-coding-agent 为核心，补齐了作为工作助手长期使用时最需要的几层能力：钉钉接入、AI Card 过程展示、子代理、分层记忆、定时事件，以及按会话通道持久化的工作区（workspace）。

如果你希望 AI 助手不只是聊天，而是能在钉钉里持续工作、保留上下文、执行任务，并且实时告知你它正在做什么，那么 Pipiclaw 就是你需要的。

npm package: @oyasmi/pipiclaw

文档入口：

• 配置手册：docs/configuration.md
• 事件与子代理使用指南：docs/events-and-sub-agents.md
• 部署与运维指南：docs/deployment-and-operations.md
• 安全文档：docs/security.md

功能特性（Features）

• 原生支持钉钉 Stream Mode，不需要消息中转服务，不需要公网IP
• 支持 AI Card 过程展示，思考、工具执行和状态更新可以持续流式呈现
• 支持 /help、/new、/compact、/session、/model
• 忙碌时可继续接收 /steer、/followup、/stop
• 按工作区 / 会话通道（workspace / channel）分层管理 SOUL.md、AGENTS.md、SESSION.md、MEMORY.md、HISTORY.md
• 支持预定义子代理（sub-agent）和临时内联子代理（inline sub-agent）
• 支持立即、单次、周期三类事件调度
• 支持自定义模型提供方（provider）和模型（model）配置
• 内建 web_search / web_fetch，支持联网搜索与网页抓取
• 内置工具层安全防护：bash 命令守卫、文件路径守卫、敏感路径拒绝、阻断审计日志

安全说明（Security）

Pipiclaw 当前已经内置一轮工具层安全增强：

• bash 会拦截明显高风险命令
• read / write / edit / attach 会做统一路径检查
• 默认允许访问用户主目录中的普通工作文件，但会拒绝常见凭据、私钥、浏览器资料、系统敏感文件等位置
• 可通过 ~/.pi/pipiclaw/security.json 做实例级策略调整

如果你要了解默认策略、已知边界、推荐模板和完整配置示例，请直接看：

• docs/security.md

快速开始（Quickstart）

从零开始，让 Pipiclaw 在你的钉钉里成功回复第一条消息。可以直接让Agent帮你完成。如果你希望自己逐步操作，再看后面的“自己动手安装”。

给 AI Agent 的安装说明（For AI Agent）

可以让 AI Agent 直接帮你完成安装、初始化、配置和启动，把下面整段文字复制给你常用的 AI Agent （如 Claude Code、Codex、OpenCode 等）：

请帮我在这台机器上安装并初始化 Pipiclaw，并尽量把它配置到“可以开始使用”的状态。按下面要求执行：

1. 先检查 Node.js 是否可用，版本必须 >= 22。
   - 如果未安装，或版本低于 22，不要继续安装 Pipiclaw，直接告诉我需要先安装或切换到 Node.js 22+。

2. 安装 Pipiclaw：
   - 优先执行：npm install -g @oyasmi/pipiclaw
   - 如果全局安装因为权限失败，不要默认使用 sudo。
   - 先把报错告诉我，再询问我希望怎么处理。

3. 安装完成后，执行一次 pipiclaw，让它初始化默认目录：
   - ~/.pi/pipiclaw/
   - ~/.pi/pipiclaw/workspace/

4. 继续帮我完成基础配置，但先逐项询问我是否愿意现在提供这些信息：
   - 钉钉应用的 clientId
   - 钉钉应用的 clientSecret
   - AI Card 的 cardTemplateId
   - 模型接入方式：Anthropic，或自定义 provider

5. 关于钉钉配置：
   - AI Card 是推荐配置，不是可有可无的装饰。正常使用时建议配上。
   - 如果我愿意提供 clientId、clientSecret、cardTemplateId，就直接帮我写入 ~/.pi/pipiclaw/channel.json
   - robotCode 可以先留空
   - allowFrom 可以先设为 []
   - 如果我暂时不提供 cardTemplateId，也可以先留空，但最后要明确提醒我后续补上
   - 不要把 any your-* placeholder 保留在最终文件里

6. 关于模型配置：
   - 先问我使用哪种方式：
     - Anthropic 默认模型
     - 自定义 provider
   - 如果我选择 Anthropic，再询问我是否愿意现在提供 ANTHROPIC_API_KEY
     - 如果我提供，就按我当前环境和你的能力，帮我配置到可用
     - 如果我不提供，就不要编造值；保留默认空 models.json，并在最后告诉我需要自己补 ~/.pi/pipiclaw/auth.json 或环境变量
   - 如果我选择自定义 provider，至少询问这些信息：
     - provider 名称
     - baseUrl
     - api 类型
     - apiKey
     - 至少一个 model id
   - 如果我提供了这些值，就帮我写好 ~/.pi/pipiclaw/models.json
   - 如果我不提供，就不要编造值；最后明确告诉我需要自己补 ~/.pi/pipiclaw/models.json
   - 如果服务是 OpenAI-compatible，优先使用 openai-completions，并默认加上 compat：
     - supportsDeveloperRole: false
     - supportsReasoningEffort: false

7. 配置完成后，分两种情况处理：
   - 如果还缺关键配置，就不要假装已经可用：
     - 明确列出还缺什么
     - 明确指出应该修改哪个文件
     - 提醒我补完后再运行 pipiclaw
   - 如果关键参数已经齐全，不要只告诉我如何启动；先询问我是否需要你现在直接帮我启动 Pipiclaw
     - 如果我同意，你就直接启动 pipiclaw
     - 启动后要检查输出，告诉我是启动成功，还是遇到了问题
     - 如果遇到问题，要把问题类型、关键信息和下一步解决建议说清楚
     - 如果启动成功，要提醒我去钉钉里先发送 /model 验证模型是否可见，再发送一条普通消息做首次验证
     - 如果我不同意立即启动，就告诉我后续该如何手动启动

8. 如果我选择“先安装，稍后自己改配置”，你就完成安装和初始化即可，但最后必须明确告诉我下一步至少要改这些文件中的哪些：
   - ~/.pi/pipiclaw/channel.json
   - ~/.pi/pipiclaw/auth.json
   - ~/.pi/pipiclaw/models.json
   - ~/.pi/pipiclaw/settings.json（如果需要固定默认模型）

9. 整个过程中不要假装已经成功。
   - 做过的操作和写过的文件要明确告诉我
   - 如果某一步无法继续，要直接说明卡在哪里

自己动手安装（For Human）

如果你希望自己逐步完成安装和配置，可以按下面步骤操作。

1. 环境要求（Requirements）

• Node.js >= 22
• 一个可用的钉钉企业内部应用
• 至少一种可用的模型接入方式
  • 直接使用 Anthropic 默认模型
  • 或在 models.json 中配置自定义模型提供方（provider）

Windows 补充说明：

• Pipiclaw 的工具执行层默认按 POSIX shell 语义工作
• 在 Windows host 模式下，建议安装 Git Bash，并确保 bash 可在 PATH 中找到
• 如果 bash 不在 PATH 中，可以设置 PIPICLAW_SHELL 指向具体可执行文件，例如 C:\Program Files\Git\bin\bash.exe
• 如果你不想依赖本机 shell 环境，推荐直接使用 Docker sandbox

2. 安装（Install）

npm install -g @oyasmi/pipiclaw

3. 初始化（Initialize）

第一次运行会自动初始化配置目录：

pipiclaw

程序会创建：

~/.pi/pipiclaw/
├── channel.json
├── auth.json
├── models.json
├── settings.json
├── tools.json
└── workspace/
    ├── SOUL.md
    ├── AGENTS.md
    ├── MEMORY.md
    ├── ENVIRONMENT.md
    ├── events/
    ├── skills/
    └── sub-agents/

默认 app home 是 ~/.pi/pipiclaw/。如果你希望把 Pipiclaw 的所有配置和运行文件放到别处，可以在启动前设置：

export PIPICLAW_HOME=/your/custom/pipiclaw-home

设置后，channel.json、auth.json、models.json、settings.json、tools.json 和整个 workspace/ 都会改为从这个目录读取和写入。

如果你在 Windows host 模式下运行，并且 bash 不在 PATH 中，也可以一并设置：

$env:PIPICLAW_SHELL = "C:\Program Files\Git\bin\bash.exe"

如果 channel.json 仍然是初始化模板，程序会提示你补全配置后再启动。这是正常行为。

4. 创建钉钉应用（Create a DingTalk App）

在 钉钉开放平台 创建企业内部应用，并完成下面几项：

1. 创建应用，获取 Client ID 和 Client Secret
2. 开启机器人能力
3. 启用 Stream Mode
4. 建议一并创建 AI Card 模板并获取 Card Template ID

5. 填写 channel.json（Fill channel.json）

编辑 ~/.pi/pipiclaw/channel.json：

{
  "clientId": "your-dingtalk-client-id",
  "clientSecret": "your-dingtalk-client-secret",
  "robotCode": "",
  "cardTemplateId": "",
  "cardTemplateKey": "content",
  "allowFrom": []
}

为了让第一轮接入更稳，上面的示例先把 cardTemplateId 留空；如果你已经准备好 AI Card 模板，推荐直接填入真实值。

最少只需要：

• clientId
• clientSecret

常见可选项：

• robotCode 留空时会回退到 clientId
• cardTemplateId 建议配置；留空时表示暂不启用 AI Card
• allowFrom 设为 [] 或删除时表示允许所有人

推荐把 AI Card 一起配上，这样在钉钉里能直接看到过程更新。只有在排查接入链路时，才建议临时把 cardTemplateId 留空。

6. 配置模型（Configure Models）

Pipiclaw 启动后要想真正生成回复，还需要有可用模型。这里通常有两种接入方式。

方案 A：使用内置 Anthropic 默认模型（Option A: Use the Built-in Anthropic Default）

如果你直接使用 Anthropic，models.json 可以保持默认内容：

{
  "providers": {}
}

然后提供 Anthropic 凭据即可。最简单的是环境变量：

export ANTHROPIC_API_KEY=sk-ant-...

也可以写到 ~/.pi/pipiclaw/auth.json：

{
  "anthropic": {
    "type": "api_key",
    "key": "sk-ant-..."
  }
}

方案 B：添加自定义模型提供方（Option B: Add a Custom Provider）

如果你使用的是 OpenAI-compatible 网关、代理、自建服务或聚合平台，可以在 ~/.pi/pipiclaw/models.json 里添加一个自定义模型提供方（provider）。

一个可以直接改名替换后使用的最小示例：

{
  "providers": {
    "my-gateway": {
      "baseUrl": "https://llm.example.com/v1",
      "api": "openai-completions",
      "apiKey": "your-api-key",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "gpt-4.1"
        }
      ]
    }
  }
}

这个例子里最关键的四项是：

• baseUrl
• api
• apiKey
• models

说明：

• apiKey 可以直接写真实 key
• 也可以写环境变量名，或 !command
• 很多 OpenAI-compatible 服务不支持 developer role / reasoning_effort 如果遇到请求兼容性问题，先保留上面的 compat

如果你不想把凭据直接写进 models.json，也可以改成同名模型提供方（provider）的 auth.json 配置，例如：

{
  "my-gateway": {
    "type": "api_key",
    "key": "your-api-key"
  }
}

同时把 models.json 中的 apiKey 改成同一个值，或者改成环境变量名。完整配置手册见 docs/configuration.md。

7. 可选：设置默认模型（Optional: Set a Default Model）

如果你希望固定默认模型，可以编辑 ~/.pi/pipiclaw/settings.json：

{
  "defaultProvider": "my-gateway",
  "defaultModel": "gpt-4.1"
}

如果不设置，Pipiclaw 会使用当前可用模型列表里的第一个。

8. 启动 Pipiclaw（Start Pipiclaw）

pipiclaw

9. 可选：配置内建 Web 工具（Optional: Configure Built-in Web Tools）

如果你希望助手直接使用 web_search / web_fetch，可以编辑 ~/.pi/pipiclaw/tools.json。

第一次启动时，Pipiclaw 会自动生成一份默认关闭的 tools.json 模板。它已经带了 Brave 的示例配置，以及可选代理示例，方便你直接改成可用状态：

{
  "tools": {
    "web": {
      "enable": false,
      "proxy": null,
      "search": {
        "provider": "brave",
        "apiKey": ""
      }
    }
  },
  "_examples": {
    "proxy": "http://127.0.0.1:7890",
    "apiKey": "BSA..."
  }
}

最常见的启用方式是：

1. 把 tools.web.enable 改成 true
2. 把 tools.web.search.apiKey 改成你自己的 Brave key
3. 如果需要代理，再把 _examples.proxy 的值抄到 tools.web.proxy

未设置 tools.web.proxy 时，web 工具会回退到标准环境变量：HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY。DingTalk runtime 也会尊重同一套环境变量。

10. 在钉钉中验证（Verify in DingTalk）

建议先给机器人发送：

/model

确认当前可见模型和默认模型都符合预期后，再发送一条普通消息，例如：

• /model 会列出当前模型和可用模型
• 切换时支持精确的 provider/modelId、精确的 modelId，以及能唯一命中的片段字符串，例如 /model turbo

请介绍一下你自己，并说明你现在能做什么

如果一切正常：

• 如果已经配置 AI Card，你会在钉钉里看到过程更新；这也是推荐的使用方式
• 如果暂时没有配置 AI Card，机器人会直接发送普通消息
• Pipiclaw 会在本地创建对应的会话通道目录
• 后续会话会复用该会话通道的工作区（workspace）与记忆文件

配置（Configuration）

配置与使用相关的文档建议按下面顺序阅读：

配置文件（Config Files）

默认根目录是 ~/.pi/pipiclaw/；如果设置了 PIPICLAW_HOME，下面这些路径都会切换到该目录下。

环境变量（Environment Variables）

命令（Commands）

Pipiclaw 有两层命令。

传输层命令（Transport Commands）

这些命令由钉钉运行时（DingTalk runtime）直接处理：

忙碌时，普通消息默认等价于 /steer <message>。

会话层命令（Session Commands）

这些命令由 AgentSession 扩展命令（extension command）立即执行，不会作为普通 prompt 发给模型：

/model 的匹配顺序是：

1. 精确匹配 provider/modelId
2. 精确匹配 modelId
3. 对完整的 provider/modelId 做子字符串匹配

只有当片段字符串能唯一命中一个可用模型时才会切换。例如：

• /model qwen
• /model k2.5
• /model turbo
• /model zpai

像 /model glm5 这种不构成子字符串的输入不会命中。

工作区结构（Workspace Layout）

Pipiclaw 的核心不是一个临时机器人实例，而是一组长期存在的工作区（workspace）文件。

~/.pi/pipiclaw/
├── channel.json
├── auth.json
├── models.json
├── settings.json
└── workspace/
    ├── SOUL.md
    ├── AGENTS.md
    ├── MEMORY.md
    ├── ENVIRONMENT.md
    ├── events/
    ├── skills/
    ├── sub-agents/
    ├── dm_{userId}/
    │   ├── SESSION.md
    │   ├── MEMORY.md
    │   ├── HISTORY.md
    │   ├── .channel-meta.json
    │   ├── context.jsonl
    │   ├── log.jsonl
    │   └── subagent-runs.jsonl
    └── group_{conversationId}/
        └── ...

其中：

• SOUL.md 定义助手身份、语气和回复风格
• AGENTS.md 定义工作规则和行为约束
• SESSION.md 当前工作态
• MEMORY.md 稳定事实、决策和偏好
• HISTORY.md 更早上下文的摘要

记忆模型（Memory Model）

Pipiclaw 不会把所有历史对话无上限地塞进 prompt，而是按层管理：

• workspace/MEMORY.md 工作区级稳定背景
• <channel>/SESSION.md 当前任务和短期上下文
• <channel>/MEMORY.md 会话通道级 durable facts、decisions、preferences
• <channel>/HISTORY.md 更早会话的摘要历史

运行时主要做两件事：

• relevant recall 按当前请求从 SESSION.md / MEMORY.md / HISTORY.md 里挑少量相关片段注入当前 prompt
• consolidation 在 compaction 或 session trimming 前刷新 SESSION.md，并把值得保留的信息沉淀到 MEMORY.md / HISTORY.md

事件与子代理（Events and Sub-Agents）

workspace/events/ 和 workspace/sub-agents/ 是 Pipiclaw 非常重要的两类长期能力：

• 定时事件适合做提醒、巡检、定期回顾和固定流程触发
• 预定义子代理适合把 reviewer、researcher、planner 这类角色沉淀为可复用能力

这两部分更接近“日常使用”而不是基础配置，单独整理在 docs/events-and-sub-agents.md。

故障排查（Troubleshooting）

pipiclaw 首次启动即退出（pipiclaw Exits on First Run）

通常是因为 channel.json 仍然保留了初始化占位值。

优先检查这些字段：

• clientId
• clientSecret
• robotCode
• cardTemplateId
• allowFrom

第一次接通时，最省事的做法是：

• 把 robotCode 设为空字符串
• 把 cardTemplateId 设为空字符串
• 把 allowFrom 设为 []

确认链路正常后，建议尽快把 AI Card 配上。

机器人已启动，但第一次模型调用失败（The Bot Starts but the First Model Call Fails）

优先检查：

• 如果 models.json 为空，是否已经提供可用的 Anthropic 凭据
• 如果使用自定义模型提供方，models.json 是否包含 baseUrl、api、apiKey、models
• auth.json 是否使用了对象格式，而不是直接写成字符串
• 如果是 OpenAI-compatible 服务，是否需要：
  • "supportsDeveloperRole": false
  • "supportsReasoningEffort": false
• 给机器人发送 /model，确认当前可见模型和默认模型是否正确；如需切换，也可以用唯一命中的片段，例如 /model turbo

机器人能收到消息，但没有回复（The Bot Receives Messages but Does Not Reply）

优先检查：

• 模型认证是否可用
• models.json 是否声明了你要使用的模型提供方 / 模型
• allowFrom 是否把你的账号挡住了
• 钉钉机器人 Stream Mode 是否已开启
• 如果配置了 cardTemplateId，该模板是否有效

如果只是想先验证链路，可以临时把 cardTemplateId 留空；正常使用时仍然建议启用 AI Card。

需要查看精确提示词（Need to Inspect the Exact Prompt）

设置：

export PIPICLAW_DEBUG=1

之后运行时会在对应的会话通道目录下写出 last_prompt.json。

开发（Development）

npm install
npm run build
npm run check

常用脚本：

• npm run typecheck
• npm run test
• npm run test:e2e
• npm run check

端到端测试说明：

• npm run test:e2e 会运行“除钉钉渠道外”的完整 E2E
• 它会使用真实 runtime、真实 ChannelStore、真实工具/记忆/Sidecar/LLM
• 只 mock 钉钉传输层，不连接真实钉钉 Stream
• 运行前需要可用模型凭据：优先读取 ${PIPICLAW_HOME:-~/.pi/pipiclaw}/auth.json，否则回退到 ANTHROPIC_API_KEY
• E2E 默认不包含在 npm run test 中，避免日常测试被真实 LLM 依赖和调用成本影响

许可证（License）

Apache License 2.0. See LICENSE.