WordPress API Pro

通过 REST API 管理 WordPress 站点。可作为 OpenClaw 技能运行，也可在 Claude Code 中运行。

在 Claude Code 中运行

该技能直接运行 scripts/*.py 脚本。从技能目录执行（运行 bash INSTALL.sh 后路径为 ~/.claude/skills/wordpress-api-pro/）：

• 认证：导出环境变量 WP_URL / WP_USERNAME / WP_APP_PASSWORD；或多站点场景下使用 config/sites.json 文件。
• 依赖项：ACF / SEO / JetEngine / 插件检测脚本需安装 requests 库（建议在虚拟环境中执行：python3 -m pip install requests）。核心的 post/page/media/WooCommerce/批量脚本仅使用 Python 标准库（stdlib）。
• 本地开发站点（例如 http://site.local）完全支持 —— 私有网络/HTTP 限制仅适用于带 --allow-remote-url 参数的媒体文件下载，不适用于 WP API 的基础 URL。
• 与 Elementor MCP 套件配套使用（claude-elementor-pro）：先用 MCP 构建页面结构，再在此处执行媒体上传、SEO 元数据设置、自定义字段填充及 WooCommerce 相关操作。

安全规则

• 未经用户明确批准，禁止发布或更新线上内容。须确认目标站点、ID、字段及状态。
• 使用最小权限凭证。推荐为所需角色单独创建 WordPress 用户及对应的应用密码（Application Password）。
• 禁止将生产环境凭证提交至代码仓库。尽可能使用环境变量管理凭证。
• 保护配置文件。若创建了 config/sites.json，请确保其仅保留在本地、未被 Git 跟踪，并执行 chmod 600 config/sites.json 设置权限。
• 批量操作默认为预演模式（dry-run）。仅在审阅完预演输出后，才可添加 --execute 参数执行真实变更。
• 默认禁止对全部已配置站点执行操作。仅当用户明确批准所有配置站点时，方可添加 --allow-all 参数。
• 本地文件读取受严格限制。默认情况下，--content-file 和媒体上传功能仅允许从当前工作目录读取文件。如需启用其他安全目录，请设置 WP_ALLOWED_FILE_ROOTS 环境变量。
• 远程媒体 URL 需显式启用。upload_media.py 要求提供 --allow-remote-url 参数或设置 WP_ALLOW_REMOTE_URLS=1，且仅允许 HTTPS 协议，同时屏蔽私有网络及本地网络主机地址。
• 原始 SEO 元数据键名默认触发警告。seo_meta.py 在写入非 Rank Math / Yoast 白名单内的元数据键时，会向 stderr 输出 WARNING。如需改为拒绝写入，可设置 WP_REQUIRE_ALLOWLIST=1。ACF/JetEngine 自定义字段键名不受此限制 —— 其设计本就支持任意键名。
• TTY 环境下交互式发布需二次确认。create_post.py 和 update_post.py 在交互式运行且指定 --status publish 时，会主动提示用户确认。可通过传入 --yes / -y 跳过确认。非交互式/代理（agent）运行模式行为不变。

认证

推荐使用的环境变量：

export WP_URL="https://example.com"
export WP_USERNAME="wp-api-user"
read -rs WP_APP_PASSWORD
export WP_APP_PASSWORD

应用密码（Application Password）设置步骤：

1. 打开 https://your-site.example/wp-admin/profile.php。
2. 为专用 API 用户创建一个新的应用密码。
3. 一次性复制该密码，并将其安全存储于密钥管理器或环境变量中。
4. 不再需要时及时轮换或撤销该密码。

快速开始

读取/列出文章

python3 scripts/get_post.py --post-id 123
python3 scripts/list_posts.py --per-page 10 --status publish

创建草稿

python3 scripts/create_post.py 
  --title "Draft title" 
  --content "Draft content" 
  --status draft

审批后更新文章

python3 scripts/update_post.py 
  --post-id 123 
  --title "Approved title" 
  --content "Approved content" 
  --status draft

安全地从本地文件读取内容

默认情况下，文件必须位于当前工作目录下：

python3 scripts/update_post.py 
  --post-id 123 
  --content-file ./content/post-123.html 
  --status draft

如需启用另一个安全目录：

export WP_ALLOWED_FILE_ROOTS="/absolute/path/to/approved-content"
python3 scripts/update_post.py --post-id 123 --content-file /absolute/path/to/approved-content/post.html

多站点配置

将模板文件复制到本地：

cp config/sites.example.json config/sites.json
chmod 600 config/sites.json

为每个站点使用独立用户，并确保 app_password 值仅保存于本地 config/sites.json 中。

{
  "sites": {
    "sample-site": {
      "url": "https://example.com",
      "username": "wp-api-user",
      "app_password": "",
      "description": "Sample site; put the real credential only in local config/sites.json"
    }
  },
  "groups": {
    "sample": ["sample-site"]
  }
}

CLI 封装脚本

./wp.sh --list-sites
./wp.sh sample-site get-post --id 123
./wp.sh sample-site update-post --id 123 --status draft

组操作需显式指定标志：

./wp.sh sample --execute-group update-post --id 123 --status draft

若组名为 all，则仅在获得用户明确批准后方可添加 --allow-all：

./wp.sh all --execute-group --allow-all update-post --id 123 --status draft

批量操作

批量模式默认为预演模式（dry-run），除非显式传入 --execute 参数：

python3 scripts/batch_update.py 
  --group sample 
  --post-ids 123,456 
  --status draft

审核后执行：

python3 scripts/batch_update.py 
  --group sample 
  --post-ids 123,456 
  --status draft 
  --execute

对全部站点执行操作需显式启用：

python3 scripts/batch_update.py 
  --group all 
  --allow-all 
  --post-ids 123 
  --status draft

媒体上传

本地文件上传，受限于允许的文件根目录：

python3 scripts/upload_media.py 
  --file ./media/image.jpg 
  --title "Image title"

远程 URL 上传，需显式启用且仅支持 HTTPS：

python3 scripts/upload_media.py 
  --file https://cdn.example.com/image.jpg 
  --allow-remote-url 
  --title "Image title"

插件集成

• scripts/detect_plugins.py — 检测 ACF、Rank Math、Yoast、JetEngine 插件是否启用。
• scripts/acf_fields.py — 读写 ACF 字段。
• scripts/seo_meta.py — 读写 Rank Math 和 Yoast SEO 元数据。
• scripts/jetengine_fields.py — 读写 JetEngine 自定义字段。
• scripts/site_audit.py — 无需认证的一级网站审计（PageSpeed / SSL / 安全响应头 / CMS+PHP / SEO 基础项）。仅使用公开探测服务；建议在售前冷启动阶段运行。
• scripts/describe_cpt.py — 发现自定义文章类型（CPT）的 rest_base、分类法（taxonomies）和字段键名（只读）。
• scripts/seed_content.py — 基于 JSON 数据集批量创建 CPT 条目，支持 ACF/Jet 字段、分类法及特色图像。默认为预演模式；需传入 --execute 才执行写入。
• scripts/elementor_content.py — 读取/更新 Elementor 的 _elementor_data 字段。
• scripts/woo_products.py — 管理 WooCommerce 商品。

填充动态内容（CPT）

针对使用 JetEngine/ACF 渲染列表的动态站点，为其填充实际条目：

1. describe_cpt.py --post-type projects — 获取该 CPT 的 rest_base、分类法及字段键名。
2. 编写 JSON 数据集（数组格式，每个元素为 {post_type, title, content, status, terms, featured_image, acf, jet} 对象）。
3. seed_content.py --dataset data.json — 查看预演计划（无任何写入，仅依赖 stdlib）。
4. seed_content.py --dataset data.json --execute — 创建条目（默认创建草稿）。

说明：CPT、分类法及 ACF 字段组必须已在后台预先创建。featured_image 可接受媒体 ID、URL 或本地路径（URL 下载需启用 --allow-remote-url）。--execute 需要 requests 依赖（由 ACF/Jet 写入器调用）。重复运行将产生重复条目（暂不支持 upsert）。

上线写入前的校验

执行任何线上写入操作前，请务必完成以下检查：

1. 确认站点 URL 正确无误。
2. 确认文章/页面/商品 ID 准确。
3. 确认字段值与状态符合预期。
4. 除非用户明确批准发布（publish），否则优先使用 draft 状态。
5. 对批量操作始终先执行预演（dry-run）。
6. 对关键内容保留备份或导出副本。