Back to Details

huawei-cloud-openviking-agent-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Huawei Cloud Agent Integration (OpenViking Long-Term Memory)

华为云Agent集成（OpenViking长期记忆）

Overview

概述

Integrate and unbind OpenViking long-term memory with coding agents running in bwrap sandboxes under 
/root/job-envs/sandboxes/
. Each agent uses its native mechanism — MCP (
mcp__openviking__*
tools) or the HTTP memory provider — so the integration survives agent upgrades and matches how each agent natively consumes memory.
Integration writes are template-level persistent: config is injected into the agent's 
start.sh
/ config templates under 
/root/template/<agent>/
, so a sandbox 
stop + start
(which re-runs 
start.sh
) preserves the integration.
将OpenViking长期记忆与运行在
/root/job-envs/sandboxes/
目录下bwrap沙箱中的编码Agent进行集成和解绑。每个Agent采用其原生机制——MCP（
mcp__openviking__*
工具）或HTTP内存提供者，因此集成效果可在Agent升级后保留，且与各Agent原生的内存使用方式一致。
集成写入为模板级持久化：配置会注入到
/root/template/<agent>/
目录下Agent的
start.sh
或配置模板中，因此沙箱的
stop + start
操作（会重新执行
start.sh
）可保留集成效果。

What Good Looks Like

预期效果

  • scripts/status.sh
    reports all 7 agents as 
    ✓
    (template + live).
  • scripts/verify_mcp.sh
    passes the full MCP handshake (initialize → tools/list → health) against 
    http://127.0.0.1:1933/mcp
    .
  • Restarting a sandbox does not lose the integration (template-level persistence, not live-only).
  • Agents surface OpenViking tools natively: 
    mcp__openviking__*
    for MCP-based agents, memory provider for JiuwenSwarm.
  • Unbinding removes every trace: template blocks, live config, skills/AGENTS.md, and config backups.
  • User authorization (
    confirm
    ) is required for every mutation — nothing changes silently.
  • scripts/status.sh
    报告所有7种Agent状态为
    ✓
    （模板+实时）。
  • scripts/verify_mcp.sh
    通过针对
    http://127.0.0.1:1933/mcp
    的完整MCP握手（初始化→工具/列表→健康检查）。
  • 重启沙箱不会丢失集成效果（模板级持久化，而非仅实时生效）。
  • Agent原生展示OpenViking工具：基于MCP的Agent显示
    mcp__openviking__*
    ，JiuwenSwarm显示内存提供者。
  • 解绑操作会清除所有痕迹：模板块、实时配置、skills/AGENTS.md以及配置备份。
  • 每次变更操作均需用户授权（
    confirm
    ）——无静默变更。

Supported Agents

支持的Agent

AgentNative mechanismPersistence
CodeArts CLIMCP in 
.codeartsdoer/codearts_cli.json
+ 4-section prompt		Template start.sh + live sandbox
OpenCodeOfficial 
@openviking/opencode-plugin
(npm, Huawei Cloud mirror)		Template start.sh (plugin install)
OpenClawOfficial OpenViking plugin (npm) + 
contextEngine
slot		Template start.sh
HermesMCP + MCP SDK (
pip install mcp
)		Template start.sh + live sandbox
JiuwenSwarmMCP + native memory providerTemplate start.sh + live config.yaml
KimiCodeMCP via 
mcp.json
Template start.sh + live mcp.json
DeepSeek Harness (dsh)Built-in 
@deepseek-ai/dsh-mcp-client
+ profile patches (web/cc-tui) + skill/AGENTS protocol		Template start.sh
Per-agent config files, injection blocks, and recall quotas: references/agent-configs.md.
Agent原生机制持久化方式
CodeArts CLI
.codeartsdoer/codearts_cli.json
中的MCP + 四段式提示词		模板start.sh + 实时沙箱
OpenCode官方
@openviking/opencode-plugin
（npm，华为云镜像）		模板start.sh（插件安装）
OpenClaw官方OpenViking插件（npm） + 
contextEngine
插槽		模板start.sh
HermesMCP + MCP SDK（
pip install mcp
）		模板start.sh + 实时沙箱
JiuwenSwarmMCP + 原生内存提供者模板start.sh + 实时config.yaml
KimiCode通过
mcp.json
实现MCP		模板start.sh + 实时mcp.json
DeepSeek Harness (dsh)内置
@deepseek-ai/dsh-mcp-client
+ 配置文件补丁（web/cc-tui） + skill/AGENTS协议		模板start.sh
各Agent的配置文件、注入块和召回配额详情：references/agent-configs.md。

