Clarify auth and API runtime setup

Author: ukgorclawbot-stack

.ai_runtimes.env.example

@@ -1,3 +1,5 @@
+# Optional.
+# Leave these empty if you prefer interactive auth/login instead of API keys.
 export OPENAI_API_KEY=""
 export ANTHROPIC_API_KEY=""
 export GEMINI_API_KEY=""

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this public repository are documented here.
 
+## v0.1.9
+
+- clarified that `Codex`, `Claude Code`, `Gemini CLI`, and `OpenClaw` do not require API-key-only setup
+- updated runtime setup flow to support both `auth/login` and API key paths
+- changed health checks so empty API key values are treated as optional when auth/login may still be valid
+
 ## v0.1.8
 
 - added one-command AI runtime installation for `OpenClaw`, `Gemini CLI`, `Codex CLI`, and `Claude Code`

INSTALL.en.md

@@ -63,8 +63,10 @@ This step will:
 
 - check whether the 4 AI CLIs are installed
 - create `.ai_runtimes.env`
-- guide you to fill in API keys
-- tell you which CLIs to run if you prefer interactive login
+- guide you to choose between:
+  - API keys
+  - auth/login
+- tell you which CLI login commands to run if you prefer auth
 
 If this is your first time setting everything up, do this before bot stack configuration.
 

INSTALL.md

@@ -68,8 +68,10 @@ bash ./configure_ai_runtimes.sh
 
 - 检查 4 个 AI CLI 是否已经安装
 - 自动创建 `.ai_runtimes.env`
-- 引导你填写 API key
-- 告诉你如果更喜欢交互式登录，应该执行哪些 CLI
+- 引导你选择：
+  - 填 API key
+  - 或者直接做 auth/login
+- 告诉你不同 CLI 对应的登录命令
 
 如果你完全是第一次装，建议在配置 bot stack 之前先完成这一步。
 

RELEASE_NOTES_v0.1.9.md

@@ -0,0 +1,24 @@
+# v0.1.9 - Auth login and API key coexistence
+
+This release fixes an important onboarding issue for beginners.
+
+## Fixed
+
+- the project no longer implies that `Codex`, `Claude Code`, or `Gemini CLI` must use API keys
+- runtime setup now explicitly supports both:
+  - API key mode
+  - auth/login mode
+
+## Improved
+
+- `.ai_runtimes.env.example` now clearly marks API keys as optional
+- `configure_ai_runtimes.sh` now tells users how to use:
+  - `openclaw configure` or `openclaw onboard`
+  - `gemini`
+  - `codex login`
+  - `claude auth login`
+- `health_check.sh` now reports empty API env fields as optional instead of warning-level failure
+
+## Goal
+
+Make the project friendlier to real-world users, where some tools are authenticated by account login and others by API keys.

configure_ai_runtimes.sh

@@ -14,17 +14,21 @@ bash "$REPO_DIR/install_ai_runtimes.sh" --check || true
 
 echo
 echo "==> 准备配置 AI 认证环境"
-echo "请在打开的文件里按需填写以下内容："
+echo "这一步同时支持两种方式："
+echo "1) API key"
+echo "2) auth / login"
+echo
+echo "如果你想用 API key，就在打开的文件里按需填写："
 echo "- OPENAI_API_KEY"
 echo "- ANTHROPIC_API_KEY"
 echo "- GEMINI_API_KEY"
 echo "- GOOGLE_API_KEY"
 echo
-echo "如果你更喜欢交互式登录，也可以稍后手动执行："
-echo "- openclaw"
+echo "如果你想用 auth / login，也可以把这个文件留空，然后手动执行："
+echo "- openclaw configure  或  openclaw onboard"
 echo "- gemini"
-echo "- codex"
-echo "- claude"
+echo "- codex login"
+echo "- claude auth login"
 echo
 
 if command -v open >/dev/null 2>&1; then

docs/ai-runtimes.md

@@ -56,7 +56,16 @@ This script helps users prepare authentication.
 
 It does not print secrets.
 
