pipiclaw

Pipiclaw 是一个接入钉钉的 AI Card 机器人，把 pi-coding-agent 带到钉钉对话里，支持过程性 AI 卡片、最终 Markdown 回复、内置 Slash 命令、技能扩展和定时事件。

功能

• 钉钉 Stream 模式接收消息，自动重连
• 过程性思考和执行信息通过 AI Card 展示，最终答复独立快速返回
• 内置 Slash 命令：/help、/new、/compact、/session、/model
• 每个 DM / 群聊独立工作空间
• 支持全局和频道级 SOUL.md、AGENT.md、MEMORY.md
• 支持全局和频道级技能目录
• 支持 immediate / one-shot / periodic 定时事件
• 支持自定义模型配置和模型切换

安装

npm install -g @oyasmi/pipiclaw

首次运行

pipiclaw

首次运行时，Pipiclaw 会自动创建 ~/.pi/pipiclaw/，并生成这些文件和目录：

• channel.json
• auth.json
• models.json
• settings.json
• workspace/
• workspace/events/
• workspace/skills/
• workspace/SOUL.md
• workspace/AGENT.md
• workspace/MEMORY.md

如果 channel.json 还是示例占位符，程序会提示你先填写真实配置，然后退出。

钉钉应用配置

在 钉钉开放平台 创建企业内部应用：

1. 创建应用并获取 Client ID 和 Client Secret
2. 开启机器人能力并启用 Stream 模式
3. 如需 AI Card 流式输出，创建 AI 卡片模板并获取 Card Template ID

配置文件

channel.json

~/.pi/pipiclaw/channel.json

程序会自动生成一个模板文件。你需要至少填写：

• clientId
• clientSecret

通常还会填写：

• robotCode
• cardTemplateId
• allowFrom

模板示例：

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

说明：

• robotCode 留空时默认回退到 clientId
• cardTemplateId 留空时不使用 AI Card 流式输出
• allowFrom 设为 [] 或删除时允许所有人

auth.json

~/.pi/pipiclaw/auth.json

首次运行会自动生成空对象：

{}

如果你使用环境变量提供模型密钥，可以一直保持为空。也可以手工写成：

{
  "anthropic": "your-anthropic-api-key"
}

models.json

~/.pi/pipiclaw/models.json

首次运行会自动生成一个自定义模型示例，结构参考 pi-coding-agent 的模型配置，但 API key 默认留空，不会生效，供你按需填写：

{
  "providers": {
    "zpai": {
      "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
      "api": "openai-completions",
      "apiKey": "",
      "models": [
        {
          "id": "glm-5-turbo",
          "name": "glm-5-turbo"
        }
      ]
    },
    "bailian": {
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
      "api": "openai-completions",
      "apiKey": "",
      "models": [
        {
          "id": "kimi-k2.5",
          "name": "kimi-k2.5"
        },
        {
          "id": "glm-5",
          "name": "glm-5"
        },
        {
          "id": "qwen3-max-2026-01-23",
          "name": "qwen3-max-2026-01-23"
        }
      ]
    }
  }
}

settings.json

~/.pi/pipiclaw/settings.json

首次运行会自动生成：

{}

/model 等命令写入的默认模型会保存在这里，并在重启后继续生效。

运行

填写好 channel.json 和模型认证信息后，再次启动：

pipiclaw

如需 Docker sandbox，可以显式指定：

pipiclaw --sandbox=docker:your-container

内置 Slash 命令

以下命令由 Pipiclaw 直接处理，不会作为普通 prompt 发送给模型：

• /help
• /new
• /compact [instructions]
• /session
• /model [provider/modelId|modelId]

说明：

• /model 无参数时返回当前模型和可用模型列表
• /model <ref> 只支持精确匹配
• 未被 Pipiclaw 拦截的其他 slash 输入，仍会按 AgentSession.prompt() 的原有逻辑处理

工作空间布局

~/.pi/pipiclaw/
├── channel.json
├── auth.json
├── models.json
├── settings.json
└── workspace/
    ├── SOUL.md
    ├── AGENT.md
    ├── MEMORY.md
    ├── skills/
    ├── events/
    └── dm_{userId}/
        ├── AGENT.md
        ├── MEMORY.md
        ├── .channel-meta.json
        ├── context.jsonl
        ├── log.jsonl
        └── skills/

定时事件

在 ~/.pi/pipiclaw/workspace/events/ 中创建 JSON 文件来触发定时任务：

• immediate
• one-shot
• periodic

示例：

{
  "type": "periodic",
  "channelId": "dm_your-staff-id",
  "text": "Review your MEMORY.md files. Remove outdated entries, merge duplicates, ensure well-organized.",
  "schedule": "0 3 * * 0",
  "timezone": "Asia/Shanghai"
}

环境变量

开发

npm install
npm run build
npm run dev