Prerequisites

前置条件

  • OpenViking server running and accessible (default 
    http://127.0.0.1:1933
    ):
    bash
    curl -s http://127.0.0.1:1933/health
# {"status":"ok","healthy":true,"version":"0.4.x","auth_mode":"dev"}
  • Agent sandboxes exist under 
    /root/job-envs/sandboxes/
    (managed by job-env-manager).
  • Host tools: 
    curl
    , 
    python3
    , 
    bash
    . OpenCode/OpenClaw additionally need 
    npm
    (Huawei Cloud mirror configured by the skill).
  • This skill operates on local bwrap sandboxes only — no Huawei Cloud IAM policies required (see references/iam-policies.md).
  • OpenViking服务器已运行且可访问（默认地址
    http://127.0.0.1:1933
    ）：
    bash
    curl -s http://127.0.0.1:1933/health
# {"status":"ok","healthy":true,"version":"0.4.x","auth_mode":"dev"}
  • Agent沙箱存在于
    /root/job-envs/sandboxes/
    目录下（由job-env-manager管理）。
  • 主机工具：
    curl
    、
    python3
    、
    bash
    。OpenCode/OpenClaw额外需要
    npm
    （本技能会配置华为云镜像）。
  • 本技能仅针对本地bwrap沙箱操作——无需华为云IAM策略（详见references/iam-policies.md）。

参数确认 (Required Inputs)

参数确认（必填输入）

ParameterRequiredDescriptionExample
--agent <name>
Yes (unless 
--all
)		Target agent: 
codearts
, 
opencode
, 
openclaw
, 
hermes
, 
jiuwenswarm
, 
kimicode
, 
deepseek-harness
--agent opencode
--all
Yes (unless 
--agent
)		Operate on all 7 agents
--all
--endpoint <url>
NoOpenViking server URL (default 
http://127.0.0.1:1933
)
--endpoint http://192.168.1.100:1933
--api-key <key>
NoOpenViking API key (dev mode needs none). Never echo in chat or logs
--api-key sk-xxx
--dry-run
NoShow changes without applying them
--dry-run
--yes
/ 
-y
NoSkip authorization prompt (automation only)
--yes
--json
No
status.sh
: machine-readable output
--json
参数是否必填描述示例
--agent <name>
是（除非使用
--all
）		目标Agent：
codearts
、
opencode
、
openclaw
、
hermes
、
jiuwenswarm
、
kimicode
、
deepseek-harness
--agent opencode
--all
是（除非使用
--agent
）		对所有7种Agent执行操作
--all
--endpoint <url>
否OpenViking服务器URL（默认
http://127.0.0.1:1933
）
--endpoint http://192.168.1.100:1933
--api-key <key>
否OpenViking API密钥（开发模式无需密钥）。禁止在聊天或日志中回显
--api-key sk-xxx
--dry-run
否显示变更内容但不实际执行
--dry-run
--yes
/ 
-y
否跳过授权提示（仅用于自动化场景）
--yes
--json
否
status.sh
：输出机器可读格式
--json

Dependencies

