如果你最近关注过 AI 编程工具一定绕不开 Claude Code。在终端里以自然语言给它下达任务它就能读取代码、定位问题、修改文件、运行命令甚至反复调试直到通过测试。这种体验和过去“人写代码、AI 补全”完全不同更像是在带一个能独当一面的实习生。不过新问题也来了既然 AI 能写代码我们怎么验收它的能力靠肉眼盯屏幕靠一遍遍重复提问这也是我关注到 “Show HN: Claude Code Arcade” 这类项目的原因。单看名字它像是一个给 Claude Code 玩的“游戏厅”但我的判断是它真正想做的是把 Agent 的验证过程变成一套可复现、可计分、可回放的任务关卡系统。这个思路的价值远不止“好玩”。所以这篇文章会把两层内容一次性讲透先分析 Claude Code Arcade 这类项目背后的工程逻辑再带你从零装好 Claude Code、完成 settings.json 配置并照“Arcade 闯关”的思路自己搭一个能自动评分的最小验证脚本。1. “Claude Code Arcade”到底是一个什么东西先说结论Claude Code Arcade 不是一个官方产品更像是开发者社区里典型的 Show HN 项目。Show HN 是 Hacker News 上开发者用来展示自己原型项目的一种主题标签意味着这个项目可能还很早期但作者愿意把想法拿出来接受大家试用和讨论。单从命名习惯来看Arcade 这个词通常包含三层可能的含义理解方向说明作品合集式体验馆把多个小任务、小游戏集中在一起让 Claude Code 逐个完成并展示能力Agent 能力训练场通过设计好的关卡反复让 Agent 完成特定挑战观察它在不同约束下的表现自动化评测框架每个关卡都有明确目标和评分脚本把 Agent 的行为转成可量化的结果按目前能看到的公开资料推断它大概率不是一个“在终端里玩俄罗斯方块”的普通游戏库而是位于“展示”和“评测”之间的产物。它真正提供的价值是让开发者意识到AI Agent 的能力边界必须在具体的任务里才能被看见。这种“Arcade”思路的重点只有四个字关卡、验收。每个任务都是独立关卡每个关卡都有明确目标Agent 做完之后由脚本检查结果而不是靠人脑判断。它让“这个模型能不能写好代码”这种模糊问题变成“这个 Agent 能不能通过这一关”这样可验证的问题。如果你也在做 Agent 应用真正值得从这类项目里学到的不是具体某个小游戏写得多漂亮而是它如何把一次性的“灵魂提问”改造成可持续运行的Agent 验收流水线。1.1 为什么这样的项目会在现在出现如果用一句话概括当前 Agent 工具链的现状模型能力已经超过了配套工程能力。模型越来越聪明但谁来定义“聪明”、谁来持续测试“聪明”至今没有标准答案。过去我们写单元测试是因为函数行为是确定性的。给入参、等出参、比对结果一个用例就能守住一个功能。但 Claude Code 这类 CLI Agent 的行为是非确定性的它可能先读文件再搜索可能一次改对也可能试三次可能用 Python 也可能临时起意用 Shell。如果你没有一套“关卡系统”想评估它的能力就只能靠感觉。Claude Code Arcade 这类项目的核心贡献是把“测试 Agent”这件事产品化了用任务当输入用结果当输出用关卡来对冲不确定性。这也是为什么我认为它值得单独写一篇而不是当作一个娱乐向的小玩具。2. Claude Code 为什么突然这么受关注要理解 Claude Code Arcade必须先理解 Claude Code 本身。Claude Code 是 Anthropic 推出的终端编程 Agent。它不只是一个 IDE 插件而是在命令行里直接运行的智能体它能读取项目文件、搜索代码、调用工具在获得授权后直接修改文件、执行命令然后继续观察结果形成“思考—行动—验证”的循环。过去开发者的工作流是打开 IDE写代码跑测试看报错手动修。现在可以变成在项目根目录启动 claude描述需求Agent 自己去拆解并执行开发者在关键节点审核。传统 AI 编程辅助与 Claude Code 的一个关键区别如下对比维度Copilot 式补全Claude Code 式 Agent交互方式跟随光标边写边补接收任务自主执行工作方式生成代码片段调用工具、管理文件、执行命令需要的人工介入每步都需要接受/修改只在策略节点授权验收方式靠开发者逐行看靠运行结果和测试反馈这带来的体验变化是巨大的以前 AI 是“输入法”现在 AI 是“结对同事”。但“结对同事”也会犯错所以我们需要 Arcade 式的任务关卡来持续验证它的能力。2.1 生态里的常用概念现在和 Claude Code 相关的高频词越来越多这篇文章后面会反复用到几个概念先帮你梳理清楚Agent能自主规划并调用外部工具完成任务的 AI 系统Claude Code 就是面向编程场景的 Agent。Skill一组预置的能力包包含专门的行为指令和参考示例。Agent 在遇到对应任务时可以通过 Skill 激活避免每次从零摸索。MCP全称 Model Context Protocol是一种让 Agent 统一连接外部工具/数据的标准协议解决“每个工具都要单独集成”的问题。Settings.jsonClaude Code 的配置文件集中控制权限、模型、钩子、环境变量等。沙箱/隔离环境Agent 修改文件有风险因此在独立、可丢弃的目录或容器里执行任务是工程上最基本的防线。把这些概念连起来你就有了理解 Claude Code Arcade 的完整地图Arcade 提供关卡任务Agent 负责闯关Skill 相当于 Agent 平时积累的“技能书”而 MCP 则相当于 Agent 的“外接工具箱”。3. 安装 Claude Code 并完成基础验证不管你最终是要复现一个 Claude Code Arcade 项目还是只想把它当普通开发工具用第一步都是把它装到自己的终端里。3.1 安装前确认环境Claude Code 是一个终端工具对运行环境有一定要求。在实际动手前先确认三件事操作系统macOS、Linux 都可以直接在终端安装Windows 上最稳妥的方式是使用 Windows Terminal WSL这样能避免很多原生终端兼容性问题。Node.js官方推荐使用较新的 Node.js LTS 版本。你可以用下述命令检查版本node -v npm -v账号凭证使用 Claude Code 需要 Anhtropic 账号凭证或你所使用的 API 服务商提供的密钥。具体获取方式请以官方文档为准不要相信任何来路不明的“免费 key”。版本细节我这里不写死因为工具迭代很快。更推荐的做法是看官方 README 的 prerequisites 部分一般会明确最低版本要求。3.2 npm 全局安装与验证在满足前置条件后打开终端执行# 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 查看版本确认安装成功 claude --version安装完成后如果claude命令找不到通常是 Node.js 的全局 bin 目录不在 PATH 中。可以先执行npm bin -g然后把输出目录加入系统的 PATH。运行claude或claude --version不再报错说明核心程序已经装好。3.3 两种基本启动方式Claude Code 有两种最常见的启动方式后续做 Arcade 关卡时也会用到# 方式一交互式启动适合手动沟通 claude # 方式二非交互式一次性指令适合被脚本调用 claude -p 请帮我看看当前目录里有什么代码交互模式适合你亲自盯着它改代码-p参数print 模式则适合自动化脚本。Arcade 类的自动化关卡本质就是不断调用-p模式并向脚本索取结果。启动失败时不必慌先按顺序检查 Node 版本、npm 全局路径、账号鉴权三个环节大多数问题都能解决。4. settings.json 配置模型与权限Claude Code 安装好还不够要让它在真实任务中稳定工作你必须理解 settings.json。很多群里讨论的“模型不识别”“权限失效”问题基本都是这一层配置出了问题。4.1 settings.json 放在哪里Claude Code 支持多级配置文件常见位置包括用户级~/.claude/settings.json作用于当前用户的所有项目。项目级.claude/settings.json放在当前项目根目录下建议提交到仓库中。本地级.claude/settings.local.json适合写个人的密钥、本地环境变量不建议提交。一套推荐的 settings.json 示例如下{ env: { ANTHROPIC_MODEL: your-model-id }, permissions: { deny: [Bash(npm publish:*), Bash(rm -rf:*)], allow: [Read, Glob] }, statusLine: { type: command, command: echo Claude Code Ready } }注意上面代码里your-model-id需要替换成你实际要用的模型标识。环境变量、权限策略的具体字段以你当前安装版本为准。每台机器、每个项目目录下生效的配置可能不同误改配置后优先检查是哪一层文件覆盖了另一层。4.2 权限配置别把控制权全交出去很多刚开始用 Claude Code 的人会贪图方便把权限全开这是很危险的做法。即使是在测试项目里也建议遵循最小权限原则只允许 Agent 读文件在明确授权后再允许它写文件。我通常这样处理先用只读权限让 Agent 做分析和计划审阅后切换成允许编辑的模式需要执行高风险命令时再按需授权。把allow列表写得越短你的项目越安全。4.3 为什么会出现“模型不被识别”搜索热度很高的一条报错是类似这样的xx-model is not a model this version of claude code recognizes这个问题多半不是你安装错了而是三种情况之一settings.json 里的ANTHROPIC_MODEL或启动命令里指定的模型名与当前服务商/兼容网关提供的模型 ID 不一致。当前 Claude Code 版本内置的模型识别列表还没有覆盖新模型 ID升级或换用已支持的名字即可。环境变量里的接口地址与密钥不匹配导致 Agent 拿着 A 服务商的密钥请求 B 服务商的接口。碰到这种报错第一步打开claude model查看当前可用模型列表确认你填写的 ID 是否在列表内第二步检查 settings.json 的 env 区域第三步确认 API 兼容地址正确。不要靠瞎猜反复重启错误提示里通常已经说了是模型名问题还是版本问题。4.4 使用兼容网关切换模型时要注意什么现在很多人会把 Ollama 或各类兼容第三方 API 接入 Claude Code本意是省 token、做本地验证。切换本身可行但容易踩坑的地方也很集中模型 ID 不匹配、接口路径不对、密钥混淆、上下文长度不支持。严格确认你使用的服务商/SDK 官方提供的 Anthropic 兼容地址。切换模型后先跑一个最小指令例如claude -p hi。不要直接在一个仓库里换模型跑全量任务先在临时目录里做冒烟验证。Arcade 类项目对模型 ID 尤其敏感因为自动化脚本通常会用环境变量固定模型名。如果你换模型跑关却一直失败优先怀疑模型名被写死而不是关卡写得有问题。5. 照 Arcade 思路做一个最小闯关系统理解完概念和配置下面进入最有价值的部分自己搭一个极简的“Arcade 关卡”。我不打算让你去复制一个完整开源项目而是用最小的文件结构演示关卡机制。它的核心只有三样东西一个任务定义、一个带 bug 的项目、一个评分脚本。Agent 闯关成功后脚本会自动判定并输出分数。5.1 目录结构arcade-demo/ ├── levels/ │ └── fix-average/ │ ├── task.md │ └── project/ │ └── calc.py ├── runner.sh └── verify.sh这个结构模拟的关卡叫做 fix-average给 Claude Code 一个“算平均分”的小脚本但脚本里藏着一个会导致运行报错的 bugAgent 必须定位并修复它。5.2 关卡任务与初始代码先创建关卡任务说明levels/fix-average/task.md# 关卡修复平均分计算 - 请阅读 project/calc.py - 当前脚本运行会报错原意是计算若干分数的平均值 - 只允许修改 project 目录内的代码 - 不要删除文件不要引入新的第三方依赖 - 修改完成后运行 python3 project/calc.py输出应为 20.0接着在project/calc.py中放入一个故意写错的脚本# 文件路径arcade-demo/levels/fix-average/project/calc.py def average(scores): total 0 for score in scores: total score count len(score) # Bug这里是 score不是 scores return total / count if __name__ __main__: print(average([10, 20, 30]))这个 bug 很典型变量score在循环内是一个整数对它调用len()会直接抛出TypeError导致程序崩溃。Agent 只要运行脚本就能看到报错然后追踪到count len(score)这一行把它改成len(scores)程序就能正确输出20.0。5.3 任务启动脚本 runner.sh为了把闯关过程的“人工操作”降到最低我们写一个 runner.sh 自动把任务目录复制到临时工作区再调用 Claude Code 的非交互模式执行任务#!/usr/bin/env bash # 文件路径arcade-demo/runner.sh set -euo pipefail LEVEL_DIRlevels/fix-average WORK_DIR.arcade-run # 1. 每次闯关都从干净副本开始避免上一次修改影响结果 rm -rf $WORK_DIR mkdir -p $WORK_DIR cp -r $LEVEL_DIR/project $WORK_DIR/project # 2. 以任务描述作为系统指令把修改任务交给 Claude Code CLAUDE_CMD${CLAUDE_CMD:-claude} $CLAUDE_CMD -p 请阅读 $LEVEL_DIR/task.md并在 $WORK_DIR/project 目录中完成修复。 \ --allowedTools Read Write Bash \ --output-format json agent_round_1.log 21 || true echo agent 执行完毕日志已保存到 agent_round_1.log echo 开始执行关卡评分...脚本里我特意加了|| true是因为即使 Agent 修复失败我们仍然希望评分脚本能给出明确结果而不是让 runner 的中断掩盖真实情况。日志会被完整保存方便之后回放分析。5.4 评分脚本 verify.sh评分脚本是这个系统的“裁判”。它不关心 Agent 过程中说了什么只看修复后程序的行为是否符合任务要求#!/usr/bin/env bash # 文件路径arcade-demo/verify.sh set -euo pipefail WORK_DIR.arcade-run if [ ! -f $WORK_DIR/project/calc.py ]; then echo FAIL: project/calc.py 不存在 exit 1 fi # 执行修复后的脚本并捕获输出 ACTUAL_OUTPUT$(python3 $WORK_DIR/project/calc.py 21) || { echo FAIL: 脚本执行报错$ACTUAL_OUTPUT exit 1 } EXPECTED_OUTPUT20.0 if [ $ACTUAL_OUTPUT $EXPECTED_OUTPUT ]; then echo PASS: 输出正确得分 1/1 exit 0 else echo FAIL: 预期输出 $EXPECTED_OUTPUT实际输出 $ACTUAL_OUTPUT exit 1 fi最后执行chmod x runner.sh verify.sh ./runner.sh ./verify.sh如果一切顺利你会看到类似输出agent 执行完毕日志已保存到 agent_round_1.log 开始执行关卡评分... PASS: 输出正确得分 1/1这个最小系统已经具备 Arcade 的两个核心要素Agent 在隔离目录里执行修复脚本根据最终行为评分。你可以把 calc.py 换成任何带 bug 的业务代码把 verify.sh 换成任意测试逻辑这套关卡就能复用到各种场景。6. 从“跑通一个关卡”到“跑通一整套验收”上面只是一个最小示例真正运营一个 Claude Code Arcade 类项目需要在此基础上增加几层工程能力。6.1 测试任务目录要与真实工作区隔离最需要注意的是环境隔离。无论你的 Agent 有多强只要它直接修改真实代码库任何一次错误判断都可能覆盖你没有提交的代码。Arcade 类测试的通用做法是每次运行都从 Git 标签或干净副本创建临时目录Agent 只允许在临时目录里操作。如果你的场景必须让 Agent 修改真实仓库那至少要做到三点先创建独立分支、提交一次初始快照、给 Agent 配置最小权限。Agent 改完以后由人工 review diff确认无误再合入。6.2 用多关卡跑回归一个关卡只能证明 Agent 能完成一类问题。要让 Arcade 有价值你需要把它们积累成一个回归测试集第一关修复一个语法错误。第二关重构一段重复代码并保证测试通过。第三关按需求文档新增一个接口。第四关根据失败测试反推并定位 bug。这四个关卡难度递增、考察能力不同正好覆盖 Agent 编程中最常见的几类行为。每次更换模型版本、修改提示词模板或升级 Claude Code都可以用同一套关卡回归一遍。在实现时可以考虑把每个关卡目录里的 task.md 做得更严格明确“可修改范围”“禁止事项”“验收命令”因为 Agent 并不会自动按照人的常识去行动。Task 描述越无歧义评审结果越可信。6.3 日志回放比评分结果更重要如果只想看“过没过”跑一个二进制脚本就行。但关卡系统最重要的资产其实是日志。agent_round_1.log 里记录着 Agent 的每一步思考工具调用和修改动作遇到关卡失败时回放日志能让你快速定位是模型理解错了、操作顺序错了还是测试脚本本身有歧义。所以不要只把日志写到标准输出再丢弃建议保存带时间戳的文件例如LOG_FILElogs/level_$(date %Y%m%d_%H%M%S).json这样每一次模型升级后的尝试都是可追溯的你才能判断一个 Agent 是“变强了”还是“碰巧过了”。7. Claude Code 常见问题与排查方法下面整理安装和配置中最常见的几类问题。这些问题不只在 Arcade 项目会出现日常用 Claude Code 也躲不开。问题现象可能原因排查方式解决方案安装后claude命令不存在npm 全局 bin 目录不在 PATH执行npm bin -g查看路径把该目录加入 PATH 后重开终端Windows PowerShell 下启动失败原生终端与 CLI 兼容问题改用 Windows Terminal 检查版本优先使用 WSL 环境安装运行报错could not locate the claude cli on path当前 shell 环境找不到 claude 可执行文件which claude确认路径检查全局安装路径与当前 shell PATH报错xx is not a model this version recognizes模型 ID 与当前版本不匹配claude model查看可用模型列表更新模型 ID 或升级 Claude Code提示组织禁用了订阅账号权限或订阅状态问题查看账号控制台和接口返回信息使用具备权限的账号并按授权范围操作终端输出乱码编码或字体问题检查locale和终端编码设置设置 UTF-8 编码并改用支持中文的终端字体Token 消耗太快未设置预算和精简提示词查看日志中的 token 统计限制上下文长度、关闭不必要工具、使用更短的 task.mdAgent 改坏了代码直接在真实目录运行且权限过大查看 git diff 和操作日志使用隔离副本、设置允许名单、提交前审查如果遇到报错不知道怎么处理先从日志入手。Claude Code 在-p模式下会输出结构化 JSON里面既包含模型的请求响应也包含工具调用记录。第一次排查时把它完整打开找到第一个异常点通常就能定位问题。8. Claude Code Arcade 类项目的工程建议把上面的内容沉淀成工程经验有几条建议值得反复强调模型和版本要固定下来。Agent 的能力受底层模型影响很大Arcade 评测如果没有固定模型和工具版本今天过明天挂你根本无法判断是回归还是噪声。用可回放的日志替代肉眼观察。把每一轮 Agent 操作完整落盘比任何“现场盯屏”都有价值。关卡任务先写验收标准再写任务描述。很多 Agent 效率低不是因为模型笨而是因为任务说明里没有写清楚“怎样才算完成”。把 verify 脚本先写好Agent 才知道自己该朝哪个方向收敛。控制单次任务的执行预算。给 Agent 设定时间或 token 上限避免一个错误方向让它无限循环下去。runner 脚本里可以加一条 timeout 命令在 Agent 超时后强制结束本轮闯关。权限最小化是底线。即使只是测试脚本也不要让 Agent 拥有整台机器的完全控制权。允许名单越短你后续修复问题的成本越低。不要在配置文件里写明文密钥。settings.local.json 虽然可以存放本地环境变量但如果你要提交项目级配置务必确保里面没有密钥并且生产环境密钥通过环境变量或密钥管理服务注入。如果未来你要把这类关卡接入团队 CI建议把运行阶段进一步分成 smoke、daily、release 三档每次提交只跑一道最小关卡每晚跑全部日常关卡发版前再配合真实回归测试跑关键路径。这样既能快速反馈又不会因为 Agent 评测的偶发性阻塞正常开发。9. 总结从“游戏厅”到“验收场”回过头再看 “Show HN: Claude Code Arcade” 这个项目名我觉得它真正打开了一个值得持续跟踪的方向把 Agent 能力测试变成一套带关卡、带评分、带回放的系统化工程。表面上看是让 Claude Code 玩游戏实际上是让每个开发者都能用最小成本回答一个关键问题——这个 Agent 到底能不能完成我定义的那类任务。这篇文章带你完成了三件事理解了 Claude Code Arcade 背后的运行逻辑完成了从安装到 settings.json 配置的实操搭建了第一个能自动执行、自动评分的 Agent 闯关脚本。有了这套最小框架你可以开始往里面添加自己的关卡。如果你也打算尝试建议从一个小步骤开始挑一个最近困扰过你的经典 bug把那块出问题的代码摘出来做成一个隔离关卡再让 Claude Code 从零修复并自动评分。跑通第一关之后再扩成十个、二十个关卡你会开始真正了解你的 Agent而不是只能感叹它“有时聪明有时笨”。这套思路的本质其实很简单不能量化就无法改进。Arcade 不是让 Agent 去玩而是让我们找到一种更靠谱的方式去衡量 Agent。下一步就可以把你自己的“第一关”设计出来了。