docs: fix claude authentication command

[chaodu-agent]

Summary

Replace claude setup-token with claude auth login in docs/claude-code.md.

Problem

The doc previously instructed users to run claude setup-token for authentication. This command generates a long-lived token and prints it to stdout without saving it locally — it is intended for CI/scripts where you set CLAUDE_CODE_OAUTH_TOKEN as an env var.

For container deployments with PVC persistence, claude auth login is the correct command. It authenticates via OAuth device flow and stores credentials on disk, surviving pod restarts.

Reference

From the official Claude Code CLI reference:

• claude setup-token — "Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it."
• claude auth login — "Sign in to your Anthropic account." (stores credentials locally)

For container deployments with PVC persistence, claude auth login is the correct command.

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs: fix claude authentication command
• Source: docs: fix claude authentication command #739
• Status: moved to PR-Screening
• Generated at: 2026-05-05T02:31:20.360Z
• Discord thread: https://discord.com/channels/1488041051187974246/1501048444754858130

Screening report

## Intent

PR #739 updates docs/claude-code.md so OpenAB’s Claude Code container setup instructions use the correct authentication command.

The operator-visible problem is that the docs currently tell deployers to run claude setup-token, which prints a long-lived token for CI/script usage but does not save credentials locally. For container deployments using PVC persistence, that can leave operators with authentication that does not survive restarts unless they manually manage CLAUDE_CODE_OAUTH_TOKEN.

Feat

Docs improvement.

The PR replaces the Claude authentication instruction with claude auth login, which uses the OAuth login flow and stores credentials locally so they can persist across pod restarts when backed by a PVC.

Who It Serves

Primary beneficiary: deployers and agent runtime operators running OpenAB with Claude Code in containers.

Secondary beneficiaries: maintainers and reviewers, because the documented setup path becomes less error-prone and better aligned with persistent runtime environments.

Rewritten Prompt

Update docs/claude-code.md to document claude auth login as the recommended authentication command for container deployments that persist Claude credentials with a PVC.

Make the docs clearly distinguish:

• claude auth login: interactive OAuth login that stores credentials locally and is appropriate for persistent container volumes.
• claude setup-token: CI/script-oriented token generation that prints a token and requires explicit environment variable handling.

Keep the change scoped to documentation. Verify the surrounding setup instructions still read coherently for a deployer following the container/PVC flow.

Merge Pitch

This is a low-risk documentation correction that prevents operators from following an authentication path poorly suited to persistent container deployments. It is worth advancing because incorrect auth setup can cause avoidable runtime failures after pod restarts.

Likely reviewer concern: whether claude auth login is universally correct or only correct for the PVC-backed deployment path. The docs should avoid overgeneralizing and should preserve setup-token as the right option for CI or non-interactive scripts.

Best-Practice Comparison

Relevant OpenClaw principles:

• Durable job persistence: relevant by analogy. Persisted Claude credentials should survive pod restarts when the deployment expects durable agent state.
• Explicit delivery routing: not directly relevant.
• Gateway-owned scheduling: not directly relevant.
• Isolated executions: only indirectly relevant; authentication state should be scoped intentionally, but this PR is documentation-only.
• Retry/backoff and run logs: not relevant.

Relevant Hermes Agent principles:

• Atomic writes for persisted state: indirectly relevant because local auth credentials become part of persisted runtime state, though the CLI handles the actual write behavior.
• Fresh session per scheduled run: relevant only as a caution. Fresh execution sessions still need predictable access to persisted credentials.
• Self-contained prompts for scheduled tasks: not directly relevant.
• Gateway daemon tick model: not relevant.
• File locking to prevent overlap: not relevant.

The proposed direction fits the persistence-oriented parts of both systems: runtime state that must survive restarts should be stored deliberately, not emitted once to stdout and left to manual handling.

Implementation Options

Conservative option: merge the current one-line command replacement plus minimal explanatory text.

Balanced option: merge the command replacement and add a short note explaining when to use claude auth login versus claude setup-token.

Ambitious option: expand docs/claude-code.md into a fuller authentication section covering local development, PVC-backed containers, CI/script usage, expected credential location, and troubleshooting after pod restarts.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative command replacement	High	Low	Medium	High	Medium	Good
Balanced clarification	High	Low-Medium	High	High	High	Best
Full auth section	Medium	Medium	High	Medium	High	Good, but may be larger than needed

Recommendation

Advance the PR with the balanced documentation shape.

The command correction is clearly useful, but the merge is stronger if the docs explicitly preserve claude setup-token as the CI/script option and frame claude auth login as the PVC-backed container option. That keeps the change accurate, reviewable, and low risk.

Suggested sequencing: merge this as a focused docs fix, then split any broader Claude Code deployment troubleshooting into a separate follow-up if maintainers want more complete operator guidance.

[masami-agent]

PR Review: #739

Based on commit: b23eb0ef676e9ae9ce09e62102d274564072af4f

Summary

• Problem: docs/claude-code.md uses claude setup-token for authentication, but this command only prints a token without saving it — unsuitable for container deployments with PVC persistence.
• Approach: Replace with claude auth login (OAuth device flow, stores credentials on disk), add a kubectl rollout restart step, and include an explanatory note.
• Risk level: Low (docs-only change)

Core Assessment

1. Problem clearly stated: ✅ — PR description clearly explains the difference between the two commands with official reference
2. Approach appropriate: ⚠️ — The fix is technically correct, but incomplete in scope (see 🔴 below)
3. Alternatives considered: N/A
4. Best approach for now: ⚠️ — Depends on whether the other references should be fixed together or separately

Fact Verification

I checked the official Claude Code CLI reference:

• claude setup-token — "Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it."
• claude auth login — "Sign in to your Anthropic account." (stores credentials locally via OAuth device flow)

PR claims are consistent with official docs ✅

Findings

🟢 INFO

• Technical content is correct and verified against official Anthropic documentation
• PR description quality is high — includes reference link and clear explanation
• Commit message follows Conventional Commits format
• The > **Note:** block provides useful context for users who might confuse the two commands

🔴 SUGGESTED CHANGE — Incomplete scope

The repo has two other locations that still reference claude setup-token:

1. charts/openab/templates/NOTES.txt — The Helm post-install notes still tell users to run claude setup-token
2. src/setup/wizard.rs — The setup wizard output prints claude setup-token in two places

If only docs/claude-code.md is updated, users will receive contradictory guidance depending on whether they read the docs or follow the Helm/wizard output. I'd suggest either:

• (a) Expanding this PR to update all three locations, or
• (b) Confirming that NOTES.txt and wizard.rs will be addressed in a follow-up PR

🟡 NIT — Minor wording

The phrase "restart the pod to pick up the new credentials" is slightly imprecise. After claude auth login, credentials are already written to the PVC. The restart is needed so the openab process re-reads them on startup. Consider: "restart the pod so the bot process loads the new credentials." This does not affect correctness of the instructions.

Verdict

COMMENT — The fix itself is correct and valuable, but the scope should be discussed. The other two references to claude setup-token in the codebase would leave users with contradictory instructions if not addressed.