IPFS Pin

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install ipfs-pin
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 ipfs-pin。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

IPFS Pin 是一项 OpenClaw 技能，用于管理本地 Kubo IPFS 节点上的内容持久性。它会添加文件并固定文件，使其持续保存在本地磁盘上，同时在账本中记录每个 CID 及其生存时间（TTL）。由于 IPFS 内容按字节寻址，相同文件会共享一个 CID；重新添加内容会刷新其跟踪的 TTL，而不是创建重复条目。
该技能将简单的 CID 管理与自动清理相结合：每日运行的 systemd 用户级定时器会执行衰减扫描，取消固定已过期的跟踪条目，并对仓库进行垃圾回收。Openclaw Skills 用户可以检查状态、预览清理操作、检索内容并刷新引用，同时只依赖 IPFS CLI 实际返回的 CID 和状态。

应用场景

将文件固定在本地 IPFS 节点上，即使离线也能继续使用。
使用可配置的默认 TTL，跟踪存储内容应保持固定的时长。
重新添加相同内容或触碰其 CID，以刷新文件的生命周期。
在运行清理之前，预览哪些跟踪的固定项即将过期。
通过 CID 检索之前固定的内容，可输出到标准输出或文件。
检查守护进程健康状况、仓库大小、固定项数量以及手动添加但未跟踪的固定项。
通过每日 systemd 定时器自动回收过期内容占用的存储空间。

工作原理

该技能会调用其 ipfs_pin.py 命令行界面，并与位于 127.0.0.1:5001 的本地 Kubo 节点通信。
运行 add 时，它会添加指定文件、固定该文件，并将 CLI 返回的 CID 和 TTL 信息记录到账本中。除非另行配置，否则默认 TTL 为 72 小时。
~/.openclaw/ipfs-pin/ledger.json 中的账本会跟踪每个受管理 CID 及其引用时间。使用 touch 可刷新 CID，而无需重新添加文件。
使用 ls 或 status 检查跟踪条目、剩余生命周期、守护进程健康状况、仓库大小、固定项数量以及未跟踪的固定项。
每日运行的 ipfs-pin-decay.timer 会触发衰减扫描。系统会取消固定已过期的跟踪 CID，随后运行 ipfs repo gc；decay --dry-run 可预览操作，而不实际执行。
使用 get 按 CID 检索内容，或使用 rm 立即取消固定某个跟踪 CID。该技能只报告 IPFS CLI 返回的值和状态。

配置指南

该技能需要 ipfs 二进制文件和本地 Kubo 守护进程。文档中的设置使用位于 ~/bin/ipfs 的 Kubo 0.43.1，并配置用户级 systemd 服务和每日衰减定时器。使用以下命令检查服务和定时器：
systemctl --user status ipfs
systemctl --user status ipfs-pin-decay.timer
通过该技能的 CLI 运行命令：
~/.openclaw/plugin-skills/ipfs-pin/ipfs_pin.py ...
如需结构化输出，请将 --json 紧跟在程序名称后面。默认 TTL 为 72 小时；使用 config 查看或更改该值。使用以下命令预览下一次清理扫描：
~/.openclaw/plugin-skills/ipfs-pin/ipfs_pin.py decay --dry-run
如果守护进程不可用，请使用 status 确认问题，而不要假定它正在运行。

数据架构

该技能在 ~/.openclaw/ipfs-pin/ledger.json 中维护其受管理内容账本。
数据或资源 用途
CID 标识 IPFS CLI 返回的内容；相同字节会解析为相同的 CID。
TTL 和引用时间 确定跟踪的固定项何时符合衰减条件；touch 和重新添加内容都会刷新引用。
本地 Kubo 仓库 在本地节点存储并提供固定内容。
ipfs-pin-decay.timer 用于安排每日过期扫描的 systemd 用户级定时器。
未跟踪的固定项 在此技能之外创建的固定项，例如通过手动运行 ipfs add 创建的固定项；status 会单独标记它们。
该技能不会声称在其账本中跟踪手动添加的固定项。衰减工作流仅作用于跟踪条目，然后运行 ipfs repo gc 回收仓库空间。

高级特性

TTL 生命周期管理：
配置默认 TTL，使用
touch
刷新跟踪的 CID，或重新添加相同内容来刷新它。
安全的清理预览：
decay --dry-run
，查看哪些内容将被取消固定，而不更改固定项或运行清理操作。
自动垃圾回收：
每日 systemd 用户级定时器会运行衰减和仓库垃圾回收，无需手动安排。
结构化 CLI 输出：
在程序名称后添加 --json ，以获取机器可读的结果。
运行状态可见性：
status
会报告守护进程是否可用、仓库大小、固定项数量，以及跟踪和未跟踪的固定项。
明确的保留控制：
rm
会立即移除跟踪的 CID；可选的 --no-gc 标志可跳过垃圾回收。
如实报告 CID：
该技能只报告
ipfs
CLI 返回的 CID 和状态；不会伪造标识符或推断守护进程健康状况。

name: ipfs-pin description: > IPFS content persistence for OpenClaw via a local kubo node. Adds files
to IPFS, pins them so they stay robust while active, and tracks a
per-file TTL in a ledger. decay unpins entries not referenced within
their TTL and garbage-collects the repo; a systemd user timer runs it
daily so unused content decays naturally without manual cleanup.
Reports only CIDs and status the ipfs CLI actually returned.
user-invocable: true