tool-scripts

Writing Tool Scripts

When creating tool scripts for OpenClaw agents, follow these patterns.

Rules

1. Zero npm dependencies. Use only Node.js built-ins: https, fs, path, crypto.
2. CommonJS format. Use .cjs extension and require().
3. Self-contained. Each script must work standalone with node tools/script.cjs.
4. Accept CLI arguments. Date ranges, flags, output format.
5. Print to stdout. The agent captures stdout. Use console.log() for output, console.error() for errors.

Template

#!/usr/bin/env node
// Tool Name — Short description
// Usage: node tool-name.cjs [date] [--json]
// Requires: API_KEY in .env or secrets/
const https = require("https");
const path = require("path");
const fs = require("fs");

// Load config
const envPath = path.resolve(__dirname, "../secrets/.env");
if (fs.existsSync(envPath)) {
  fs.readFileSync(envPath, "utf-8").split("\n").forEach(line => {
    const [k, ...v] = line.split("=");
    if (k && !k.startsWith("#")) process.env[k.trim()] = v.join("=").trim();
  });
}

const API_KEY = process.env.API_KEY;
if (!API_KEY) { console.error("Set API_KEY in secrets/.env"); process.exit(1); }

// HTTP helper — works with any JSON API
function httpGet(url, headers = {}) {
  return new Promise((resolve, reject) => {
    const u = new URL(url);
    const req = https.request({
      hostname: u.hostname,
      path: u.pathname + u.search,
      method: "GET",
      headers: { "User-Agent": "OpenClaw-Agent/1.0", ...headers },
      timeout: 15000,
    }, res => {
      let body = "";
      res.on("data", d => body += d);
      res.on("end", () => {
        try { resolve(JSON.parse(body)); }
        catch { resolve(body); }
      });
    });
    req.on("error", reject);
    req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
    req.end();
  });
}

function httpPost(url, headers, data) {
  return new Promise((resolve, reject) => {
    const body = typeof data === "string" ? data : JSON.stringify(data);
    const u = new URL(url);
    const req = https.request({
      hostname: u.hostname,
      path: u.pathname + u.search,
      method: "POST",
      headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body), ...headers },
      timeout: 15000,
    }, res => {
      let b = "";
      res.on("data", d => b += d);
      res.on("end", () => {
        try { resolve(JSON.parse(b)); }
        catch { resolve(b); }
      });
    });
    req.on("error", reject);
    req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
    req.write(body);
    req.end();
  });
}

// Date helpers
const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
const date = process.argv[2] || yesterday;
const jsonOutput = process.argv.includes("--json");

async function main() {
  // Your tool logic here
  const data = await httpGet(`https://api.example.com/data?date=${date}`);

  if (jsonOutput) {
    console.log(JSON.stringify(data, null, 2));
  } else {
    console.log(`Report for ${date}`);
    console.log("=".repeat(40));
    // Format and print results
  }
}

main().catch(e => { console.error("Fatal:", e.message); process.exit(1); });