ape-claw 0.1.3 → 0.1.5

package/docs/operator/09-env-reference.md

@@ -56,6 +56,39 @@ This document lists all environment variables used by ApeClaw, organized by comp
 | `APE_CLAW_INVITE_MAX_USES` | Maximum uses per invite token | No | `5` |
 | `APE_CLAW_POD_DIR` | Pod workspace directory path | No | Auto-detected |
 
+## Forge Agent Variables
+
+The forge agent auto-detects your LLM provider. Set **any one** of the API key variables below — the first one found is used.
+
+**LLM Provider (set one):**
+
+| Variable | Provider | Default Model |
+|----------|----------|---------------|
+| `PERPLEXITY_API_KEY` | Perplexity Sonar (web-grounded) | `sonar-pro` |
+| `OPENAI_API_KEY` | OpenAI | `gpt-4o` |
+| `ANTHROPIC_API_KEY` | Anthropic Claude | `claude-sonnet-4-20250514` |
+| `GROQ_API_KEY` | Groq | `llama-3.3-70b-versatile` |
+| `TOGETHER_API_KEY` | Together AI | `meta-llama/Llama-3.3-70B-Instruct-Turbo` |
+| `OLLAMA_HOST` | Ollama (local, no key needed) | `llama3.2` |
+
+**Explicit override (any OpenAI-compatible endpoint):**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FORGE_LLM_API_URL` | Full chat completions URL | Auto-detected from provider |
+| `FORGE_LLM_API_KEY` | API key for custom endpoint | Auto-detected from provider |
+| `FORGE_LLM_MODEL` | Model name override | Auto-detected from provider |
+
+**Agent identity:**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FORGE_AGENT_ID` | ClawBot agent ID | `"the-clawllector"` |
+| `FORGE_AGENT_TOKEN` | Pre-provisioned ClawBot token for verified identity | Auto-registers on startup |
+| `FORGE_AGENT_NAME` | Display name shown in chat | `"The Clawllector"` |
+
+Without any LLM key the endpoint returns 503 and the forge chat falls back to the basic `/api/chat` relay.
+
 ## External Service Variables
 
 | Variable | Description | Required | Default |
@@ -117,6 +150,34 @@ export APE_CLAW_CORS_ORIGINS=https://apeclaw.ai
 export APE_CLAW_STORAGE=file  # or "sqlite"
 ```
 
+### Forge Agent (Local) — pick any provider
+
+```bash
+# Option A: OpenAI
+export OPENAI_API_KEY=sk-...
+
+# Option B: Anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Option C: Perplexity
+export PERPLEXITY_API_KEY=pplx-...
+
+# Option D: Groq (free tier available)
+export GROQ_API_KEY=gsk_...
+
+# Option E: Local Ollama (no key needed)
+export OLLAMA_HOST=http://localhost:11434
+
+# Option F: Any OpenAI-compatible endpoint
+export FORGE_LLM_API_URL=https://your-endpoint.com/v1/chat/completions
+export FORGE_LLM_API_KEY=your-key
+export FORGE_LLM_MODEL=your-model
+
+# Optional identity overrides:
+export FORGE_AGENT_NAME="My Bot"
+export FORGE_AGENT_ID=my-forge-bot
+```
+
 ### Pod Operations
 
 ```bash

package/docs/social/STARTER_PACK_THREAD.md

@@ -15,7 +15,7 @@ Press Enter. 61 skills load in about four seconds.
 That's it. You have a working agent. No browsing a marketplace for an hour.
 
 ```
-npx ape-claw skill install --scope local
+npx ape-claw skill install
 ```
 
 Here's what you actually get (thread)
@@ -152,8 +152,8 @@ Still in the library at apeclaw.ai/skills. Just not in the box you get on day on
 
 The prompt defaults to yes, but you have options:
 
