Claude Code All-in-One for ArkClaw

让 ArkClaw / OpenClaw 用户在对话框里完成 Claude Code CLI 的全部配置 — 不用打开终端、不用手写 ~/.claude/settings.json、不用记 base_url。本 skill 还内置 review / build 双模式智能路由:

• review 模式(--permission-mode plan):只读分析,不改文件,适合代码审查 / 评估改造方案
• build 模式(--allowedTools 白名单):允许 Read / Edit / Write / Bash 等动手工具,适合实现代码

整体流程(决策树)

用户触发本 skill(说"用 claude code 帮我..." / "/claude-code-allinone ..." / 报错 等)
        │
        ▼
  ┌───────────────────────────┐
  │ 运行 scripts/doctor.sh    │  ← 每次触发都会运行,检测当前环境状态
  └─────────────┬─────────────┘
                │
       当前配置状态 = ?
                │
  ┌─────────────┼──────────────────────────────────┐
  │             │                                  │
"全新环境"    "本 skill 配过"                   "用户手动配过"
(从未配置)   (之前用本 skill 配置的)          (有 settings.json/config 但不是本 skill 写的)
  │             │                                  │
  ▼             ▼                                  ▼
路径 ①        路径 ②                             路径 ③
首次配置      正常使用(绝大多数情况)              兼容性检查
  │             │                                  │
  │             │                                  ├─ 检查通过 → 保留不动,转到路径 ②
  │             │                                  └─ 检查不通过 → 告知用户具体问题,
  │             │                                       询问是否用本 skill 重新配置
  │             │
问用户选择   智能判定 review/build 模式
A/B 菜单     然后执行: claude -p "用户的需求" --permission-mode plan
  │              或:    claude -p "用户的需求" --allowedTools <白名单>
  ▼
完成配置后
转到路径 ②

三条路径说明

重要:正常使用时不要打扰用户

当配置已经就绪(路径 ②)时,不允许:

• 复述配置流程
• 解释 skill 在做什么
• 询问"是否需要切换 / 是否需要重新配置"
• 把 skill 的存在感暴露给用户

只做:

1. 运行 bash scripts/ensure-onboarding.sh(确保 ~/.claude.json 标记 onboarding 完成)
2. 调用 bash scripts/run.sh "用户的完整需求原文"(自动判定 review / build 模式)
3. 把 claude code 的输出原样返回给用户

用户体验应该等同于"直接跟 claude code 对话",完全感觉不到 skill 的存在。

只有这三种情况允许打扰用户:

1. 首次配置(环境全新)
2. 兼容性检查不通过,且无法自动修复
3. 用户主动说"切换 / 换一家 / 切到 X"

触发方式

• 自然语言:"用 claude code 帮我重构 utils.py" / "claude code review 一下这个 PR"
• 显式命令:/claude-code-allinone <你的编程需求>(强制走本 skill)
• 报错触发:用户贴出 command not found: claude / Onboarding has not been completed / ANTHROPIC_AUTH_TOKEN is not set 等

详细流程

Step 0 — 运行 doctor.sh 检测环境

每次触发都先运行 bash scripts/doctor.sh,它会输出一个 JSON,包含:

{
  "claude_installed": true,
  "claude_version": "2.1.143",
  "claude_outdated": false,
  "config_state": "clean | managed-by-skill | user-managed",
  "active_profile": "agentplan | custom | null",
  "user_settings_summary": {"base_url": "...", "model": "..."} | null,
  "user_health": {"is_healthy": true/false, "checks": [...], "issues": [...]} | null,
  "onboarding_complete": true,
  "ark_api_key_set": true,
  "custom_api_key_set": false,
  "ark_managed_env": true,
  "ark_agent_plan": true,
  "ark_coding_plan": false,
  "ark_api_key_managed": true,
  "ark_model_id": "ark-code-latest",
  "issues": []
}

根据 config_state 决定走哪条路径。

Step 1 — 安装 / 升级 Claude Code CLI(仅首次需要)

scripts/install.sh 的行为:

Step 2 — 配置模型服务(仅路径 ① 触发)

默认行为:不问选项,直接走 AgentPlan

减少用户感知是核心原则。不要主动给用户列 A/B 菜单。除非用户主动说"我有自己的 Anthropic 兼容网关 / 自定义 base_url / 别的模型 Key",否则一律默认进入 AgentPlan 配置流程。

零感知首选:扫环境变量自动配好

ArkClaw / OpenClaw 沙箱会自动注入当前账号的套餐和 Key 信息,本 skill 应优先利用这些变量做零感知配置,避免让用户再粘贴一次 Key。

doctor.sh 输出会包含:

{
  "ark_managed_env": true,
  "ark_agent_plan": true,
  "ark_coding_plan": false,
  "ark_api_key_set": true,
  "ark_api_key_managed": true,
  "ark_model_id": "ark-code-latest"
}

实现细节:setup-agentplan.sh --auto 内部带三层防护:(1) 本地格式自检挡掉粘错的输入;(2) 调用 /models endpoint 做活性 ping(不消耗推理 token,3 次重试,仅 401/403 视为失败);(3) AgentPlan 401 且 ARK_CODING_PLAN=true 时自动 exec 转发到 setup-codingplan.sh --auto --from-fallback。所以即使 skill 选错或双开账号 AgentPlan Key 失效,都不会真的把错 Key 写进 profile。

