docs: update Anthropic Claude CLI billing guidance

steipete · steipete · commit 13cb9f82777e · 2026-05-29T06:14:30.000+01:00
diff --git a/docs/help/faq-models.md b/docs/help/faq-models.md
@@ -536,7 +536,11 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a
   <Accordion title="OAuth vs API key - what is the difference?">
     OpenClaw supports both:
 
-    - **OAuth** often leverages subscription access (where applicable).
+    - **OAuth / CLI login** often leverages subscription access where the
+      provider supports it. For Anthropic, OpenClaw's Claude CLI backend uses
+      Claude Code `claude -p`; Anthropic currently treats that as Agent
+      SDK/programmatic usage, with a separate monthly Agent SDK credit starting
+      June 15, 2026.
     - **API keys** use pay-per-token billing.
 
     The wizard explicitly supports Anthropic Claude CLI, OpenAI Codex OAuth, and API keys.
diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md
@@ -8,22 +8,27 @@ title: "Anthropic"
 Anthropic builds the **Claude** model family. OpenClaw supports two auth routes:
 
 - **API key** — direct Anthropic API access with usage-based billing (`anthropic/*` models)
-- **Claude CLI** — reuse an existing Claude CLI login on the same host
+- **Claude CLI** — reuse an existing Claude Code login on the same host
 
 <Warning>
-Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so
-OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned unless
-Anthropic publishes a new policy.
+OpenClaw's Claude CLI backend runs the installed Claude Code CLI in
+non-interactive print mode. Anthropic's current Claude Code docs describe
+`claude -p` as Agent SDK/programmatic usage. Starting June 15, 2026, Anthropic
+says subscription-plan `claude -p` usage no longer draws from normal Claude
+plan limits; it draws from a separate monthly Agent SDK credit first, then from
+usage credits at standard API rates when those credits are enabled.
 
-For long-lived gateway hosts, Anthropic API keys are still the clearest and
-most predictable production path.
+Interactive Claude Code still draws from the signed-in Claude plan limits. API
+key auth remains direct pay-as-you-go API billing. For long-lived gateway hosts,
+shared automation, and predictable production spend, use an Anthropic API key.
 
 Anthropic's current public docs:
 
-- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
-- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview)
-- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
-- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
+- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-usage)
+- [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan)
+- [Use Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan)
+- [Use Claude Code with your Team or Enterprise plan](https://support.claude.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan)
+- [Manage Claude Code costs](https://code.claude.com/docs/en/costs)
 
 </Warning>
 
@@ -128,8 +133,28 @@ Anthropic's current public docs:
     compatibility, but new config should keep provider/model selection as
     `anthropic/*` and put the execution backend in provider/model runtime policy.
 
+    ### Billing and `claude -p`
+
+    OpenClaw uses Claude Code's non-interactive `claude -p` path for Claude CLI
+    runs. Anthropic currently treats that path as Agent SDK/programmatic usage:
+
+    - Until June 15, 2026, subscription-plan handling follows Anthropic's active
+      Claude Code rules for the signed-in account.
+    - Starting June 15, 2026, subscription-plan `claude -p` usage draws from the
+      user's monthly Agent SDK credit first, then from usage credits at standard
+      API rates if usage credits are enabled.
+    - Console/API-key logins use pay-as-you-go API billing and do not receive
+      the subscription Agent SDK credit.
+
+    Anthropic can change Claude Code billing and rate-limit behavior without an
+    OpenClaw release. Check `claude auth status`, `/status`, and
+    Anthropic's linked docs when billing predictability matters.
+
     <Tip>
-    If you want the clearest billing path, use an Anthropic API key instead. OpenClaw also supports subscription-style options from [OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/zai).
+    For shared production automation, use an Anthropic API key instead of
+    Claude CLI. OpenClaw also supports subscription-style options from
+    [OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen),
+    [MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/zai).
     </Tip>
 
   </Tab>
diff --git a/docs/providers/claude-max-api-proxy.md b/docs/providers/claude-max-api-proxy.md
@@ -12,23 +12,31 @@ title: "Claude Max API proxy"
 <Warning>
 This path is technical compatibility only. Anthropic has blocked some subscription
 usage outside Claude Code in the past. You must decide for yourself whether to use
-it and verify Anthropic's current terms before relying on it.
+it and verify Anthropic's current billing rules before relying on it.
+
+Anthropic's current support docs say `claude -p` is Agent SDK/programmatic usage.
+Starting June 15, 2026, subscription-plan `claude -p` usage draws from a separate
+monthly Agent SDK credit first, then from usage credits at standard API rates if
+usage credits are enabled.
 </Warning>
 
 ## Why use this?
 
-| Approach                | Cost                                                | Best For                                   |
-| ----------------------- | --------------------------------------------------- | ------------------------------------------ |
-| Anthropic API           | Pay per token (~$15/M input, $75/M output for Opus) | Production apps, high volume               |
-| Claude Max subscription | $200/month flat                                     | Personal use, development, unlimited usage |
+| Approach                  | Cost route                                      | Best for                                   |
+| ------------------------- | ----------------------------------------------- | ------------------------------------------ |
+| Anthropic API             | Pay per token through Claude Console or cloud   | Production apps, shared automation, volume |
+| Claude subscription proxy | Claude Code / `claude -p` plan and credit rules | Personal experiments with compatible tools |
 
-If you have a Claude Max subscription and want to use it with OpenAI-compatible tools, this proxy may reduce cost for some workflows. API keys remain the clearer policy path for production use.
+If you have a Claude Max or Pro subscription and want to use it with
+OpenAI-compatible tools, this proxy may fit some personal workflows. It is not an
+unlimited flat-rate path. API keys remain the clearer policy and billing path for
+production use.
 
 ## How it works
 
 ```
-Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription)
-     (OpenAI format)              (converts format)      (uses your login)
+Your App → claude-max-api-proxy → Claude Code CLI / claude -p → Anthropic
+     (OpenAI format)              (converts format)          (uses your login)
 ```
 
 The proxy:
@@ -157,6 +165,7 @@ The proxy:
 
 - This is a **community tool**, not officially supported by Anthropic or OpenClaw
 - Requires an active Claude Max/Pro subscription with Claude Code CLI authenticated
+- Inherits Claude Code `claude -p` billing, usage-credit, and rate-limit behavior
 - The proxy runs locally and does not send data to any third-party servers
 - Streaming responses are fully supported
 