依赖项

  • OpenViking server ≥ 0.4.x on 
    127.0.0.1:1933
    (MCP endpoint 
    /mcp
    , streamable HTTP).
  • npm + Huawei Cloud mirror (
    registry.npmmirror.com
    or equivalent) for OpenCode / OpenClaw plugin installs.
  • Python MCP SDK (
    mcp==1.29.0
    ) injected by the skill for Hermes — not in the base template image.
  • dsh CLI (
    /root/runtime/deepseek-harness/bin/dsh
    ) for DeepSeek Harness profile patches (
    --dump-config
    verification).
  • API script conventions are Bash + 
    curl
    + 
    python3
    only.
  • OpenViking服务器 ≥ 0.4.x，运行在
    127.0.0.1:1933
    （MCP端点
    /mcp
    ，支持流式HTTP）。
  • npm + 华为云镜像（
    registry.npmmirror.com
    或等效镜像），用于OpenCode / OpenClaw插件安装。
  • Python MCP SDK（
    mcp==1.29.0
    ），由本技能注入到Hermes中——基础模板镜像未包含该依赖。
  • dsh CLI（
    /root/runtime/deepseek-harness/bin/dsh
    ），用于DeepSeek Harness配置文件补丁的验证（
    --dump-config
    ）。
  • API脚本遵循Bash + 
    curl
    + 
    python3
    的约定。

核心命令

核心命令

功能命令
查看集成状态
scripts/status.sh
（
--json
机器可读，
--agent <name>
指定 Agent）
验证 MCP 端点
scripts/verify_mcp.sh
集成单个 Agent
scripts/integrate.sh --agent <name> [--endpoint URL] [--api-key KEY] [--dry-run] [--yes]
集成全部 Agent
scripts/integrate.sh --all
解绑单个 Agent
scripts/unbind.sh --agent <name> [--dry-run] [--yes]
解绑全部 Agent
scripts/unbind.sh --all
功能命令
查看集成状态
scripts/status.sh
（
--json
机器可读格式，
--agent <name>
指定Agent）
验证MCP端点
scripts/verify_mcp.sh
集成单个Agent
scripts/integrate.sh --agent <name> [--endpoint URL] [--api-key KEY] [--dry-run] [--yes]
集成全部Agent
scripts/integrate.sh --all
解绑单个Agent
scripts/unbind.sh --agent <name> [--dry-run] [--yes]
解绑全部Agent
scripts/unbind.sh --all

Workflow

工作流程

Task 1: Check Integration Status

任务1：检查集成状态

bash
SKILL_DIR=/root/.agents/skills/huawei-cloud-openviking-agent-integration
$SKILL_DIR/scripts/status.sh          # human-readable
$SKILL_DIR/scripts/status.sh --json   # machine-readable
Status values per agent:
  • template + live
    — fully integrated and active
  • template only
    — will activate on next restart
  • live only
    — will be lost on restart (needs template fix)
bash
SKILL_DIR=/root/.agents/skills/huawei-cloud-openviking-agent-integration
$SKILL_DIR/scripts/status.sh          # 人类可读格式
$SKILL_DIR/scripts/status.sh --json   # 机器可读格式
各Agent的状态值：
  • template + live
    — 完全集成且处于活跃状态
  • template only
    — 下次重启后将激活
  • live only
    — 重启后会丢失（需修复模板）

Task 2: Verify MCP Endpoint

任务2：验证MCP端点

bash
$SKILL_DIR/scripts/verify_mcp.sh
Performs the full MCP protocol handshake (initialize → notifications/initialized → tools/list → tools/call health) and lists the OpenViking tools (find, search, recall, read, list, remember, add_resource, …).
bash
$SKILL_DIR/scripts/verify_mcp.sh
执行完整的MCP协议握手（初始化→notifications/initialized→工具/列表→工具/call health），并列出OpenViking工具（find、search、recall、read、list、remember、add_resource等）。

Task 3: Integrate a Single Agent

任务3：集成单个Agent

bash
$SKILL_DIR/scripts/integrate.sh --agent opencode                       # interactive (asks for confirmation)
$SKILL_DIR/scripts/integrate.sh --agent opencode --endpoint URL --api-key KEY
$SKILL_DIR/scripts/integrate.sh --agent opencode --dry-run             # preview only
$SKILL_DIR/scripts/integrate.sh --agent opencode --yes                 # automation only
bash
$SKILL_DIR/scripts/integrate.sh --agent opencode                       # 交互式（需确认）
$SKILL_DIR/scripts/integrate.sh --agent opencode --endpoint URL --api-key KEY
$SKILL_DIR/scripts/integrate.sh --agent opencode --dry-run             # 仅预览
$SKILL_DIR/scripts/integrate.sh --agent opencode --yes                 # 仅自动化场景

