dsh-xiaoyi

dsh-xiaoyi

English | 简体中文

A DSH (DeepSeek Harness) host plugin that connects Huawei XiaoYi in OpenClaw mode to your local DSH session — voice, text and images from your phone reach the agent running on your own machine.

This is not a standalone chatbot. XiaoYi is only the entry point; what it connects to is your local DSH session (same tools, same working directory). There is no second agent.

Huawei XiaoYi on your phone  (anywhere)
   │  voice / text / images
   ▼
Huawei Cloud  wss://hag.cloud.huawei.com/openclaw/v1/ws/link
   │  long-lived connection (AK/SK auth + 30s heartbeat)
   ▼
This plugin  (runs inside the DSH host process)
   │
   ▼
DSH session  xiaoyi-listen-*

---

Prerequisites

This is not plug-and-play. Before installing, make sure you have all three:

If you cannot obtain item 2, you can still read this repository as a protocol reference implementation — index.js implements the XiaoYi/OpenClaw handshake, auth, heartbeat and JSON-RPC message exchange in full.

Where do AK / SK / agentId come from?

They are issued by Huawei. This project cannot create them for you and cannot tell you whether your account is eligible. You have to apply for them yourself:

1. Register a Huawei developer account and complete real-name verification — https://developer.huawei.com/consumer/cn/register/
2. Sign in to the XiaoYi Open Platform and create an agent — https://developer.huawei.com/consumer/cn/hag/hagindex.html#/ When creating it, choose the OpenClaw mode. Other modes are not compatible with this plugin.
3. Take the values from the agent's detail page:
   • agentId — shown in the AgentCard block;
   • AK / SK — under Credentials → New credential. The SK is displayed only once, so copy it immediately.
4. Add your own Huawei account to the agent's test whitelist. Until the agent is published, only whitelisted accounts can reach it; it takes effect after a few minutes.
5. Official documentation for this mode — https://developer.huawei.com/consumer/cn/doc/doccenter-celia/openclaw-0000002518410344

Menu names, entry points and the review process are decided entirely by Huawei and may change at any time. If a step above no longer matches what you see, follow Huawei's own documentation rather than this file. This plugin only consumes the three credentials. It never asks Huawei for anything else on your behalf.

---

Features

• Zero third-party dependencies. Only Node built-ins are used, including a hand-written minimal WebSocket client (RFC6455 client side: text frames, fragmentation reassembly, ping/pong, and handshake verification). Fewer packages in the plugin tree means fewer chances that one failed package takes the whole host down.
• Complete protocol implementation. Auth signing, init handshake, heartbeat with stale-connection detection, JSON-RPC 2.0 streaming, and control messages (clearContext / tasks/cancel).
• Inbound attachments. Images and files sent from XiaoYi are downloaded to disk, and their local paths are handed to the agent in the session (ready for read_image / read).
• Outbound online files (experimental). Send local files back to XiaoYi (the protocol only accepts public https URLs; supports a local tunnel or a third-party image host). See the direction table below — this direction is not reliable.
• Session reuse. On a cold start the plugin resumes the existing session instead of opening a new conversation every time.

What can travel in each direction

In short: the inbound direction is the reliable one. If your workflow depends on images or files arriving on your phone, do not rely on it.

---

Installation

1. Place the source

Put this directory anywhere you keep plugins. The conventional location is:

~/.dsh/plugin-sources/dsh-xiaoyi

2. Register it in your profile

Option A (recommended, one command):

# install from the GitHub repository
dsh plugin --profile web add git+https://github.com/HangZhouXi/dsh-xiaoyi

# or from npm (after it is published there)
dsh plugin --profile web add dsh-xiaoyi

Option B (edit by hand):

Edit ~/.dsh/profiles/web/package.json:

{
  "dsh": {
    "profile": {
      "bundles": [
        // ...
        "dsh-xiaoyi"          // ← add to bundles
      ]
    }
  },
  "dependencies": {
    // ...
    "dsh-xiaoyi": "git+file:///C:/Users/<you>/.dsh/plugin-sources/dsh-xiaoyi"
  }
}

