arkclaw-webchat-cli 0.9.0

CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK.

arkclaw

Chat with your ArkClaw claws (agents) from the terminal — log in with your own SSO identity, no passwords, no permanent keys. Works the same for a human at a prompt and for another agent/script (--json + exit codes).

arkclaw init        # one-time interactive setup (asks only what it can't auto-detect)
arkclaw login       # browser SSO
arkclaw agents      # list the agents you can chat
arkclaw chat ci-xxxxxxxx

---

What it can do

• Log in as you — browser SSO (PKCE), short-lived token, auto-refresh. No AK/SK, no client secret, nothing permanent on disk but a token in your OS keychain.
• List your agents — arkclaw agents shows the agents in your accessible claws (add a claw by chatting it once: arkclaw chat ci-...).
• Manage agents — agents create / agents delete add or remove named agents in a claw, right from the terminal.
• Chat — interactive REPL or one-shot -m, streaming token-by-token, with a live "what's it doing" spinner and tool-event trace.
• Talk to a specific claw — by id (chat ci-...) or by name (chat 答疑助手).
• Manage a claw's files — read/write its managed workspace files (AGENTS.md, SOUL.md, MEMORY.md, …) with ls / pull / push.
• Upload & download any file — push arbitrary files into the claw's real workspace filesystem and pull results back (a whole directory comes as a .tar) with upload / download / mkdir / ls <path>, over the Silk file service (needs a Silk-enabled claw).
• Large-product storage — a separate IDS netdisk plane for big artifacts/videos: netdisk create-space / ls / upload / download / mkdir / rm.
• Read past conversations — list an agent's sessions, then pull a full transcript with arkclaw history <会话ID> (over the chat.history ws RPC; --json to export, -o to a file).
• Fan out — send one message to many claws in parallel.
• Be scripted — every command takes --json (one clean {ok,data,error} envelope on stdout) and returns a typed exit code.

Two transports, picked at login: openclaw (your claws, the default) and a2a (an agent endpoint).

---

Install

pip install arkclaw-webchat-cli          # provides the `arkclaw` command

From source:

git clone <repo> && cd ee-claw
uv venv && uv pip install -e .

Contributing / hacking on the CLI? Start with AGENTS.md — dev setup, the three gates, code map, invariants, and how to add a command/provider/transport.

---

Quick start

# 0. one-time setup — interactive. Asks for your space address and (only if the
#    space doesn't already publish them) the CLI client + STS role. Saved to
#    ~/.arkclaw/defaults.json so you never type them again.
arkclaw init

# 1. log in (a browser opens; sign in with SSO)
arkclaw login

# 2. list the claws you've used (empty at first — you add them by chatting)
arkclaw agents

# 3. chat — interactive…
arkclaw chat ci-xxxxxxxx
#    …or one-shot:
arkclaw chat ci-xxxxxxxx -m "用一句话介绍你自己"

arkclaw init resolves everything it can from the address (identity pool, region) and only prompts for what's missing. Once your space publishes auto-discovery, init asks for nothing but the address — and you can even skip straight to arkclaw login https://your-space.... See Configuration.

---

Commands