-It opens `.ai_runtimes.env` and lets users fill:
+It opens `.ai_runtimes.env` if users want API-key based auth.
+
+Users can also leave that file empty and use interactive login instead.
+
+It supports:
+
+- API key mode
+- auth/login mode
+
+When using API keys, users can fill:
 
 - `OPENAI_API_KEY`
 - `ANTHROPIC_API_KEY`
@@ -66,7 +75,7 @@ It opens `.ai_runtimes.env` and lets users fill:
 这个脚本的作用不是“替你登录账号”，而是：
 
 - 统一生成认证配置文件
-- 让新手知道该填哪些 key
+- 让新手知道 API key 只是可选方案之一
 - 给出交互式登录的备用入口
 
 ## 5. Two supported auth styles / 两种支持的认证方式
@@ -99,6 +108,20 @@ Best for:
 - 个人电脑
 - 第一次快速上手
 
+Typical examples:
+
+- `openclaw configure` or `openclaw onboard`
+- `gemini`
+- `codex login`
+- `claude auth login`
+
+常见命令示例：
+
+- `openclaw configure` 或 `openclaw onboard`
+- `gemini`
+- `codex login`
+- `claude auth login`
+
 ## 6. Important runtime note / 一个重要细节
 
 This project makes the bot launch script load `.ai_runtimes.env` automatically.
@@ -125,16 +148,24 @@ It now reports whether these four AI CLIs are available.
 - Codex CLI 是否安装
 - Claude Code 是否安装
 
+It does not treat an empty API key file as a hard failure, because auth/login may still be valid.
+
+它不会把“API key 为空”直接判成失败，因为用户也可能走 auth/login。
+
 ## 8. Recommended rule for beginners / 给小白的推荐规则
 
 If you are a beginner:
 
 1. let `install.sh` install the tools
-2. fill `.ai_runtimes.env`
+2. choose either:
+   - fill `.ai_runtimes.env`
+   - or complete auth/login interactively
 3. only then continue to bot token configuration
 
 如果你是第一次装：
 
 1. 先让 `install.sh` 装 4 个 AI CLI
-2. 再填 `.ai_runtimes.env`
+2. 再二选一：
+   - 填 `.ai_runtimes.env`
+   - 或者完成 auth/login
 3. 最后再去填 bot token 和启动服务

health_check.sh

@@ -200,12 +200,12 @@ print_runtime_status() {
   fi
 }
 
-print_env_status() {
+print_env_status_optional() {
   local key="$1"
   if [ -n "${!key:-}" ]; then
     printf "[%s] %-18s configured\n" "$(status_icon ok)" "$key"
   else
-    printf "[%s] %-18s empty\n" "$(status_icon warn)" "$key"
+    printf "[%s] %-18s optional-empty\n" "$(status_icon info)" "$key"
   fi
 }
 
@@ -224,13 +224,16 @@ print_runtime_status "openclaw" "OpenClaw"
 print_runtime_status "gemini" "Gemini CLI"
 print_runtime_status "codex" "Codex CLI"
 print_runtime_status "claude" "Claude Code"
-print_env_status "OPENAI_API_KEY"
-print_env_status "ANTHROPIC_API_KEY"
+print_env_status_optional "OPENAI_API_KEY"
+print_env_status_optional "ANTHROPIC_API_KEY"
 if [ -n "${GEMINI_API_KEY:-}" ] || [ -n "${GOOGLE_API_KEY:-}" ]; then
   printf "[%s] %-18s configured\n" "$(status_icon ok)" "Gemini auth"
 else
-  printf "[%s] %-18s empty\n" "$(status_icon warn)" "Gemini auth"
+  printf "[%s] %-18s optional-empty\n" "$(status_icon info)" "Gemini auth"
 fi
+printf "[%s] %-18s supported via login or local config\n" "$(status_icon info)" "OpenClaw auth"
+printf "[%s] %-18s supported via codex login\n" "$(status_icon info)" "Codex auth"
+printf "[%s] %-18s supported via claude auth login\n" "$(status_icon info)" "Claude auth"
 
 echo
 echo "== Bot Services =="