A plain local path dependency also works: "dsh-xiaoyi": "file:../../plugin-sources/dsh-xiaoyi".

3. Install and cold-start

dsh plugin --profile web install

Then cold-start the DSH host. (Host-side plugins are not applied by hot reload — a cold start is required.)

4. Provide credentials

Edit ~/.dsh/xiaoyi/state.json:

{
  "enabled": true,
  "ak": "XiaoYi Open Platform AK",
  "sk": "XiaoYi Open Platform SK",
  "agentId": "agentId of your OpenClaw-mode agent",
  "wsUrl": "wss://hag.cloud.huawei.com/openclaw/v1/ws/link",
  "sessionId": "",
  "cwd": "C:\\Users\\<you>\\Desktop",
  "publicBaseUrl": "",
  "imageHost": ""
}

You can also let the agent configure these at runtime with the xiaoyi_set tool (changes take effect immediately and reconnect).

Log file: ~/.dsh/xiaoyi/xiaoyi.log

---

Agent tools

HTTP routes

---

Protocol summary

Verified against the published artifacts of @ynhcj/xiaoyi. This project does not depend on that package.

Outbound files (xiaoyi_send_photo)

The Part sent back to the client is { url, filename, mediaType } — only public https URLs are accepted; there is no "upload bytes" interface. Hence two modes:

local mode requires state.publicBaseUrl; without it the tool returns an error and never silently falls back to an image host.

---

Security and privacy

• Credentials stay local. They live in ~/.dsh/xiaoyi/state.json, which is excluded by .gitignore. They are never committed and never logged (the log only records whether a value is present).
• Inbound attachments are protected against SSRF. The inbound uri comes from an external message and is treated as untrusted input. Only http/https is allowed. Every hop of a redirect chain is checked before it is fetched (redirect: 'manual'), and each host is judged two ways: structurally, and by what it actually resolves to. IPv6 addresses are parsed into bytes rather than compared as strings, so equivalent spellings cannot slip through. Blocked ranges: loopback, private, link-local, unique-local, multicast, site-local, IPv4-mapped (::ffff:a.b.c.d), NAT64, 6to4 and Teredo — including cloud metadata endpoints such as 169.254.169.254.
• Attachments are size-capped. 50 MB per file, read as a stream, so a lying content-length cannot exhaust memory.
• Published URLs are unguessable. Filenames include 8 random bytes.
• ⚠️ The HTTP routes themselves have no authentication. /xiaoyi/state and /xiaoyi/public/* are reachable by anyone who can reach the port. Do not expose the DSH port directly to the internet; if you use a tunnel, prefer one with authentication or an unguessable hostname.

---

Known limitations

• A file or image cannot be pushed back to the phone reliably. The protocol only accepts a public https URL for outbound files, and whether the XiaoYi client renders the resulting file part is outside this project's control. Text replies are unaffected.
• Outbound attachments must use a public URL. This is a protocol constraint, not a shortcut in the implementation.
• Inbound attachment URLs are pre-signed and expire in roughly 30 minutes, so they must be fetched immediately. This plugin does exactly that; if a download fails, the link has most likely expired.
• The media/ directory is never cleaned automatically. Prune ~/.dsh/xiaoyi/media/ yourself periodically.
• Platform-side policies may change. OpenClaw mode, endpoints and field names can be adjusted by Huawei at any time; long-term availability is not guaranteed.

---

Uninstall

1. Remove dsh-xiaoyi from bundles and dependencies in ~/.dsh/profiles/web/package.json.
2. dsh plugin --profile web install
3. Cold-start the host.
4. For a complete cleanup, delete ~/.dsh/xiaoyi/ (it contains credentials and logs).

---

Troubleshooting

---

License

MIT

Disclaimer

Please read DISCLAIMER.md before use.