-npx ape-claw skill install --scope local --starter-pack installs without asking
-npx ape-claw skill install --scope local --no-starter-pack skips it
+npx ape-claw skill install --starter-pack installs without asking
+npx ape-claw skill install --no-starter-pack skips it
 No flag means it asks you
 
 You can install it later. You can also skip it entirely and pick from 10,000+ skills one at a time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ape-claw",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "ApeChain bridge and NFT execution CLI with telemetry for OpenClaw agents",
   "license": "MIT",
   "repository": {

package/src/cli.mjs

@@ -144,15 +144,15 @@ function installApeClawSkill(args) {
     throw new Error(`Source skill missing at ${sourceSkillPath}`);
   }
 
-  const scope = String(args.scope || "local").toLowerCase();
+  const scope = String(args.scope || "global").toLowerCase();
   const explicitSkillsDir = args["skills-dir"] ? String(args["skills-dir"]) : "";
   let skillsRoot;
   if (explicitSkillsDir) {
     skillsRoot = path.resolve(explicitSkillsDir);
     if (skillsRoot.includes("\0")) throw new Error("Invalid skills-dir path");
   }
-  else if (scope === "global") skillsRoot = path.join(os.homedir(), ".openclaw", "skills");
-  else skillsRoot = path.join(process.cwd(), ".cursor", "skills");
+  else if (scope === "local") skillsRoot = path.join(process.cwd(), ".cursor", "skills");
+  else skillsRoot = path.join(os.homedir(), ".openclaw", "skills");
 
   const targetSkillDir = path.join(skillsRoot, "ape-claw");
   const targetSkillPath = path.join(targetSkillDir, "SKILL.md");
@@ -211,6 +211,15 @@ function installApeClawSkill(args) {
   };
 }
 
