Summary

Describe the problem and fix in 2–5 bullets:

• Problem: config options (including channels/plugins) and config schema docs drifted; no single generated API/spec source for validation + docs.
• Why it matters: operators and tooling could not reliably inspect all openclaw.json keys or verify docs against runtime schema.
• What changed: added authenticated config HTTP endpoints (/v1/config/schema, /v1/config/keys, /v1/config/validate), generators for schema/spec/docs artifacts, and Mintlify OpenAPI wiring via docs/docs.json.
• What did NOT change (scope boundary): no changes to non-config gateway APIs, model routing behavior, or channel runtime semantics.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #

User-visible / Behavior Changes

List user-visible changes (including defaults/config).
If none, write None.

• New authenticated HTTP config endpoints:
  • GET /v1/config/schema
  • GET /v1/config/keys
  • POST /v1/config/validate
• New generated artifacts and docs:
  • dist/config.schema.json
  • dist/config.uihints.json
  • dist/config.keys.json
  • dist/config-http.openapi.json
  • docs/openapi/config-http.openapi.json
  • docs/gateway/config-http-api.md
  • docs/gateway/configuration-schema-reference.md
• Mintlify now consumes config OpenAPI directly via docs/docs.json api.openapi config.

Security Impact (required)

• New permissions/capabilities? (Yes/No) Yes
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) Yes
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) Yes
• If any Yes, explain risk + mitigation:
  • Risk: new HTTP endpoints expose config schema/validation surface.
  • Mitigation: endpoints require existing gateway bearer auth and reuse existing trusted proxy + auth rate limiter flow.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + pnpm
• Model/provider: N/A
• Integration/channel (if any): Gateway HTTP server
• Relevant config (redacted): gateway.auth.mode=token

Steps

1. Run pnpm config-spec:gen.
2. Start gateway with bearer auth and request /v1/config/schema, /v1/config/keys, /v1/config/validate.
3. Run pnpm config-spec:check and pnpm check:docs.

Expected

• Endpoints return authenticated schema/keys/validation responses.
• Spec/docs artifacts regenerate deterministically and remain in sync.
• Docs lint + link checks pass.

Actual

• Matches expected.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm vitest run --config vitest.gateway.config.ts src/gateway/config-http.test.ts (5/5 passing)
  • pnpm config-spec:check passing
  • pnpm check:docs passing (broken_links=0)
• Edge cases checked:
  • unauthenticated access returns 401
  • wrong method returns 405
  • validate endpoint handles both raw object and { config: ... }
• What you did not verify:
  • remote deployed Mintlify preview rendering (requested via this draft PR)

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • Revert this PR branch/commits.
• Files/config to restore:
  • src/gateway/config-http.ts, src/gateway/server-http.ts, docs/docs.json, generated artifacts.
• Known bad symptoms reviewers should watch for:
  • pnpm config-spec:check diff churn
  • Mintlify API reference not rendering from docs/openapi/config-http.openapi.json

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: generated artifacts can drift if generator and formatter pipelines diverge.
  • Mitigation: config-spec:docs now formats generated files, and config-spec:check enforces sync.