ali-esa-acme-ssl-skill

# ESA DNS + ACME Certificate Automation

## Design Decision (Important)
This skill **combines acme.sh + ESA DNS** into a single integrated flow, not split into two skills.

Reasons:
1. The two steps are tightly coupled: ACME challenge tokens must be written to ESA DNS immediately.
2. The most common user errors are "validation failed / record written to the wrong panel" — an integrated flow minimizes mistakes.
3. Wildcard scenarios often produce multiple TXT values for the same FQDN; splitting would increase manual synchronization cost.

> If there is significant demand for "DNS-only operations" in the future, a separate `esa-dns-records` helper skill can be extracted.

---

## When to Trigger
Trigger when any of the following apply:
- Domain NS records are on `*.atrustdns.com` (ESA-hosted DNS)
- User says "issue certificate with acme.sh", "Let's Encrypt", "DNS-01"
- Error: `No TXT record found at _acme-challenge...`
- Need to issue `example.com + *.example.com` together
- Need to auto-write ESA DNS records and install to Nginx

---

## Supported Environment

- Linux hosts (recommended: Ubuntu tested)
- System-level Nginx (LNMP tested)
- Docker/containerized environments are not supported
- Not tested on Windows/macOS

## Prerequisites

Install `acme.sh` from the official project before using this skill, and review the installation method you choose instead of piping remote scripts directly to a shell:

- https://github.com/acmesh-official/acme.sh

This skill expects `acme.sh` to be available on `PATH`. The script also falls back to `~/.acme.sh/acme.sh` if present.

Requirements:

- Credentials via `ALIYUN_AK` / `ALIYUN_SK` or `ALIBABACLOUD_ACCESS_KEY_ID` / `ALIBABACLOUD_ACCESS_KEY_SECRET`
- STS token is supported via `ALIYUN_SECURITY_TOKEN`, `ALIBABACLOUD_SECURITY_TOKEN`, or `--sts-token`
- If the user provides credentials directly in OpenClaw chat/TUI as plain `id` / `secret` / `token` values without env names, treat them as generic Alibaba Cloud `AccessKeyId` / `...

# ali-esa-acme-ssl-skill

[Chinese Documentation](README_zh.md)

OpenClaw skill for **automatic HTTPS certificate issuance/renewal** using **Alibaba Cloud ESA DNS + acme.sh**, with optional installation to Nginx.

## What this skill solves

AI models often resolve to the wrong place: they write records to traditional AliDNS, while the correct target should be ESA DNS. These two DNS systems are independent.

In other words, when a domain is hosted on ESA (`*.atrustdns.com`), DNS-01 validation records must be written to ESA DNS, not traditional AliDNS.

## Environment compatibility

- ✅ Linux hosts (Ubuntu tested)
- ✅ System-level Nginx deployments (LNMP tested)
- ❌ Containerized environments (Docker not supported)
- ❌ Windows/macOS not tested

## Project structure

- `SKILL.md` – Trigger rules and usage guidance for the agent
- `scripts/esa_acme_issue.py` – Automation script
- `scripts/i18n/` – Language files (en.json, zh.json, …) for script output
- `evals/evals.json` – Basic evaluation prompts

## acme.sh prerequisite

Install `acme.sh` from the official project before using this skill, and review the installation method you choose instead of piping remote scripts directly to a shell:

- https://github.com/acmesh-official/acme.sh

This skill expects `acme.sh` to be available on `PATH`. The script also falls back to `~/.acme.sh/acme.sh` if present.

## Quick start

### 1) Export credentials

```bash
export ALIYUN_AK='YOUR_AK'
export ALIYUN_SK='YOUR_SK'
export ALIYUN_SECURITY_TOKEN='YOUR_STS_TOKEN'  # optional but recommended
```

The script also accepts Alibaba Cloud style aliases:

```bash
export ALIBABACLOUD_ACCESS_KEY_ID='YOUR_AK'
export ALIBABACLOUD_ACCESS_KEY_SECRET='YOUR_SK'
export ALIBABACLOUD_SECURITY_TOKEN='YOUR_STS_TOKEN'  # optional
```

### 2) Single domain

```bash
python3 scripts/esa_acme_issue.py -d test.example.com
```

### 3) Apex + wildcard

```bash
python3 scripts/esa_acme_issue.py -d example.com -d '*.example.com'
```

### 3.1) Wildcard only...