+function yamlSafe(val) {
+  const s = String(val);
+  if (!s) return '""';
+  if (/[:{}\[\]#&*!|>'"%@`,\n]/.test(s) || s.startsWith(" ") || s.endsWith(" ")) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
 function syncSkillToOpenClaw(cardObj, slug, skillsRoot) {
   const s = String(slug || cardObj?.slug || cardObj?.name || "").toLowerCase().trim()
     .replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -218,11 +227,15 @@ function syncSkillToOpenClaw(cardObj, slug, skillsRoot) {
   const rawDoc = String(cardObj?.documentation_md || "").trim();
   const displayName = String(cardObj?.name || s).trim();
   const versionValue = String(cardObj?.version || "1.0.0").trim();
-  const descriptionValue = String(cardObj?.description || "").trim();
+  let descriptionValue = String(cardObj?.description || "").trim();
+  // Strip embedded YAML frontmatter that some imported skills have in their description
+  if (descriptionValue.startsWith("---")) {
+    descriptionValue = descriptionValue.replace(/^---[\s\S]*?---\s*/, "").trim();
+  }
+  if (!descriptionValue) descriptionValue = String(cardObj?.desc || displayName);
   const descOneLine = descriptionValue.replace(/\n/g, " ").slice(0, 300);
 
-  // OpenClaw expects: name = slug, description in frontmatter
-  const openclawFrontmatter = `---\nname: ${s}\nversion: ${versionValue}\ndescription: ${descOneLine}\n---\n`;
+  const openclawFrontmatter = `---\nname: ${s}\nversion: ${yamlSafe(versionValue)}\ndescription: ${yamlSafe(descOneLine)}\n---\n`;
 
   let content;
   if (rawDoc) {
@@ -237,7 +250,8 @@ function syncSkillToOpenClaw(cardObj, slug, skillsRoot) {
   fs.mkdirSync(skillDir, { recursive: true });
   fs.writeFileSync(path.join(skillDir, "SKILL.md"), content, "utf8");
 
-  const openclawWorkspaceSkills = path.join(os.homedir(), ".openclaw", "workspace", "skills", s);
+  const homeDir = process.env.OPENCLAW_HOME || os.homedir();
+  const openclawWorkspaceSkills = path.join(homeDir, ".openclaw", "workspace", "skills", s);
   try {
     fs.mkdirSync(openclawWorkspaceSkills, { recursive: true });
     fs.writeFileSync(path.join(openclawWorkspaceSkills, "SKILL.md"), content, "utf8");
@@ -365,6 +379,63 @@ function safeSkillVersion(v) {
   return s;
 }
 
+const TRUSTED_SKILL_API_HOSTS = new Set(["apeclaw.ai", "www.apeclaw.ai", "api.apeclaw.ai"]);
+
+function resolveSkillApiBase(args = {}) {
+  const explicit = String(args.api || "").trim();
+  const fromEnv = String(process.env.APE_CLAW_API_URL || "").trim();
+  const raw = explicit || fromEnv || "https://apeclaw.ai";
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new Error(`Invalid APE_CLAW_API_URL: ${raw}`);
+  }
+  const isLoopback = u.hostname === "localhost" || u.hostname === "127.0.0.1";
+  if (u.protocol !== "https:" && !(isLoopback && Boolean(args["allow-insecure-api"]))) {
+    throw new Error("Remote skill API must use HTTPS. For local dev only, use --allow-insecure-api with localhost.");
+  }
+  if (!TRUSTED_SKILL_API_HOSTS.has(u.hostname) && !Boolean(args["allow-custom-api"])) {
+    throw new Error(`Untrusted skill API host: ${u.hostname}. Use --allow-custom-api to override.`);
+  }
+  return u.origin.replace(/\/+$/, "");
+}
+
+function assertRemoteSkillCardSafe({ requestedSlug, card, skillMeta = null, asJson = false, allowUnvetted = false, allowHighRisk = false }) {
+  if (!card || typeof card !== "object") throw new Error("Remote API returned invalid skill card object");
+  const normalizedRequested = toSlug(requestedSlug);
+  const normalizedCardSlug = toSlug(card.slug || card.name || "");
+  if (!normalizedCardSlug) throw new Error("Remote skill card missing slug/name");
+  if (normalizedCardSlug !== normalizedRequested) {
+    throw new Error(`Remote skill slug mismatch (requested=${normalizedRequested}, received=${normalizedCardSlug})`);
+  }
+  const version = safeSkillVersion(card.version || "1.0.0");
+  if (!version) throw new Error("Remote skill version is invalid");
+  const description = String(card.description || "").trim();
+  if (!description) throw new Error("Remote skill description is required");
+  const documentation = String(card.documentation_md || "");
+  if (Buffer.byteLength(documentation, "utf8") > 300_000) {
+    throw new Error("Remote skill documentation is too large (>300KB)");
+  }
+  if (/[\x00-\x08\x0B\x0C\x0E-\x1F]/.test(documentation)) {
+    throw new Error("Remote skill documentation contains control characters");
+  }
+
+  const metaRiskTierRaw = Number(skillMeta?.riskTier ?? card?.constraints?.riskTier ?? card?.riskTier ?? 2);
+  const metaRiskTier = Number.isFinite(metaRiskTierRaw) ? Math.max(1, Math.min(3, Math.round(metaRiskTierRaw))) : 2;
+  if (metaRiskTier >= 3 && !allowHighRisk) {
+    throw new Error(`Remote skill risk tier ${metaRiskTier} requires explicit --allow-high-risk`);
+  }
+  // If API metadata is present, require vetting by default.
+  if (skillMeta && skillMeta.vettedOk !== true && !allowUnvetted) {
+    throw new Error("Remote skill is not vetted. Use --allow-unvetted to install anyway.");
+  }
+
+  if (!asJson && skillMeta && skillMeta.vettedOk === true) {
+    console.log("\x1b[2m  Security: vetted skill metadata confirmed by API.\x1b[0m");
+  }
+}
+
 function resolveBundledSkillFile(packageRoot, slug) {
   const skillsDataDir = path.join(packageRoot, "data", "skills");
   const target = path.join(skillsDataDir, `${slug}.json`);
@@ -389,16 +460,35 @@ function resolveBundledSkillFile(packageRoot, slug) {
   return "";
 }
 
-async function fetchSkillFromApi(slug) {
-  const apiBase = process.env.APE_CLAW_API_URL || "https://apeclaw.ai";
-  const url = `${apiBase}/api/skills/${encodeURIComponent(slug)}`;
+async function fetchSkillFromApi(slug, args = {}) {
+  const apiBase = resolveSkillApiBase(args);
+  const url = `${apiBase}/api/skills/get?slug=${encodeURIComponent(slug)}`;
   try {
     const res = await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(15000) });
-    if (!res.ok) return null;
+    if (!res.ok) return { card: null, skillMeta: null, url, apiBase };
     const json = await res.json();
-    return json?.card || json?.skill || json || null;
+    if (!json?.ok) return { card: null, skillMeta: null, url, apiBase };
+
+    const skillMeta = json?.skill && typeof json.skill === "object" ? json.skill : null;
+    // Prefer the full card JSON; fall back to synthesising a minimal card from index metadata
+    let card = json?.card && typeof json.card === "object" ? json.card : null;
+    if (!card && skillMeta) {
+      card = {
+        name: skillMeta.name || slug,
+        slug: skillMeta.slug || slug,
+        version: "1.0.0",
+        description: skillMeta.description || skillMeta.name || slug,
+        riskTier: skillMeta.riskTier ?? 2,
+        provenance: skillMeta.provenance || { publisher: "imported", signed: false },
+        constraints: { riskTier: skillMeta.riskTier ?? 2 },
+        documentation_md: skillMeta.description
+          ? `# ${skillMeta.name || slug}\n\n${skillMeta.description}`
+          : `# ${skillMeta.name || slug}\n`,
+      };
+    }
+    return { card, skillMeta, url, apiBase };
   } catch {
-    return null;
+    return { card: null, skillMeta: null, url, apiBase };
   }
 }
 
@@ -411,7 +501,8 @@ function resolveHumanizerDependencySlug(packageRoot) {
 }
 
 function installOpenClawSkillCard(cardObj, fallbackSlug = "") {
-  const skillsRoot = path.join(ROOT, ".cursor", "skills");
+  const homeDir = process.env.OPENCLAW_HOME || os.homedir();
+  const skillsRoot = path.join(homeDir, ".openclaw", "skills");
   return syncSkillToOpenClaw(cardObj, fallbackSlug, skillsRoot);
 }
 
@@ -607,7 +698,16 @@ async function main() {
       } catch (bundledErr) {
         // Not in bundled data — fetch from API
         if (!asJson) console.log(`\x1b[2m  Skill not bundled locally, fetching from API…\x1b[0m`);
-        const card = await fetchSkillFromApi(requestedSkillSlug);
+        let remote;
+        try {
+          remote = await fetchSkillFromApi(requestedSkillSlug, args);
+        } catch (apiErr) {
+          if (asJson) return print({ ok: false, error: `Skill "${requestedSkillSlug}" rejected: ${apiErr.message}` }, true);
+          console.error(`\x1b[31m  ✗ ${apiErr.message}\x1b[0m`);
+          process.exitCode = 1;
+          return;
+        }
+        const card = remote?.card || null;
         if (!card || typeof card !== "object" || (!card.name && !card.slug)) {
           if (asJson) return print({ ok: false, error: `Skill "${requestedSkillSlug}" not found (bundled: ${bundledErr.message}, API: not found)` }, true);
           console.error(`\x1b[31m  ✗ Skill "${requestedSkillSlug}" not found in bundled library or API.\x1b[0m`);
@@ -615,6 +715,22 @@ async function main() {
           process.exitCode = 1;
           return;
         }
+        try {
+          assertRemoteSkillCardSafe({
+            requestedSlug: requestedSkillSlug,
+            card,
+            skillMeta: remote?.skillMeta || null,
+            asJson,
+            allowUnvetted: Boolean(args["allow-unvetted"]),
+            allowHighRisk: Boolean(args["allow-high-risk"]),
+          });
+        } catch (safeErr) {
+          if (asJson) return print({ ok: false, error: safeErr.message }, true);
+          console.error(`\x1b[31m  ✗ ${safeErr.message}\x1b[0m`);
+          console.error(`\x1b[2m    Use --allow-unvetted and/or --allow-high-risk only if you trust this source.\x1b[0m`);
+          process.exitCode = 1;
+          return;
+        }
         // Write fetched card to a temp file and install it
         const tmpDir = path.join(packageRoot, "data", "skills");
         fs.mkdirSync(tmpDir, { recursive: true });
@@ -2184,7 +2300,7 @@ async function main() {
       "bridge execute (autonomous)": "ape-claw bridge execute --request <requestId> --execute --autonomous --json",
       "bridge status": "ape-claw bridge status --request <requestId> --json",
       "allowlist audit": "ape-claw allowlist audit --json",
-      "skill install": "ape-claw skill install [<slug>] [--scope local] [--starter-pack | --no-starter-pack] --json",
+      "skill install": "ape-claw skill install [<slug>] [--scope local] [--starter-pack | --no-starter-pack] [--allow-unvetted] [--allow-high-risk] [--allow-custom-api] [--allow-insecure-api] --json",
       "v2 skill mint": "ape-claw v2 skill mint --rpc <url> --privateKey 0x... --skillNft 0x... --registry 0x... [--parentId 0] [--royalty-receiver 0x... --royalty-bps 500] --json",
       "v2 skill publish": "ape-claw v2 skill publish --rpc <url> --privateKey 0x... --registry 0x... --skillId <id> --file <skillcard.json> [--uri ipfs://...] [--riskTier 1] --json",
       "v2 intent create": "ape-claw v2 intent create --rpc <url> --privateKey 0x... --intents 0x... --payload '{...}' [--expiresAt <unixSec>] --json",

package/src/server/index.mjs

@@ -30,6 +30,7 @@ import {
   handleChatStream, handleChatGet, handleChatRooms,
   handleChatPost, handleChatReact,
 } from "./routes/chat.mjs";
+import { handleForgeChat, handleForgeStatus, initForgeAgent } from "./routes/forge-agent.mjs";
 import { handleV2ReceiptGet, handleV2Config } from "./routes/v2.mjs";
 import { handlePodStatus, handlePodStop, handlePodFiles, handleStarterPack } from "./routes/pod.mjs";
 import {
@@ -41,7 +42,7 @@ import {
   handleIndex, handleStaticFile,
 } from "./routes/static.mjs";
 
-const PORT = Number(process.env.APE_CLAW_UI_PORT || 8787);
+const PORT = Number(process.env.PORT || process.env.APE_CLAW_UI_PORT || 8787);
 const BIND_HOST = String(process.env.APE_CLAW_BIND_HOST || "").trim();
 
 const RL_READ = { limit: 60, windowMs: 60_000, keyPrefix: "read" };
@@ -58,7 +59,8 @@ if (!process.env.OPENSEA_API_KEY) {
 
 initStorage();
 initSseBroadcast();
-logger.info("Storage initialized, SSE broadcast active");
+initForgeAgent();
+logger.info("Storage initialized, SSE broadcast active, forge agent ready");
 
 function safeHandler(fn) {
   return (req, res, ...args) => {
@@ -122,6 +124,8 @@ const server = http.createServer((req, res) => {
   if (pathname === "/api/invites/create" && req.method === "POST") return safeHandler(handleInviteCreate)(req, res);
   if (pathname === "/api/clawbots/register" && req.method === "POST") return safeHandler(handleClawbotsRegister)(req, res);
   if (pathname === "/api/events" && req.method === "POST") return safeHandler(handlePostEvent)(req, res);
+  if (pathname === "/api/forge/status" && req.method === "GET") return safeHandler(handleForgeStatus)(req, res);
+  if (pathname === "/api/forge/chat" && req.method === "POST") return safeHandler(handleForgeChat)(req, res);
   if (pathname === "/api/chat/stream") return safeHandler(handleChatStream)(req, res, reqUrl);
   if (pathname === "/api/chat" && req.method === "GET") return safeHandler(handleChatGet)(req, res, reqUrl);
   if (pathname === "/api/chat/rooms" && req.method === "GET") return safeHandler(handleChatRooms)(req, res, reqUrl);