传统首次配置(仅在零感知不可用时触发)

向用户输出:

准备给你配置 Claude Code,使用火山方舟 AgentPlan(套餐内额度,ark-code-latest 智能路由)。

请粘贴 AgentPlan 控制台分配的专属 Key:

拿到 Key 后立即跑:

bash scripts/setup-agentplan.sh "$KEY"

何时走自定义网关分支?

只有以下情况才询问/触发 custom 流程,不要主动给用户列菜单:

• 用户主动说:"我有自己的 Anthropic 网关" / "用我们公司的 base_url" / "我有 claude-code-router" / "用 Bedrock / Vertex 转出来的端点"
• 用户主动给出 base_url + Key + model 三件套
• 用户主动说"我没有 AgentPlan Key,但我有别的 Anthropic 兼容端点"

触发后引导用户依次给出 3 个信息,然后跑:

bash scripts/setup-custom.sh "$BASE_URL" "$KEY" "$MODEL"

⛔ 不允许在用户没提"自定义/别的网关/我的 Key"等关键词时,主动展示 A/B 菜单或让用户做选择。这会增加感知,违背"默认 AgentPlan + 零感知优先"原则。

配置脚本会自动完成:写 Key → 写 settings.json → 写 ~/.claude.json 的 hasCompletedOnboarding: true → .token 文件落盘。如果用户已有 settings.json,会先备份再覆盖。

Step 3 — 兼容性检查(仅路径 ③ 触发)

当 doctor.sh 返回 config_state == "user-managed" 时,说明用户之前手动写过 settings.json。此时读取 user_health 字段:

检查通过(is_healthy == true):

• 不打扰用户,直接当作"已配好",进入正常使用

检查不通过(is_healthy == false): 向用户展示具体问题,并询问:

检测到你已有的 claude code 配置存在以下问题:
  1. <具体问题描述>
  2. <具体问题描述>

你希望:
  A. 让本 skill 帮你重新配置(推荐,会先备份你现有的文件)
  B. 我自己去修改

请回复 A 或 B。

Step 4 — 正常使用(智能路由 review / build 模式)

bash scripts/run.sh "用户的完整需求原文"

run.sh 内部会:

1. 关键词扫描决定 mode:
   • 命中 "review / 评审 / 审查 / 看一下 / 分析 / 评估 / 检查 / lint / 评 / read-only" → review 模式(--permission-mode plan)
   • 否则默认 build 模式(--allowedTools "Read,Glob,Grep,LS,Bash,Edit,Write")
2. 用 nohup setsid + </dev/null + log file + 110s PID polling 跑 claude(避免 PTY 挂起)
3. 把日志末尾原样返回

也可以由 Agent 显式指定:

bash scripts/run.sh --mode review "用户需求"
bash scripts/run.sh --mode build  "用户需求"

Step 5 — 切换模型服务(用户主动要求时)

仅当用户明确说"切换 / 换一家 / 切到 X / 换成自定义 / 用回 AgentPlan"等关键词时触发,不要主动建议切换。

bash scripts/switch-profile.sh             # 列出已配置的服务
bash scripts/switch-profile.sh agentplan   # 切换到 AgentPlan
bash scripts/switch-profile.sh custom      # 切换到自定义网关

切换实际上是把 ~/.claude/settings.json 替换为目标 profile 的内容(同时同步 .token 文件),并把 ~/.claude/active-profile 写成目标名。

关键配置点(踩坑后的硬约束)

这是 v3.1 现网走通后总结出的必须遵守的规则,违反就报错。

健康检查都检查什么?

Profile 设计

每个模型服务在 ~/.claude/profiles/ 下有一个 settings.json 模板:

~/.claude/profiles/
├── agentplan.json    — 火山方舟 AgentPlan(ark-code-latest,base_url /api/plan)
├── codingplan.json   — 火山方舟 Coding Plan(ark-code-latest,base_url /api/coding)
└── custom.json       — 自定义 Anthropic 兼容网关(占位符 __BASE_URL__ / __MODEL__)

~/.claude/settings.json 是当前激活配置的实际内容(由 setup / switch 脚本写入),~/.claude/active-profile 文件记录当前是哪一个。

必读参考文档

安全规则

• 用户的 Key 只保存在 ~/.bashrc、~/.claude/.token 和 ~/.claude/profiles/*.json 中(用户家目录内)
• 覆盖配置前自动备份到 ~/.claude/settings.json.bak.<时间戳>
• 不上传任何外部服务,不在日志中记录 Key 明文
• ⛔ 不会出现在日志或 stdout 的任何地方打印完整 Key

不做什么

• ❌ 不尝试连接 Anthropic 官方服务(沙箱网络在境内 IDC,连不上 anthropic.com)
• ❌ 不自动猜测 Key,所有 Key 必须由用户主动粘贴
• ❌ 不做 Codex 的配置(那是另一个 skill,叫 codex-allinone)
• ❌ 不在用户没确认前覆盖已有的 settings.json
• ❌ 不接管 review/build 之外的复杂权限模式(如 bypassPermissions、dontAsk),那是用户自己的事

常用对话示例

给用户的"人话提示"模板(必须遵守)

skill 与用户沟通时,禁止出现 profile / token / settings.json / apiKeyHelper / onboarding 这类内部术语。下表是对应的人话翻译,凡需告知用户错误时一律按此输出: