@laitszkin/apollo-toolkit 2.6.0 → 2.7.0

package/AGENTS.md

@@ -38,6 +38,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can publish structured GitHub issues or feature proposals with auth fallbacks.
 - Users can prepare and open open-source pull requests from existing changes.
 - Users can generate storyboard image sets from chapters, novels, articles, or scripts.
+- Users can configure OpenClaw from official documentation, including `~/.openclaw/openclaw.json`, skills loading, SecretRefs, CLI edits, and validation or repair workflows.
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
 - Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
 - Users can process GitHub pull request review comments and resolve addressed threads.

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.7.0] - 2026-03-20
+
+### Added
+- Add `openclaw-configuration` for explaining, editing, validating, and troubleshooting OpenClaw configuration from the current official docs, including `~/.openclaw/openclaw.json`, skills config, secrets, and CLI workflows.
+- Add bundled OpenClaw configuration references covering the official doc map, config option guide, and operational best practices.
+
+### Changed
+- Update `fix-github-issues` to require temporary worktree and local branch cleanup as part of direct-push or PR completion, with explicit cleanup verification before finishing.
+- Update `learn-skill-from-conversations` to treat post-completion cleanup or finalization follow-ups as evidence that the owning workflow's done criteria need tightening.
+- Update the repository skill inventory and project capability docs to include OpenClaw configuration support.
+
 ## [v2.6.0] - 2026-03-20
 
 ### Added

package/README.md

@@ -31,6 +31,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - open-github-issue
 - open-source-pr-workflow
 - openai-text-to-image-storyboard
+- openclaw-configuration
 - record-spending
 - resolve-review-comments
 - review-change-set

package/fix-github-issues/SKILL.md

