feat(integrations/OpenClaw): add OpenClaw PowerContext memory plugin

[XnLemon]

Which issue or RFC does this PR close?

Closes #1281.

Rationale for this change

OpenClaw needs a memory provider that can use PowerContext's durable, scoped memory backend without modifying OpenClaw core. OpenClaw remains responsible for agent identity, privacy decisions, transcripts, and lifecycle hooks, while PowerContext provides memory storage, search, recall, and processing.

What changes are included in this PR?

• Add an external OpenClaw memory plugin backed by PowerContext HTTP APIs.
• Register the exclusive memory provider slot.
• Expose namespaced tools: powercontext_memory_search, powercontext_memory_get, powercontext_memory_store, powercontext_memory_revise, and powercontext_memory_retire.
• Add lifecycle integration for prompt recall, source capture, compaction flush, and session-end flush.
• Enforce agent/project scopes and private-session restrictions.
• Validate citations and treat recalled memory as untrusted context.
• Defer automatic memory flush when the PowerContext deployment does not advertise memory extraction capability.
• Bound context preparation queries by UTF-8 byte length to satisfy the PowerContext request contract.
• Add an idempotent configure-openclaw.py helper that enables the plugin, preserves user-defined tools.alsoAllow entries, adds the five PowerContext tools, and removes only those managed entries for disable/off.
• Add powercontext setup openclaw --source <source> --ref <ref> to materialize, build, install, and configure the integration in one command.
• Add plugin tests, TypeScript configuration, package metadata, build targets, and CLI setup coverage.

Evidence

Logs - Detail

 "finalPromptText": "请严格按顺序完成一次 PowerContext memory 测试，只使用 powercontext_memory_* 工具：调用 powercontext_memory_store 保存 text=\"PC_FULL_FLOW_TEST\"，kind=\"fact\"；调用 powercontext_memory_search 搜索该文本；使用返回的 citation 调用 powercontext_memory_get；使用该 citation 调用 powercontext_memory_revise，将文本改为 \"PC_FULL_FLOW_TEST_REVISED\"；再次搜索新文本；最后使用最新 citation 调用 powercontext_memory_retire。报告每一步结果。",
      "finalAssistantVisibleText": "[[reply_to_current]]PowerContext memory 测试已严格按顺序完成：\n\n1. **Store**：成功  \n   - 文本：`PC_FULL_FLOW_TEST`\n   - 状态：`stored`\n   - Revision：`4`\n\n2. **Search 原文本**：成功  \n   - 命中：1 条\n   - 内容：`PC_FULL_FLOW_TEST`\n   - 获得 citation\n\n3. **Get**：成功  \n   - 读取内容：`PC_FULL_FLOW_TEST`\n\n4. **Revise**：成功  \n   - 新文本：`PC_FULL_FLOW_TEST_REVISED`\n   - 状态：`revised`\n   - Revision：`5`\n   - 获得新 citation\n\n5. **Search 新文本**：成功  \n   - 命中：1 条\n   - 内容：`PC_FULL_FLOW_TEST_REVISED`\n   - 获得最新 citation\n\n6. **Retire**：成功  \n   - 使用最新 citation\n   - 状态：`retired`\n   - Revision：`6`\n\n**结论：完整流程全部通过。**",
      "finalAssistantRawText": "[[reply_to_current]]PowerContext memory 测试已严格按顺序完成：\n\n1. **Store**：成功  \n   - 文本：`PC_FULL_FLOW_TEST`\n   - 状态：`stored`\n   - Revision：`4`\n\n2. **Search 原文本**：成功  \n   - 命中：1 条\n   - 内容：`PC_FULL_FLOW_TEST`\n   - 获得 citation\n\n3. **Get**：成功  \n   - 读取内容：`PC_FULL_FLOW_TEST`\n\n4. **Revise**：成功  \n   - 新文本：`PC_FULL_FLOW_TEST_REVISED`\n   - 状态：`revised`\n   - Revision：`5`\n   - 获得新 citation\n\n5. **Search 新文本**：成功  \n   - 命中：1 条\n   - 内容：`PC_FULL_FLOW_TEST_REVISED`\n   - 获得最新 citation\n\n6. **Retire**：成功  \n   - 使用最新 citation\n   - 状态：`retired`\n   - Revision：`6`\n\n**结论：完整流程全部通过。**",
      "replayInvalid": true,
      "livenessState": "working",
      "stopReason": "stop",
      "executionTrace": {
        "winnerProvider": "openai",
        "winnerModel": "gpt-5.6-sol",
        "attempts": [
          {
            "provider": "openai",
            "model": "gpt-5.6-sol",
            "result": "success",
            "stage": "assistant"
          }
        ],
        "fallbackUsed": false,
        "runner": "embedded"
      },
      "requestShaping": {
        "authMode": "auth-profile",
        "thinking": "low"
      },
      "toolSummary": {
        "calls": 6,
        "tools": [
          "powercontext_memory_store",
          "powercontext_memory_search",
          "powercontext_memory_get",
          "powercontext_memory_revise",
          "powercontext_memory_retire"
        ],
        "failures": 0
      },
      "completion": {
        "stopReason": "stop",
        "finishReason": "stop"
        

Are there any user-facing changes?

Yes.

The plugin requires OpenClaw 2026.8.1-beta.2 or newer. After building and installing the local plugin, it can be enabled with:

python3 ./scripts/configure-openclaw.py enable http://127.0.0.1:8765 agent

The aligned one-line setup flow is:

powercontext setup openclaw --source oceanbase/powercontext --ref v0.0.2

The helper updates the memory slot and the OpenClaw coding-tool allowlist without overwriting unrelated tools.alsoAllow entries. No OpenClaw core source changes or public PowerContext API breaking changes are introduced.

How was this change tested?

• pnpm --dir integrations/openclaw/plugins/memory-powercontext typecheck
• pnpm --dir integrations/openclaw/plugins/memory-powercontext test — 16 tests passed
• pnpm --dir integrations/openclaw/plugins/memory-powercontext build
• uv run python -m pytest tests/test_openclaw_cli.py tests/test_openclaw_configure_script.py -q — 7 tests passed
• uv run python -m pytest tests/test_cli.py tests/test_dsh_cli.py tests/test_openclaw_cli.py tests/test_openclaw_configure_script.py tests/test_system_cli.py -q — 69 tests passed
• uv run python -m pytest tests/e2e/test_runtime_server.py -q — 7 passed, 3 skipped
• python3 -m py_compile integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py
• Temporary OpenClaw state validation covering idempotent enable, preservation of existing allowlist entries, and precise removal for disable/off
• uv run ruff check integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py tests/test_openclaw_configure_script.py src/powercontext/cli/openclaw.py src/powercontext/cli/system.py tests/test_openclaw_cli.py
• uv run ty check
• git diff --check

AI usage statement

AI tools were used during development and validation. Codex based on GPT-5 was used to inspect the repositories, implement the integration, run tests, and validate the OpenClaw plugin installation and runtime behavior.

中文翻译

此 PR 关闭哪个 Issue 或 RFC？

关闭 #1281。

变更原因

OpenClaw 需要一个能够使用 PowerContext 持久化、隔离 Memory 的提供方，同时不修改 OpenClaw 核心代码。OpenClaw 继续负责 Agent 身份、隐私判断、transcript 和生命周期钩子，PowerContext 负责 Memory 的存储、搜索、召回和处理。

此 PR 包含哪些变更？

• 新增基于 PowerContext HTTP API 的外部 OpenClaw Memory 插件。
• 注册独占的 memory provider slot。
• 暴露命名空间工具：powercontext_memory_search、powercontext_memory_get、powercontext_memory_store、powercontext_memory_revise 和 powercontext_memory_retire。
• 接入提示词召回、Source 采集、压缩前 flush 和会话结束 flush。
• 支持 agent/project scope 和私有会话限制。
• 校验 Memory citation，并将召回内容视为不可信上下文。
• 当 PowerContext 部署未声明 memory extraction 能力时，延后自动 memory flush。
• 按 UTF-8 字节长度限制 context preparation 查询，满足 PowerContext 请求契约。
• 新增幂等的 configure-openclaw.py：启用插件、保留用户已有的 tools.alsoAllow 项、加入五个 PowerContext 工具，并在 disable/off 时只移除由本插件管理的工具。
• 新增 powercontext setup openclaw --source <source> --ref <ref>，用一条命令完成 checkout、构建、安装和集成配置。
• 新增插件测试、TypeScript 配置、包元数据、构建目标和 CLI setup 覆盖。

证据

已使用本地 OpenClaw 2026.8.1-beta.2 Gateway 和本地 PowerContext HTTP Server 完成集成验证。配置脚本报告五个受管工具均已加入 allowlist，并在重复 enable 以及 disable/off 操作中保留无关的用户工具。

是否有面向用户的变更？

有。

插件要求 OpenClaw 2026.8.1-beta.2 或更高版本。构建并安装本地插件后，可以使用以下命令启用：

python3 ./scripts/configure-openclaw.py enable http://127.0.0.1:8765 agent

对齐其他集成的一行 setup 命令为：

powercontext setup openclaw --source oceanbase/powercontext --ref v0.0.2

该脚本会更新 memory slot 和 OpenClaw coding-tool allowlist，不会覆盖无关的 tools.alsoAllow 项。不修改 OpenClaw 核心代码，也不改变 PowerContext 的公共 API。

如何测试？

• pnpm --dir integrations/openclaw/plugins/memory-powercontext typecheck
• pnpm --dir integrations/openclaw/plugins/memory-powercontext test，16 个测试通过
• pnpm --dir integrations/openclaw/plugins/memory-powercontext build
• uv run python -m pytest tests/test_openclaw_cli.py tests/test_openclaw_configure_script.py -q，7 个测试通过
• uv run python -m pytest tests/test_cli.py tests/test_dsh_cli.py tests/test_openclaw_cli.py tests/test_openclaw_configure_script.py tests/test_system_cli.py -q，69 个测试通过
• uv run python -m pytest tests/e2e/test_runtime_server.py -q，7 个通过、3 个跳过
• python3 -m py_compile integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py
• 使用临时 OpenClaw 状态验证 enable 幂等、保留已有 allowlist 项，以及 disable/off 的精确移除行为
• uv run ruff check integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py tests/test_openclaw_configure_script.py src/powercontext/cli/openclaw.py src/powercontext/cli/system.py tests/test_openclaw_cli.py
• uv run ty check
• git diff --check

AI 使用声明

本 PR 的开发和验证过程中使用了 AI 工具。Codex（GPT-5）用于检查代码库、实现集成、运行测试，以及验证 OpenClaw 插件的安装和运行时行为。

[XnLemon]

For Reviewers

Note: 辛苦各位Reviewers owo) b 集成运行时日志和效果可见观测放在 Evidence 内 目前存在的 review 均已修复 请在合并时注意和 #1314 的合并顺序 如果需要合并后的 Follow-up 可以随时进行 PR 产出

