← 返回首页

使用指南

从下载到跑通第一个 Agent,大概 10 分钟。涉及服务端配置的地方都给出最简链路。

安装

Agent Cast 当前仅 HarmonyOS 5.0+ (API 12+)。安装有两种方式:

推荐

侧载 APK

下载签名 HAP 后用 DevEco 或华为手机「文件管理」安装。无需商店审核,随时跟最新版。

AppGallery

审核中,正式上架后开放。

  1. 1. 获取 v1.0.0 HAP 文件（上架后可在本站下载）。
  2. 2. 发送到手机(微信/网盘/USB 都行),点击 HAP 文件触发安装。
  3. 3. 首次启动授予「网络」「文件访问」权限,即可进入主页。

连接第一个 Agent

App 只做标准 HTTPS / WSS 客户端。无论哪个 Agent,流程都一样:

  1. 1 在桌面 / 服务器上启动 Agent 服务
  2. 2 确保手机能访问到(同局域网 / Tailscale / cloudflared quick tunnel)
  3. 3 在 App「Agents」页点 +,填入 endpoint 与凭证
  4. 4 在「Sessions」发起对话

💡 桌面侧的公网入口怎么搞?
最省心的是内嵌 cloudflared quick tunnel(免登录,一次性域名)。 或者 frp / Tailscale 都行。App 端代码无需改动,只填最终可直达的 URL。

Hermes

Hermes Agent 提供 OpenAI 兼容的 /v1 端点 + SSE 流式。直连即可。

服务端

启动 Hermes API Server,记录 API_SERVER_KEY。

App 端配置

Endpoint · https://your-host
API Key · 粘贴你的 API_SERVER_KEY
Agent Kind · Hermes (OpenAI 兼容)

M1.5 阶段支持 思考过程显示 + 审批按钮 + 服务端中断。

OpenCode

OpenCode v2 提供 /global/event SSE 真流式主路径,断线时回退到轮询。集成度仅次于 Hermes。

服务端

$
opencode serve --port 14096 --hostname 0.0.0.0

App 端配置

Endpoint · http://your-host:14096
Auth · opencode basic auth (可选)
Agent Kind · OpenCode

特色能力:项目文件浏览 + DiffSheet 回合级改动查看。

OpenClaw

OpenClaw 是 Gateway WebSocket (JSON-RPC 2.0) 协议,默认端口 18789。当前 Adapter Phase 1 已完成,完整集成在 M2 阶段。

前置

  • ·本地 OpenClaw Gateway 已启动并配置 token / password
  • ·Gateway 绑定 --bind lan 或经 Tailscale / SSH 隧道可达
  • ·准备好 hello-ok / snapshot 验证手段

⚠️ 移动端限制
OpenClaw 事件不重放。重连后必须主动 health / presence 刷新。 手机端不暴露 fs/* 类工具(防 agent 误碰)。

常见问题

为什么不做 IM?
钉钉/飞书那种聊天轮询会拖累鸿蒙后台。Agent 跑在桌面,App 只在用户想遥控时启动,断线重连即恢复,这是设计红利。
我的 Agent 协议 App 不支持怎么办?
写一个 AgentAdapter 实现 AgentContracts 接口,注册到 ConnectionManager。这是 M3 之后的官方扩展位。
Token 存在哪里?
Asset Store Kit (系统密钥库) + HUKS AES-GCM 加密,明文不落盘。卸载 App 即全部销毁。
App 会上传我的对话内容吗?
不会。所有数据走本地 RelationalStore,App 无任何云端 endpoint。详见隐私政策。

故障排查

网络

连接显示「unauthorized」

检查 endpoint 对应的 API key / token 是否正确粘贴。OpenClaw 场景确认 gateway.auth.token 与 Gateway 启动时一致。

网络

能连接但收不到流式响应

检查反向代理是否缓冲 SSE。Nginx 加 proxy_buffering off;Cloudflare Workers 注意 streaming 配置。

OpenCode

提问卡看不到 / 回合不结束

这是 OpenCode v2 适配器已知修复点(v1.0.0 已修)。若自行 build,确认 OpenCodeAdapter.ets 在 230+ 行版本。

HarmonyOS

后台被杀导致连接断开

v1.0.0 已加「后台长时任务」+「回合完成系统通知」。若仍被杀,检查「应用启动管理」是否限制了 Agent Cast。

返回首页