@@ -16,8 +16,8 @@ description: Resolve issues from remote GitHub repositories via GitHub CLI (`gh`
 
 - Evidence: Verify repository context, fetch remote issue details, and derive expected behavior from issue text before coding.
 - Execution: Select the issue, open an isolated worktree by default, fix it through `systematic-debug`, validate locally, then hand off to the delivery workflow that matches the user's request.
-- Quality: Keep scope limited to the selected issue, capture exact validation commands, and preserve issue linkage in the final PR or commit message.
-- Output: Finish with either a linked PR or a direct pushed commit, then clean up the temporary worktree when the work is complete.
+- Quality: Keep scope limited to the selected issue, capture exact validation commands, preserve issue linkage in the final PR or commit message, and treat temporary worktree cleanup as part of completion rather than an optional follow-up.
+- Output: Finish with either a linked PR or a direct pushed commit, then clean up the temporary worktree plus any matching local branch before reporting completion.
 
 ## Overview
 
@@ -89,10 +89,12 @@ python3 scripts/list_issues.py --limit 50 --state open
   - executed test commands and results
 - Include issue-closing reference (for example, `Closes #<issue-number>`) whenever a PR is opened.
 
-### 8) Clean up the temporary worktree after PR creation
+### 8) Clean up the temporary worktree after PR creation or direct push
 
 - Once the PR is opened or the direct push is complete and no more work is needed in that isolated tree, remove the worktree you created for the fix.
 - Also clean up the matching local branch reference if it is no longer needed locally.
+- Verify the cleanup with `git worktree list` and confirm the temporary path no longer appears before finishing.
+- If the worktree cannot be removed because of uncommitted changes or a still-checked-out branch, resolve that state immediately instead of leaving cleanup for a later user request.
 
 ## Included Script
 

package/learn-skill-from-conversations/SKILL.md

@@ -15,7 +15,7 @@ description: Learn and evolve the local skill library from recent Codex conversa
 ## Standards
 
 - Evidence: Extract recent Codex session history first and derive reusable lessons only from actual conversation patterns.
-- Execution: Inventory the current skill catalog before editing, prioritize repeated requests, user corrections, and reported errors, then prefer a focused update to the strongest related skill or create a new skill only when the overlap is weak.
+- Execution: Inventory the current skill catalog before editing, prioritize repeated requests, user corrections, reported errors, and post-completion follow-up asks that reveal missing closure, then prefer a focused update to the strongest related skill or create a new skill only when the overlap is weak.
 - Quality: Take no action when there are no recent sessions, avoid unrelated broad refactors, and validate every changed skill.
 - Output: Report the analyzed sessions, extracted lessons, created or updated skills, and the reasoning behind each decision.
 
@@ -48,6 +48,8 @@ python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_co
 - Identify repeated user needs, recurring friction, and repeated manual workflows.
 - Give extra weight to moments where the user corrected the agent, rejected an earlier interpretation, or pointed out a missing preference or requirement.
 - Give extra weight to user-reported errors, regressions, or avoidable mistakes, then ask how a skill can prevent repeating that failure mode.
+- Treat a user follow-up that asks for cleanup or an omitted finalization step immediately after the assistant reported completion as evidence that the workflow's done criteria were incomplete.
+- When that kind of follow-up recurs, tighten the owning skill's completion checklist before considering any new-skill extraction.
 - Ignore one-off issues that do not provide reusable value.
 - Distinguish between:
   - repeated trigger intent that deserves a new skill

package/openclaw-configuration/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: openclaw-configuration
+description: Build, audit, and explain OpenClaw configuration from official documentation. Use when configuring `~/.openclaw/openclaw.json`, mapping config options, adjusting skills or secrets, generating validated snippets, or diagnosing config errors with `openclaw config`, `openclaw configure`, and `openclaw doctor`.
+---
+
+# OpenClaw Configuration
+
+## Dependencies
+
+- Required: none.
+- Conditional: `answering-questions-with-research` when a request depends on newer OpenClaw docs than the bundled references cover.
+- Optional: none.
+- Fallback: If the local CLI is unavailable, work from the bundled references and clearly mark any runtime behavior that was not verified on the machine.
+
+## Standards
+
+- Evidence: Verify the active config file, current values, and CLI diagnostics before editing.
+- Execution: Prefer the smallest safe change; use `openclaw config` for narrow edits and direct JSON edits for broad restructures.
+- Quality: Keep the file schema-valid, avoid plaintext secrets when a SecretRef or env var fits, and preserve unrelated valid settings.
+- Output: Return exact file paths, touched keys, validation commands, and any restart or hot-reload caveats.
+
+## Goal
+
+Help another agent configure OpenClaw safely, quickly, and with citations back to the official docs.
+
+## Workflow
+
+### 1. Classify the request
+
+Decide whether the user needs:
+
+- a config explanation
+- a new starter config
+- a targeted key update
+- skills loading or per-skill env setup
+- secrets or provider wiring
+- validation or repair of a broken config
+
+Assume the canonical config file is `~/.openclaw/openclaw.json` unless the environment proves otherwise.
+
+### 2. Choose the safest edit surface
+
+- Use `openclaw onboard` or `openclaw configure` for guided setup.
+- Use `openclaw config get/set/unset/validate` for precise path-based edits.
+- Use direct JSON edits only when changing several related branches at once.
+- If the local gateway is running, the Control UI config tab at `http://127.0.0.1:18789` can help inspect or edit the same schema-backed config.
+
+### 3. Load only the references you need
+
+- Read `references/official-docs.md` first for the canonical doc map.
+- Read `references/config-reference-map.md` when you need option names, CLI behavior, hot reload, skills config, env handling, or secrets rules.
+- Read `references/best-practices.md` before producing a new config, touching credentials, or fixing a broken setup.
+
+### 4. Apply minimal, schema-safe changes
+
+- Prefer `openclaw config set` for one-path edits.
+- Prefer SecretRefs or env substitution over plaintext credentials.
+- For skill-specific setup, use `skills.load.extraDirs`, `skills.entries.<skillKey>`, and per-skill `env` or `apiKey`.
+- Do not invent unknown root keys; OpenClaw rejects schema-invalid config.
+
+### 5. Validate before finishing
+
+- Run `openclaw config validate` after edits.
+- If the gateway refuses to boot, run `openclaw doctor`.
+- Use `openclaw doctor --repair` only after reviewing what it will change; the tool can back up the config and remove unknown keys.
+- Call out whether the change should hot-apply or may still need a restart.
+
+### 6. Return a concise handoff
+
+Always include:
+
+- the file or keys changed
+- the command or JSON snippet used
+- the validation command
+- any secret or env prereqs
+- the official doc pages that justify the change
+
+## Common Tasks
+
+### Generate a starter config
+
+Start from the official minimal or starter shape, then add only the channels, models, or skills the user actually needs.
+
+### Explain config options
+
+Summarize the relevant branch and point back to the matching official page rather than dumping the entire reference.
+
+### Configure skills
+
+Use `skills.load.extraDirs` for additional skill folders and `skills.entries.<skillKey>` for per-skill enablement, env vars, or `apiKey`.
+
+### Wire secrets
+
+Prefer SecretRefs (`env`, `file`, or `exec`) for supported credential fields. Use plaintext only when the user explicitly wants a local-only quick setup and understands the tradeoff.
+
+### Repair a broken config
+
+Run `openclaw config validate`, then `openclaw doctor`, and only then make the smallest correction that restores schema validity.

package/openclaw-configuration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenClaw Configuration"
+  short_description: "Configure and troubleshoot OpenClaw settings"
+  default_prompt: "Use $openclaw-configuration to explain, edit, validate, or troubleshoot OpenClaw configuration, including `~/.openclaw/openclaw.json`, `skills` settings, env vars, SecretRefs, and official OpenClaw CLI/config workflows."

package/openclaw-configuration/references/best-practices.md

@@ -0,0 +1,55 @@
+# OpenClaw Configuration Best Practices
+
+These rules are distilled from the official OpenClaw docs and adapted into a practical workflow.
+
+## Authoring rules
+
+- Treat `~/.openclaw/openclaw.json` as the source of truth unless the environment proves otherwise.
+- Prefer the smallest possible edit surface:
+  - one key: `openclaw config set`
+  - one subtree removal: `openclaw config unset`
+  - several coordinated edits: direct JSON edit plus validation
+- Keep JSON structure conservative; OpenClaw rejects unknown keys.
+- Use the configuration examples page as a baseline instead of inventing a new root layout.
+
+## Safety rules
+
+- Never store production credentials in plaintext if a SecretRef or env var can be used.
+- Avoid mixing plaintext and SecretRefs for the same credential path; the ref wins on supported fields and makes ownership clearer.
+- Validate immediately after editing:
+  - `openclaw config validate`
+  - `openclaw doctor` when the gateway still behaves unexpectedly
+- Use `openclaw doctor --repair` only when you are comfortable with automatic cleanup and backup behavior.
+
+## Environment rules
+
+- Prefer `${VAR_NAME}` substitution for portable config shared across machines.
+- Keep env var names uppercase to match the documented substitution pattern.
+- Use `env.shellEnv.enabled` only when the missing-key import behavior is intentional and understood.
+- Avoid scattering the same secret across the parent shell, local `.env`, and `~/.openclaw/.env`; keep precedence simple.
+
+## Skills rules
+
+- Put extra skill roots in `skills.load.extraDirs` instead of hard-coding ad hoc discovery logic elsewhere.
+- Use `skills.entries.<skillKey>.enabled` for explicit enable or disable state.
+- Use `skills.entries.<skillKey>.env` for skill-local environment variables.
+- Use `skills.entries.<skillKey>.apiKey` only when the skill expects a primary env-backed API key convenience field.
+- Leave `skills.load.watch` enabled while iterating on local skills unless file-watch churn becomes a confirmed problem.
+- If you set `skills.install.nodeManager`, remember the official docs still recommend Node as the runtime for the gateway itself.
+
+## Troubleshooting rules
+
+- If the gateway stops booting after a config change, assume schema breakage first and validate before changing unrelated systems.
+- When troubleshooting a credentialed path, inspect both the config branch and the SecretRef provider branch.
+- When a user asks for "why did this stop working," capture the exact key path and the command used to validate it.
+- For broken skill loading, check both `skills.load.extraDirs` and the effective `skillKey` mapping.
+
+## Recommended delivery format
+
+When answering a user or editing a machine, return:
+
+1. the exact file or key path
+2. the change made
+3. the validation command
+4. the secret or env prerequisites
+5. the official docs used

package/openclaw-configuration/references/config-reference-map.md

@@ -0,0 +1,189 @@
+# OpenClaw Config Reference Map
+
+This file condenses the official OpenClaw configuration docs into a quick operator map.
+
+## Main file and edit surfaces
+
+- Canonical file: `~/.openclaw/openclaw.json`
+- Guided setup:
+  - `openclaw onboard`
+  - `openclaw configure`
+- Precise edits:
+  - `openclaw config get <path>`
+  - `openclaw config set <path> <value>`
+  - `openclaw config unset <path>`
+  - `openclaw config validate`
+- UI editing:
+  - Config tab in the local Control UI at `http://127.0.0.1:18789`
+- Direct editing:
+  - safe for broader restructures, but validate immediately afterward
+
+## Validation and reload behavior
+
+- OpenClaw enforces a strict schema.
+- Unknown keys, bad types, or invalid values can prevent the gateway from starting.
+- The root `$schema` string is the documented exception for editor schema metadata.
+- When validation fails, the docs point to diagnostic commands such as:
+  - `openclaw doctor`
+  - `openclaw logs`
+  - `openclaw health`
+  - `openclaw status`
+- The gateway watches `~/.openclaw/openclaw.json` and hot-applies many changes automatically.
+
+## CLI behavior worth remembering
+
+### Paths
+
+- Dot notation works: `agents.defaults.workspace`
+- Bracket notation works: `agents.list[0].tools.exec.node`
+
+### Value parsing
+
+- `openclaw config set` parses JSON5 when possible.
+- Use `--strict-json` when you want parsing to be required.
+- Use strings intentionally for values such as heartbeat durations.
+
+### Assignment modes
+
+- Value mode: plain path/value edit
+- SecretRef builder mode: build a supported ref without hand-writing JSON
+- Provider builder mode: build `secrets.providers.<alias>` entries
+- Batch mode: apply several edits from a JSON payload or file
+
+## Official namespace map
+
+The full reference documents these major sections:
+
+- `channels`
+- `agents`
+- `session`
+- `messages`
+- `talk`
+- `tools`
+- custom providers and base URLs
+- `skills`
+- `plugins`
+- `browser`
+- `ui`
+- `gateway`
+- `hooks`
+- canvas host
+- discovery
+- `environment`
+- `secrets`
+- auth storage
+- logging
+- CLI
+- wizard
+- identity
+- `cron`
+- media model template variables
+- config includes via `$include`
+
+Use the official full reference when you need the exact nested shape under one of these branches.
+
+## Environment variables
+
+The gateway docs describe three non-inline sources:
+
+- env vars from the parent process
+- `.env` in the current working directory
+- `~/.openclaw/.env` as a global fallback
+
+Neither `.env` file overrides variables that are already present in the parent process.
+
+The docs also describe config-side helpers:
+
+- inline `env` sections
+- optional shell env import via `env.shellEnv.enabled`
+- config string substitution with `${VAR_NAME}`
+
+Key rules called out by the docs:
+
+- substitution targets uppercase variable names
+- missing or empty values fail at load time
+- use `$${VAR}` to escape a literal placeholder
+
+## Secrets and credential references
+
+OpenClaw documents a common SecretRef shape:
+
+```json
+{
+  "source": "env",
+  "provider": "default",
+  "id": "OPENAI_API_KEY"
+}
+```
+
+Supported ref sources in the docs:
+
+- `env`
+- `file`
+- `exec`
+
+Operational rules confirmed by the secrets docs:
+
+- if a supported field has both plaintext and a ref, the ref takes precedence
+- `openclaw secrets audit --check` is the default preflight
+- `openclaw secrets configure` helps wire providers
+- a final `openclaw secrets audit --check` confirms the setup
+
+## Skills configuration
+
+The official skills config page documents these fields:
+
+- `skills.allowBundled`
+- `skills.load.extraDirs`
+- `skills.load.watch`
+- `skills.load.watchDebounceMs`
+- `skills.install.preferBrew`
+- `skills.install.nodeManager`
+- `skills.entries.<skillKey>.enabled`
+- `skills.entries.<skillKey>.env`
+- `skills.entries.<skillKey>.apiKey`
+
+Notes confirmed by the docs:
+
+- `skills.entries` keys default to the skill name
+- if a skill defines `metadata.openclaw.skillKey`, use that key instead
+- watcher-driven skill changes are picked up on the next agent turn when watching is enabled
+
+## Example snippets to adapt
+
+### Minimal starter
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.openclaw/workspace"
+    }
+  },
+  "channels": {
+    "whatsapp": {
+      "allowFrom": ["+15555550123"]
+    }
+  }
+}
+```
+
+### Custom skill directory plus per-skill env
+
+```json
+{
+  "skills": {
+    "load": {
+      "extraDirs": ["~/skills", "~/.apollo-toolkit"]
+    },
+    "entries": {
+      "openclaw-configuration": {
+        "enabled": true,
+        "env": {
+          "OPENCLAW_CONFIG_PATH": "~/.openclaw/openclaw.json"
+        }
+      }
+    }
+  }
+}
+```

package/openclaw-configuration/references/official-docs.md

@@ -0,0 +1,40 @@
+# OpenClaw Official Config Docs
+
+Last verified: 2026-03-20
+
+Use this file as the entry map into the official OpenClaw documentation on `docs.openclaw.ai`.
+
+## Canonical pages
+
+- Gateway configuration overview: `https://docs.openclaw.ai/gateway/configuration`
+  - Covers the main config file path, edit surfaces, strict validation, hot reload, env vars, and links to the full reference.
+- Full configuration reference: `https://docs.openclaw.ai/gateway/configuration-reference`
+  - Covers the major top-level namespaces such as `channels`, `agents`, `tools`, `skills`, `plugins`, `gateway`, `secrets`, `cron`, and `$include`.
+- Configuration examples: `https://docs.openclaw.ai/gateway/configuration-examples`
+  - Provides minimal and starter-shaped configs plus common deployment patterns.
+- Skills config: `https://docs.openclaw.ai/tools/skills-config`
+  - Covers `skills.allowBundled`, `skills.load.*`, `skills.install.*`, and `skills.entries.<skillKey>`.
+- Secrets management: `https://docs.openclaw.ai/gateway/secrets`
+  - Covers SecretRef structure, providers, precedence, audit flow, and secure credential handling.
+- CLI config command: `https://docs.openclaw.ai/cli/config`
+  - Covers `openclaw config get/set/unset/validate`, path syntax, parsing rules, and SecretRef builder modes.
+- CLI configure command: `https://docs.openclaw.ai/cli/configure`
+  - Covers the guided configuration wizard.
+- CLI doctor command: `https://docs.openclaw.ai/cli/doctor`
+  - Covers diagnostics, repair behavior, backups, and environment checks.
+
+## Core facts confirmed from the official docs
+
+- The canonical config file is `~/.openclaw/openclaw.json`.
+- OpenClaw supports guided edits, CLI path edits, Control UI editing, and direct file editing.
+- The gateway validates the config strictly against schema; unknown keys are rejected except for the root `$schema` metadata key.
+- The gateway watches the config file and hot-applies many changes automatically.
+- Secrets can be supplied through env vars, files, or exec-backed SecretRefs, depending on the field.
+
+## When to open which doc
+
+- Need the exact field name or namespace: open the full reference.
+- Need a starting snippet or pattern: open configuration examples.
+- Need to load custom skills or set per-skill env: open skills config.
+- Need to wire API keys safely: open secrets management plus CLI config.
+- Need to repair a broken config: open gateway configuration plus CLI doctor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Apollo Toolkit npm installer for managed skill linking across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",