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).
• Schedule tasks — arkclaw cron makes the claw run a prompt unattended on a cron expression / fixed interval / one-shot time (add / list / run / runs / update / rm), over the runtime's cron.* RPCs.
• Configure ESA connectors — arkclaw mcp lists, installs, and removes MCP connectors for an Enterprise Service Agent.
• 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 it) the CLI client. 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

Every targetable command pairs --clawid ci-... with --esaid mi-... (mutually exclusive). These flags override the target for that invocation only and do not change the default saved by login. Every command also accepts --json for machine output.

Enterprise Service Agents (ESA)

An ESA uses the same command surface and an mi-... ID, but a separate AgentKit data plane. Supported today: streaming chat, admin agents, sessions / sessions --new, history, admin pull AGENTS.md, admin Debug-only push, cron, netdisk, and MCP connector configuration. Add --debug to data-plane commands to target the Debug runtime. ESA chat does not accept --file or piped stdin yet; ESA has no Silk workspace or terminal, and its single agent cannot be created, deleted, or deployed from the CLI.

Chatting

arkclaw chat ci-xxxx                       # REPL with that claw (Ctrl-C: interrupt turn; twice: exit)
arkclaw chat ci-xxxx -m "你好"             # one-shot
arkclaw chat ci-xxxx --agent a-yyyy --debug -m "你好"   # use that agent's debug target if present
arkclaw chat mi-xxxx -m "你好"             # ESA: continue the newest session
arkclaw chat --esaid mi-xxxx -m "你好"     # temporarily override the saved default ESA
arkclaw chat mi-xxxx --new --debug -m "测试" # ESA: create a fresh Debug session
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 OpenClaw conversation. For ESA it accepts the full ID or the unique prefix shown by sessions; no option continues the newest session, while --new creates one.
• 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:

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. Credentials are minted per-user from your SSO login — no static AK/SK: the claw's iDrive instance is resolved and a minimal-permission temp credential is issued for your UserPoolUserUid (GetIDriveInstance → GetIDriveCredential). --space defaults to the claw's iDrive space; pass it to target another.

arkclaw netdisk ls                                # the claw's iDrive space
arkclaw netdisk upload ./final.mp4 outputs/final.mp4
arkclaw netdisk download outputs/final.mp4 ./final.mp4
arkclaw netdisk mkdir outputs
arkclaw netdisk rm outputs/final.mp4              # asks unless --yes
arkclaw netdisk create-space my-space             # a second space → prints its SpaceID
arkclaw netdisk ls --space spc-...                # target a specific space

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

Owner self-op (admin AK/SK). If env admin AK/SK is present (VOLCENGINE_ACCESS_KEY / SECRET_KEY, or ARKCLAW_AK / SK), netdisk signs the control plane with those creds directly — no assume-role, no role policy — and auto-resolves the ClawSpace id via ListClawSpaces (matched by your login's UserPool). A warning prints on every call: it's a full-power static secret that can mint any user's creds, so it's for the owner's own operations only, never for end users.

For CI / a dedicated storage account you can still override the identity path:

Scheduled tasks — cron

Let a claw run a prompt unattended on a schedule (its runtime carries a scheduler; check it with arkclaw cron status). A task is an agent turn — the --message is the prompt the agent runs at each fire.

arkclaw cron status                         # is the scheduler on; jobs; next wake
arkclaw cron add --name 早报 \
  --cron "0 9 * * *" --tz Asia/Shanghai \
  -m "联网搜集今天的科技新闻,生成一份中文摘要"   # every day 09:00
arkclaw cron add --name 巡检 --every 30m -m "检查服务健康并报告异常"
arkclaw cron add --name 一次性 --at 2026-07-01T09:00:00+08:00 -m "提醒我项目截止" --delete-after-run
arkclaw cron list                           # all jobs (enabled + disabled)
arkclaw cron run <id>                        # fire one now (server-side)
arkclaw cron runs <id>                       # recent run history + status
arkclaw cron update <id> --disable           # pause; --enable to resume
arkclaw cron rm <id>                         # delete (asks unless --yes)

Schedule is exactly one of --cron "<expr>" (with optional --tz), --every <30s|15m|2h|1d>, or --at <ISO8601>. --session-target picks where the run lives (isolated default / main / current); --agent runs it as a specific agent. Jobs the platform manages (created by an agent-pack template) are marked * in the list — edit those in the console, not here. openclaw plane only.

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 sends that token to the space BFF for temporary credentials, then mints a one-time ChatToken and connects over wss. Role selection stays inside the BFF. 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 discovery → arkclaw init defaults → derived from the address. You normally only type the address — when the space exposes the CLI bootstrap endpoint, login auto-fetches its public OAuth client. The BFF owns role selection, so the CLI no longer carries a role identifier.

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:

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.