!!! Documentation, usage instructions, and the README will be completed in a follow-up PR bcz this PR has LARGE SIZE. This PR focuses on the implementation and adds the following CLI capabilities:

• Adds powercontext setup openclaw for one-command OpenClaw integration.
• Supports selecting the plugin source and Git ref through --source and --ref.
• Supports configuring the PowerContext Server URL with --server-url.
• Supports agent and project memory scopes through --scope-mode.
• Supports machine-readable output through --json.
• Automatically resolves, builds, installs, and configures the OpenClaw memory plugin.
• Preserves existing tools.alsoAllow entries while adding the PowerContext memory tools.
• Provides cross-platform configuration actions for enable, disable, off, and status.

示例命令：

powercontext setup openclaw \
  --source oceanbase/powercontext \
  --ref <ref> \
  --server-url http://127.0.0.1:8765 \
  --scope-mode agent

One Line Command:

powercontext setup openclaw --source oceanbase/powercontext --ref v0.0.2

The relatively large size of this PR is due to the fact that it introduces a complete OpenClaw integration rather than a small configuration hook. It adds a standalone plugin package, OpenClaw lifecycle and memory management, HTTP transport, tool registration, content/privacy/scope handling, runtime validation, SDK typings, package/build configuration, and plugin tests. It also adds the cross-platform Python configurator, the powercontext setup openclaw CLI flow, repository build integration, and CLI/configuration tests. The generated pnpm-lock.yaml contributes several thousand lines to the diff but contains dependency metadata rather than handwritten implementation logic. Overall, the PR adds approximately 31 files and 7,964 lines to provide an installable, configurable, idempotent, and tested integration.

本 PR 体量较大，是因为它实现的是完整的 OpenClaw 集成，而不是简单的配置适配。除了插件本身，还包含生命周期管理、记忆管理、HTTP 通信、工具注册、内容/隐私/作用域处理、运行时校验、SDK 类型声明、构建配置和插件测试，同时新增了跨平台 Python 配置脚本、powercontext setup openclaw CLI 流程、构建集成以及 CLI 和配置测试。pnpm-lock.yaml 产生了数千行依赖元数据，但这些并非手写业务逻辑。整体改动约 31 个文件、7,964 行，目的是提供一套可安装、可配置、幂等且经过测试的完整集成。

[Teingi]

LGTM