Task 4: Integrate All Agents

任务4：集成全部Agent

bash
$SKILL_DIR/scripts/integrate.sh --all
bash
$SKILL_DIR/scripts/integrate.sh --all

Task 5: Unbind a Single Agent

任务5：解绑单个Agent

bash
$SKILL_DIR/scripts/unbind.sh --agent opencode
$SKILL_DIR/scripts/unbind.sh --agent opencode --dry-run
$SKILL_DIR/scripts/unbind.sh --agent opencode --yes
bash
$SKILL_DIR/scripts/unbind.sh --agent opencode
$SKILL_DIR/scripts/unbind.sh --agent opencode --dry-run
$SKILL_DIR/scripts/unbind.sh --agent opencode --yes

Task 6: Unbind All Agents

任务6：解绑全部Agent

bash
$SKILL_DIR/scripts/unbind.sh --all
bash
$SKILL_DIR/scripts/unbind.sh --all

Task 7: Rebuild OpenClaw Sandbox (Apply Template Changes)

任务7：重建OpenClaw沙箱（应用模板变更）

OpenClaw's gateway runs in an ephemeral bwrap; 
stop + start
re-runs 
start.sh
, which reinstalls the plugin and applies endpoint config. Do:
  1. curl -s -X POST $BASE/envs/openclaw/stop
    (poll until 
    stopped
    )
  2. curl -s -X POST $BASE/envs/openclaw/start
    (poll until 
    running
    )
  3. Verify: 
    scripts/integrate.sh --agent openclaw --dry-run
    reports endpoint configured
Full restart/rebuild scripts (including the 
stop → delete → create → deploy
fallback) and live-config verification from outside bwrap: references/related-commands.md.
OpenClaw的网关运行在临时bwrap沙箱中；
stop + start
会重新执行
start.sh
，从而重新安装插件并应用端点配置。操作步骤：
  1. curl -s -X POST $BASE/envs/openclaw/stop
    （轮询直到状态为
    stopped
    ）
  2. curl -s -X POST $BASE/envs/openclaw/start
    （轮询直到状态为
    running
    ）
  3. 验证：
    scripts/integrate.sh --agent openclaw --dry-run
    报告端点已配置
完整的重启/重建脚本（包括
stop → delete → create → deploy
备选方案）以及沙箱外的实时配置验证方法：references/related-commands.md。

Authorization Model

授权模型

Both 
integrate.sh
and 
unbind.sh
require explicit user confirmation before modifying any agent configuration:
━━━ Authorization Required ━━━
  Action:   Integrate OpenViking MCP
  Agent:    opencode
  Details:  Add OpenViking MCP to OpenCode template start.sh (persistent across restarts)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Type 'confirm' to proceed:
  • The user must type exactly 
    confirm
    ; any other input aborts.
  • --yes
    / 
    -y
    skips the prompt (for automation only).
  • --dry-run
    shows what would happen without requiring authorization.
  • Never integrate or unbind without explicit user confirmation — see references/guardrails.md for the full rules.
integrate.sh
和
unbind.sh
在修改任何Agent配置前均需用户明确确认：
━━━ 需要授权 ━━━
  操作:   集成OpenViking MCP
  Agent:    opencode
  详情:  将OpenViking MCP添加到OpenCode模板start.sh中（重启后仍保留）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

输入'confirm'以继续：
  • 用户必须准确输入
    confirm
    ；其他输入将终止操作。
  • --yes
    / 
    -y
    可跳过提示（仅用于自动化场景）。
  • --dry-run
    会展示预期变更，无需授权。
  • 未经用户明确确认，不得执行集成或解绑操作——完整规则详见references/guardrails.md。

Safety Rules