Command	What it does
arkclaw init [address]	One-time interactive setup. Saves the address + (only what isn't auto-discovered) the CLI client and STS role to ~/.arkclaw/defaults.json, so later commands need no env/flags.
arkclaw login [space-url]	Browser SSO login. Uses init defaults if you omit the URL. --transport a2a --endpoint <url> for an agent endpoint. --clawid ci-... sets a default claw. Bare arkclaw login re-logs into the previous space.
arkclaw agents	List the agents in your accessible claws (verified over the ws; inaccessible claws are pruned). Candidate claws = the ones you've used from this machine + your default — add one by chatting it once (arkclaw chat ci-...). Not a space-wide directory.
arkclaw agents create	Create a named agent in a claw: --name --role --soul (+ optional --description, repeatable --skill). Then chat <claw> --agent <agentId>.
arkclaw agents delete <agent>	Delete a named agent by agentId (a-...) or display name. Asks for confirmation unless --yes; the main agent is protected.
arkclaw chat [TARGET] [MSG]	Chat. TARGET = a claw id (ci-...), an agent name (from agents), or a profile. With MSG → one-shot; without → interactive REPL. -f attach files, -o write the reply, --session NAME name the conversation, --approve-all auto-approve tool runs.
arkclaw <name>	Shortcut: arkclaw 答疑助手 ≡ arkclaw chat 答疑助手.
arkclaw ls [path]	No path → the claw's managed brain files. With path → that workspace directory over Silk (the real filesystem).
arkclaw pull <name> [local]	Download a managed file to local disk.
arkclaw push <local> [name]	Write a local text file into a managed file.
arkclaw upload <local> [remote]	Upload any file into the claw's workspace filesystem (Silk). Defaults to the basename at the workspace root.
arkclaw download <remote> [local]	Download a workspace file from the claw (Silk); a directory comes as <name>.tar.
arkclaw mkdir <path>	Create a directory in the claw workspace (Silk; parent must exist).
arkclaw netdisk <cmd>	IDS netdisk (large products/videos), a separate storage plane: create-space / ls / upload / download / mkdir / rm. Configured via IDS_* env.
arkclaw fanout "<msg>" --clawid ci-a --clawid ci-b	Same message to many claws in parallel.
arkclaw sessions [claw]	An agent's conversations from the server (--agent to pick one), newest first — resume with chat --session <会话ID>, read with history <会话ID>, fork with --new. Falls back to the local record when offline / a2a.
arkclaw history <session>	Print a past conversation's full transcript (ws chat.history). <session> = a 会话ID from sessions, a label, or a full agent:… key. Tool steps hidden unless --show-tools; --json dumps every message; -o writes a plain-text log. openclaw only.
arkclaw profile save/use/list	Named snapshots of the session config (multi-space / multi-claw).
arkclaw doctor	Self-check: login freshness, keychain, pool/STS/endpoint reachability.
arkclaw schema --json	Machine-readable command surface (for agents/tooling).
arkclaw claw list/describe/create/delete	Fleet management on the control plane.

All commands accept --clawid ci-... (where relevant) to target a specific claw, and --json for machine output.

---

Chatting

arkclaw chat ci-xxxx                       # REPL with that claw (Ctrl-C: interrupt turn; twice: exit)
arkclaw chat ci-xxxx -m "你好"             # one-shot
arkclaw chat 答疑助手 -m "怎么部署"         # by name (names come from `arkclaw agents`)
echo "$DATA" | arkclaw chat ci-xxxx --json -m "总结" | jq -r .data.reply   # piped, machine
arkclaw chat ci-xxxx -f notes.md -m "review" -o out.md   # attach context, save reply

• Streaming on both transports; until the first token a spinner shows elapsed time + the running tool.
• Sessions are server-side — --session NAME keeps a named conversation that survives CLI restarts.
• Tool approvals: in a terminal you're prompted; headless it fails closed (deny) unless --approve-all; a ~/.arkclaw/cmdpolicy.json deny-list always wins.

---

Files & storage

The CLI moves files across three distinct planes — pick by what you're carrying:

Plane	Commands	What lives there
Managed brain	ls · pull · push	The claw's own config files (AGENTS.md, SOUL.md, …). A fixed allow-list, not a general store.
Workspace (Silk)	ls <path> · upload · download · mkdir	The claw's real working filesystem — arbitrary files, uploads, agent outputs, subdirectories.
Netdisk (IDS)	netdisk …	A separate large-object store for big products/videos, on a dedicated storage account.

1. Managed brain files — ls / pull / push

The claw's "brain": AGENTS.md, SOUL.md, MEMORY.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md. A fixed allow-list — arbitrary filenames are rejected; push only writes text.

arkclaw ls                          # list them (defaults to your default claw)
arkclaw pull SOUL.md                # download SOUL.md here
arkclaw pull AGENTS.md ./agents.md  # download to a path
arkclaw push ./agents.md AGENTS.md  # write a managed file
arkclaw ls --clawid ci-other        # a different claw

2. Workspace filesystem — upload / download / mkdir / ls <path>

The claw's real working filesystem (/root/.openclaw/workspace), over the Silk file service. Paths are workspace-relative. Use it to feed an agent input files and to retrieve whatever it produces.

arkclaw upload ./input.png             # → workspace root (basename)
arkclaw upload ./data.csv runs/data.csv  # → a subpath
arkclaw mkdir runs                     # parent must exist (non-recursive)
arkclaw ls runs                        # list a workspace directory
arkclaw download runs/output.mp4 ./out.mp4   # pull a result back
arkclaw download runs ./runs.tar       # a directory downloads as a .tar

• Requires a Silk-enabled claw. A claw you can chat but that isn't provisioned into Silk is rejected with a clear "未启用文件服务(Silk)" error (ErrClawInstanceNotFound); Silk runs the same per-user gate as chat.
• Upload cap is server-side (~25 MB per file); larger uploads return a clear "文件超出上传上限" error.
• There is no rm here — workspace deletes aren't exposed as a command.

3. Netdisk (IDS) — netdisk …

A separate storage plane for large products/videos, on a dedicated IDS account (not your SSO identity). Configured entirely from IDS_* env vars (provisioned by the storage team). Create a space once, then pass its SpaceID:

arkclaw netdisk create-space my-space            # → prints the SpaceID
arkclaw netdisk mkdir outputs --space spc-...
arkclaw netdisk upload ./final.mp4 outputs/final.mp4 --space spc-...
arkclaw netdisk ls outputs/ --space spc-...
arkclaw netdisk download outputs/final.mp4 ./final.mp4 --space spc-...
arkclaw netdisk rm outputs/final.mp4 --space spc-...   # asks unless --yes

create-space also takes --description; ls takes --limit N to cap entries.

Env	Purpose
IDS_BASE_URL / IDS_REGION / IDS_SERVICE / IDS_INSTANCE_ID	Endpoint + routing for the IDS instance.
IDS_AK / IDS_SK (+ IDS_ACCOUNT_ID)	Static credentials for the storage account…
IDS_ROLE_TRN	…or assume a role via SSO instead of static AK/SK.

---

For agents / automation

• --json → stdout is exactly one {ok, data, error} document; progress/streaming goes to stderr. Pipe to jq.
• Exit codes: 0 ok · 1 api · 2 validation · 3 auth · 4 network · 5 internal.
• Headless never blocks: --json / piped stdin refuse the interactive REPL; tool approvals fail closed.
• arkclaw schema --json describes every command + option for programmatic discovery.

---

Identity & security

• Identity-through, zero permanent secrets. Browser PKCE (S256, public client, loopback) → a short-lived id_token that is your user identity (same as the web app), auto-refreshed. The claw sees you, not a shared key.
• openclaw path exchanges that token (via a least-privilege STS role that can do exactly GetClawInstanceChatToken) for a one-time ChatToken, then connects over wss. a2a presents the token directly to the agent's gateway.
• Tokens live in the OS keychain (0600 file fallback). The config file holds only non-secret routing. Every upstream error is redacted (tokens / AK-SK) before display.

---

Configuration

login resolves config in this order: explicit flag → ARKCLAW_* env → the space's published discovery → arkclaw init defaults → derived from the address. You normally only type the address.

The easy way — arkclaw init asks once (interactively) for whatever the space doesn't yet auto-publish, and saves it. After that, just arkclaw login.

The env way (scripts/CI, or instead of init) — supply the same non-secret values via env:

Env	Purpose
ARKCLAW_CLIENT_ID	The CLI's public OAuth client id for the pool.
ARKCLAW_ROLE_TRN	STS role that mints the ChatToken (openclaw).
ARKCLAW_REGION / ARKCLAW_SPACE_ID	Override region / space (usually auto).
ARKCLAW_API_HOST / ARKCLAW_API_SERVICE	Advanced/testing. Point the control-plane calls at a non-production plane (host + SigV4 service). See the note below.

Other config: ~/.arkclaw/defaults.json (init answers, 0600), ~/.arkclaw/session.json (routing, 0600), ~/.arkclaw/cmdpolicy.json (tool-approval allow/deny), OS keychain (tokens).

Escape hatch (admin/test): arkclaw login <url> --transport openclaw --static-creds uses VOLCENGINE_ACCESS_KEY/SECRET_KEY from the env instead of SSO — convenient for CI, but it's account-level keys, not identity-through.

Control-plane override (advanced/testing): by default every control-plane call (chat/terminal token mints, file/fleet actions, doctor) targets arkclaw.<region>.volcengineapi.com with SigV4 service arkclaw. Setting ARKCLAW_API_HOST + ARKCLAW_API_SERVICE retargets them — e.g. a non-production plane. The service is also the IAM action prefix, so a non-default service needs the matching role permissions. The host receives the signed request including live temporary credentials, so it must be a host you trust — only *.volcengineapi.com is accepted.

---

Notes

• ls/pull/push, upload/download/mkdir, and a bare chat use your default claw (set at login, or the last one you opened in the browser); override with --clawid (or chat ci-...).
• pull/push reach the claw's managed files; upload/download reach its workspace filesystem (Silk, arbitrary files); netdisk … is a separate storage plane on its own account.
• Nothing is hardcoded per space — the CLI reads what the space serves.