huawei-cloud-openviking-agent-integration

Huawei Cloud Agent Integration (OpenViking Long-Term Memory)

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.

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.

Supported Agents

Agent	Native mechanism	Persistence
CodeArts CLI	MCP in .codeartsdoer/codearts_cli.json + 4-section prompt	Template start.sh + live sandbox
OpenCode	Official @openviking/opencode-plugin (npm, Huawei Cloud mirror)	Template start.sh (plugin install)
OpenClaw	Official OpenViking plugin (npm) + contextEngine slot	Template start.sh
Hermes	MCP + MCP SDK (pip install mcp)	Template start.sh + live sandbox
JiuwenSwarm	MCP + native memory provider	Template start.sh + live config.yaml
KimiCode	MCP 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.

Prerequisites

• OpenViking server running and accessible (default http://127.0.0.1:1933):

  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).

参数确认 (Required Inputs)

Parameter	Required	Description	Example
--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>	No	OpenViking server URL (default http://127.0.0.1:1933)	--endpoint http://192.168.1.100:1933
--api-key <key>	No	OpenViking API key (dev mode needs none). Never echo in chat or logs	--api-key sk-xxx
--dry-run	No	Show changes without applying them	--dry-run
--yes / -y	No	Skip authorization prompt (automation only)	--yes
--json	No	status.sh: machine-readable output	--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.

核心命令

功能	命令
查看集成状态	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

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)

Task 2: Verify MCP Endpoint

$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, …).

Task 3: Integrate a Single Agent

$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

Task 4: Integrate All Agents

$SKILL_DIR/scripts/integrate.sh --all

Task 5: Unbind a Single Agent

$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

$SKILL_DIR/scripts/unbind.sh --all

Task 7: Rebuild OpenClaw Sandbox (Apply Template Changes)

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.

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.

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).

Validation Rules

Quick verification after any integration or unbinding:

$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.

References

Document	Description
agent-configs.md	Per-agent config files, injection blocks, persistence patterns, recall quotas, MCP tools
guardrails.md	Safety and authorization rules
troubleshooting.md	Common failure scenarios, slow-response diagnostics (model TTFB vs network vs MCP), and fixed unbind cleanup issues
iam-policies.md	Equivalent access controls (no Huawei Cloud IAM needed)
verification-method.md	Step-by-step verification for each workflow
related-commands.md	Restart/rebuild scripts, inspection commands, live-config verification
acceptance-criteria.md	Acceptance criteria for integration/unbinding
demo/example-input.json	Example input for the integration workflow

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.