安全规则

  • Authorization is mandatory — never integrate or unbind without explicit user confirmation.
  • Do not fabricate integration state — always run 
    status.sh
    to verify before reporting.
  • Never edit agent configs directly on the host — all changes go through the skill scripts.
  • No API keys in logs — 
    --api-key
    values must never appear in output or logs.
  • Dry-run first for unfamiliar targets.
  • Slow responses are not an integration bug — check model API TTFB before blaming MCP (see references/troubleshooting.md).
  • 授权是强制性的——未经用户明确确认，不得执行集成或解绑操作。
  • 不得伪造集成状态——报告前必须运行
    status.sh
    进行验证。
  • 不得直接在主机上编辑Agent配置——所有变更必须通过本技能脚本执行。
  • 日志中不得包含API密钥——
    --api-key
    的值不得出现在输出或日志中。
  • 针对不熟悉的目标，先执行dry-run。
  • 响应缓慢并非集成问题——在归咎于MCP前，先检查模型API的TTFB（详见references/troubleshooting.md）。

Validation Rules

验证规则

Quick verification after any integration or unbinding:
bash
$SKILL_DIR/scripts/status.sh          # all agents green
$SKILL_DIR/scripts/verify_mcp.sh      # MCP handshake passes
Acceptance criteria for each workflow (integrate/unbind per agent): references/acceptance-criteria.md. Step-by-step verification methods: references/verification-method.md.
集成或解绑操作后的快速验证：
bash
$SKILL_DIR/scripts/status.sh          # 所有Agent状态为绿色
$SKILL_DIR/scripts/verify_mcp.sh      # MCP握手通过
各工作流程（集成/解绑单个Agent）的验收标准：references/acceptance-criteria.md。 分步验证方法：references/verification-method.md。

References

参考文档

DocumentDescription
agent-configs.mdPer-agent config files, injection blocks, persistence patterns, recall quotas, MCP tools
guardrails.mdSafety and authorization rules
troubleshooting.mdCommon failure scenarios, slow-response diagnostics (model TTFB vs network vs MCP), and fixed unbind cleanup issues
iam-policies.mdEquivalent access controls (no Huawei Cloud IAM needed)
verification-method.mdStep-by-step verification for each workflow
related-commands.mdRestart/rebuild scripts, inspection commands, live-config verification
acceptance-criteria.mdAcceptance criteria for integration/unbinding
demo/example-input.jsonExample input for the integration workflow
文档描述
agent-configs.md各Agent的配置文件、注入块、持久化模式、召回配额、MCP工具
guardrails.md安全与授权规则
troubleshooting.md常见故障场景、响应缓慢诊断（模型TTFB vs 网络 vs MCP）、已修复的解绑清理问题
iam-policies.md等效访问控制（无需华为云IAM）
verification-method.md各工作流程的分步验证方法
related-commands.md重启/重建脚本、检查命令、实时配置验证
acceptance-criteria.md集成/解绑操作的验收标准
demo/example-input.json集成工作流程的示例输入

Scripts

脚本说明

scripts/status.sh       Check integration status for all agents (--agent, --json)
scripts/verify_mcp.sh   Verify MCP endpoint via full protocol handshake
scripts/integrate.sh    Integrate single agent or all agents (--agent/--all, --dry-run, --yes)
scripts/unbind.sh       Unbind single agent or all agents (--agent/--all, --dry-run, --yes)
scripts/unset.sh        Alias for unbind.sh (backward-compatibility wrapper)
scripts/common.sh       Shared helpers (logging, confirmation, backups) — sourced by the others
All scripts are idempotent and create 
.bak.<timestamp>
backups before each modification.
scripts/status.sh       检查所有Agent的集成状态（支持--agent、--json参数）
scripts/verify_mcp.sh   通过完整协议握手验证MCP端点
scripts/integrate.sh    集成单个或全部Agent（支持--agent/--all、--dry-run、--yes参数）
scripts/unbind.sh       解绑单个或全部Agent（支持--agent/--all、--dry-run、--yes参数）
scripts/unset.sh        unbind.sh的别名（向后兼容包装器）
scripts/common.sh       共享辅助函数（日志、确认、备份）——被其他脚本调用
所有脚本均具有幂等性，每次修改前会创建
.bak.<timestamp>
备份文件。