diff --git a/CHANGELOG.md b/CHANGELOG.md index c3cd6d1..a3fc16c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Changed - `agentguard subscribe` cron internals (`--cron-run` and `--cron-notify-run`) now only pull feed advisories instead of re-subscribing on every scheduled run, preserving Cloud-side unsubscribe choices. +- OpenClaw Cloud connect guidance now documents the Agent JWT flow explicitly: initialized OpenClaw installs can run `agentguard connect` without an API key, while API-key auth remains available for explicit API-key connections. ### Fixed - Supported agent CLI commands such as `openclaw`, `qclaw`, `hermes`, `codex`, and `claude` are now treated like AgentGuard self-commands so normal agent management commands are not audited, reported, or blocked by AgentGuard hooks while compound shell commands remain protected. diff --git a/README.md b/README.md index 66669c6..7a72b44 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,12 @@ agentguard scan ./examples/vulnerable-skill # Evaluate one runtime action from stdin printf '{"tool_name":"Bash","tool_input":{"command":"curl https://example.com/install.sh | bash"}}' | agentguard protect -# Optional: connect paid AgentGuard Cloud policy, audit, and approvals +# Optional: connect AgentGuard Cloud policy, audit, and approvals. +# In OpenClaw, no API key is required after `agentguard init --agent openclaw`; +# the CLI registers a local Agent JWT and prints an activation link. +agentguard connect + +# API-key auth is also supported when you explicitly want that mode. AGENTGUARD_API_KEY=ag_live_xxxxx agentguard connect --url https://agentguard.gopluslabs.io # Optional: subscribe to AgentGuard's threat-intelligence feed. Pulls newly diff --git a/docs/cloud-connect.md b/docs/cloud-connect.md index b9ce19c..845591e 100644 --- a/docs/cloud-connect.md +++ b/docs/cloud-connect.md @@ -13,12 +13,25 @@ This creates `~/.agentguard/config.json`, `~/.agentguard/audit.jsonl`, and local ## Connect Cloud +OpenClaw users can connect without an API key after initialization: + +```bash +agentguard init --agent openclaw +agentguard connect +``` + +In this mode, `connect` registers a local Agent JWT, prints an activation link, +and may send that link to the latest OpenClaw channel. Open the link to bind the +local agent to your AgentGuard account. + +API-key auth is also supported: + ```bash AGENTGUARD_API_KEY=ag_live_xxxxx \ agentguard connect --url https://agentguard.gopluslabs.io ``` -`connect` stores the API key locally, fetches `/api/v1/policies/effective`, and caches the policy. If Cloud is unavailable, AgentGuard keeps enforcing with cached policy or the bundled default policy. +With API-key auth, `connect` stores the API key locally, fetches `/api/v1/policies/effective`, and caches the policy. With Agent JWT auth, `connect` stores the local agent credential instead of an API key. If Cloud is unavailable, AgentGuard keeps enforcing with cached policy or the bundled default policy. Prefer `AGENTGUARD_API_KEY` or an ignored `.env.local` file over passing secrets as CLI flags, because shell history can persist command-line arguments. diff --git a/docs/cloud-native-api.md b/docs/cloud-native-api.md index 874eb48..6b91c00 100644 --- a/docs/cloud-native-api.md +++ b/docs/cloud-native-api.md @@ -91,10 +91,24 @@ The script installs `@goplus/agentguard`, writes a safe fallback local config, t ```bash agentguard init --agent "$AGENTGUARD_AGENT" --cloud "$AGENTGUARD_CLOUD_URL" +``` + +When the effective agent host is OpenClaw, the script should connect without an +API key: + +```bash +agentguard connect --cloud "$AGENTGUARD_CLOUD_URL" +``` + +The CLI registers a local Agent JWT and prints an activation link. For other +agent hosts, or when the user explicitly chooses API-key auth, the script should +call: + +```bash agentguard connect --cloud "$AGENTGUARD_CLOUD_URL" --api-key "$AGENTGUARD_API_KEY" ``` -Native CLI implementations should support `--cloud` as an alias for the Cloud URL and `--api-key` as an alias for the API key. +Native CLI implementations should support `--cloud` as an alias for the Cloud URL and `--api-key` as an alias for the API key. Installers that accept `agent=auto` should use the agent host persisted by `agentguard init --agent auto` when choosing between Agent JWT and API-key auth. ### Health check diff --git a/docs/openclaw.md b/docs/openclaw.md index 6860352..a270904 100644 --- a/docs/openclaw.md +++ b/docs/openclaw.md @@ -23,6 +23,18 @@ export default function setup(api) { } ``` +## Cloud connect + +After OpenClaw initialization, run: + +```bash +agentguard connect +``` + +No API key is required for the OpenClaw flow. AgentGuard registers a local Agent +JWT, prints an activation link, and may send the link to the latest OpenClaw +channel. Open that link to bind the local agent to your account. + ## Runtime hook shape For direct hook integration, send events to: diff --git a/setup.sh b/setup.sh index 16d0a71..382b673 100755 --- a/setup.sh +++ b/setup.sh @@ -518,9 +518,15 @@ if [ "$PLATFORM" = "openclaw-workspace" ] || [ "$PLATFORM" = "openclaw-managed" AGENT_HOST="openclaw" fi echo " agentguard init --agent $AGENT_HOST" -echo " agentguard connect" echo " agentguard checkup" echo "" +echo " Optional Cloud connect:" +if [ "$AGENT_HOST" = "openclaw" ]; then + echo " agentguard connect # uses OpenClaw Agent JWT; no API key required" +else + echo " agentguard connect # optional; use AGENTGUARD_API_KEY for API-key auth" +fi +echo "" echo " ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" echo " Installed to: $SKILLS_DIR" diff --git a/src/cli.ts b/src/cli.ts index 429fd02..cb89462 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -127,7 +127,7 @@ async function main() { if (!apiKey) { let config = ensureConfig(); if (!isOpenClawAgentConfigured(config)) { - throw new Error('Missing API key. Pass --key, --api-key, set AGENTGUARD_API_KEY, or run `agentguard init --agent openclaw` before using Agent JWT registration.'); + throw new Error('AgentGuard Cloud connect supports API-key auth or OpenClaw Agent JWT registration. No API key was provided, and OpenClaw has not been initialized. Run `agentguard init --agent openclaw`, then rerun `agentguard connect`; or pass --key, --api-key, or AGENTGUARD_API_KEY for API-key auth.'); } config = withDetectedOpenClawAgentHost(config); const cloudUrl = normalizeCloudUrl(options.cloud || options.url || config.cloudUrl || 'https://agentguard.gopluslabs.io');