1. 项目概述零成本构建你的专属AI智能体如果你和我一样已经订阅了Claude Pro、Max或Team计划每个月都在为那个强大的Claude Code编辑器付费那你有没有想过这个编辑器本身就是一个近乎完美的AI智能体运行时环境我们一直在寻找各种复杂的AI Agent框架却忽略了手边最强大、最经济的选择。UnClaw这个项目就是基于这个简单到近乎“狡猾”的洞察诞生的既然Claude Code已经内置了工具调用、文件访问、Shell执行、子代理管理和MCP服务器连接能力我们为什么还要去维护一个独立的、需要额外支付API费用的运行时框架UnClaw不是一个传统意义上的“框架”。它没有一行运行时代码不依赖任何npm包也不需要你启动一个独立的守护进程。它本质上是一个精心设计的目录结构和配置文件模板。当你把这个模板克隆到本地并在Claude Code中运行一次/setup命令后Claude Code就会“变身”为一个拥有持久身份、长期记忆、自动调度和专属技能的个人AI智能体。整个过程不产生任何额外的API调用费用完全运行在你已有的订阅额度内。这对于个人开发者、独立创作者或者小团队来说意味着你可以拥有一个7x24小时在线、深度了解你工作习惯的AI伙伴而成本几乎为零。这个项目的核心哲学非常吸引我“最好的AI智能体框架就是你最终删除的那个。”它摒弃了所有不必要的抽象层和中间件直接利用Claude Code的原生能力。你得到的是一个高度个性化、可完全掌控的智能体而不是一个黑盒服务。接下来我将详细拆解我是如何从零开始部署、定制并深度使用UnClaw的分享其中的关键步骤、配置细节以及我踩过的一些坑。2. 核心理念与架构设计解析2.1 为什么选择“零运行时”架构在接触UnClaw之前我评估过OpenClaw和NanoClaw。OpenClaw功能强大但架构复杂超过50万行代码和70多个依赖就像一个需要精心维护的“数字城堡”。NanoClaw轻量一些但仍然需要运行一个自定义的Node.js进程。它们共同的问题是它们都无法使用你的Claude Max订阅。这意味着即使你每年支付数百美元订阅费运行这些框架产生的所有Token消耗都会走独立的API计费通道额外成本可能非常惊人。UnClaw走了另一条路。它认识到Claude Code本身已经是一个功能完备的Agent运行时工具执行可以直接运行Python、Node.js脚本调用系统命令。文件系统访问能读取、创建、修改项目内的任何文件。子代理Subagents可以创建专门化的子会话来处理特定任务。MCPModel Context Protocol服务器集成可以连接外部数据源和服务。技能Skills系统通过.claude/skills/目录下的Markdown文件扩展能力。既然运行时已经存在且功能强大UnClaw要做的就不是“重建轮子”而是“定义角色和规则”。它的全部工作就是通过一组配置文件CLAUDE.md,SOUL.md, 规则文件技能文件来“教导”Claude Code如何扮演一个具有持续性、记忆性和主动性的智能体角色。这种架构带来了几个决定性优势零额外成本所有交互都在Claude Code的会话内完成消耗的是你订阅的对话额度对于Max用户通常是充裕的没有一分钱API费用。零维护负担没有需要更新的依赖包没有需要适配的框架版本。当Anthropic更新Claude Code时你的智能体自动获得所有新特性完全无需改动。极致透明与可控智能体的“大脑”记忆、“性格”SOUL和“技能”全是纯文本文件你用任何编辑器都能查看和修改。没有编译没有打包没有黑魔法。2.2 核心文件系统架构剖析理解UnClaw就是理解它的目录结构。每个目录和文件都有明确的职责共同构成了智能体的“身体”。my-agent/ # 智能体根目录 ├── CLAUDE.md # 智能体的“操作系统”和主配置文件 ├── identity/ # 智能体的身份核心 │ ├── SOUL.md # 性格、声音、边界定义“灵魂” │ ├── user.md # 用户你的个人资料和偏好 │ └── memory.md # “热”记忆每次会话必载 ├── memory/ # “冷”记忆存储项目历史、决策记录 ├── daily-logs/ # “原始”记忆完整的每日会话日志 ├── .claude/ # Claude Code原生配置扩展 │ ├── rules/ # 行为规则和安全护栏 │ │ ├── security.md # 安全规则如文件访问限制 │ │ ├── communication.md # 沟通风格规则 │ │ └── domain.md # 领域特定规则由/setup生成 │ ├── skills/ # 技能库 │ │ ├── heartbeat/ # /heartbeat 技能 │ │ ├── promote/ # /promote 技能 │ │ └── ... # 其他自定义技能 │ ├── scripts/ # 辅助脚本Python索引器、Shell工具 │ └── settings.json # Claude Code钩子Hooks配置 ├── config/ # 环境配置 │ └── agent.env # 会话名称、频道设置 └── bin/ # 可执行脚本 ├── setup.sh # Shell版安装脚本备选 └── start-agent.sh # 在tmux中启动智能体的脚本关键文件解读CLAUDE.md这是智能体启动时读取的第一个文件相当于它的“主程序”。它通过import指令将identity/SOUL.md、identity/user.md、identity/memory.md以及.claude/rules/下的所有规则文件加载到上下文中。你可以把它理解为智能体的启动清单和核心指令集。identity/SOUL.md这是智能体的“人格芯片”。在这里你定义它的名字比如我叫我的“Atlas”、它的核心职责例如“你是我的技术副手专注于代码审查、系统架构设计和自动化脚本编写”、它的沟通语气是严谨正式还是轻松幽默、它的工作原则以及绝对不可逾越的边界比如“未经明确确认不得执行rm -rf或修改生产环境文件”。这个文件的质量直接决定了智能体与你协作的“手感”。.claude/rules/这是智能体的“交通法规”。security.md定义了文件系统访问白名单、网络请求限制等安全策略。communication.md规定了它如何向你汇报进度、何时需要确认。domain.md则是在运行/setup时根据你为智能体选择的角色如“开发助手”、“内容写手”自动生成的领域特定规则例如为开发助手添加代码规范为内容写手添加SEO和语调要求。.claude/skills/这是智能体的“技能工具箱”。每个技能都是一个独立的Markdown文件存放在以技能名命名的子目录下。Claude Code会自动发现这些技能并将其作为可用的/命令。例如/heartbeat技能会让智能体定期检查系统状态并汇报待办事项/research技能会调用MCP服务器进行网络搜索。添加新技能就像在目录里新建一个文件夹一样简单。这种基于纯文本和目录的架构使得版本控制Git变得极其自然。你可以清晰地追踪智能体“人格”和“能力”的每一次演变。3. 从零开始的完整部署与配置实战3.1 环境准备与初始设置部署UnClaw的前提是拥有Claude Code。如果你还没有需要先去 claude.ai/download 下载并安装。确保你的Claude账号拥有Pro、Max、Team或Enterprise订阅这是零成本运行的关键。第一步克隆模板并进入打开你的终端执行以下命令。我建议将my-agent替换为你想要的智能体名字比如dev-assistant或writing-buddy。git clone https://github.com/shahshrey/unclaw dev-assistant cd dev-assistant这个过程只是下载了一个包含配置模板的Git仓库没有任何依赖需要安装。第二步启动Claude Code并运行设置在终端中进入刚才克隆的目录然后启动Claude CodeclaudeClaude Code界面打开后你会在输入框看到一个提示符。关键的一步来了直接在输入框中键入/setup然后回车。这不是一个Shell命令而是Claude Code的一个“技能”指令。此时Claude Code在模板文件的引导下会启动一个交互式的设置向导。整个过程非常直观身份创建它会问你“我应该叫什么名字”、“我的核心角色是什么例如软件开发助手、研究分析师、内容策略师”。请认真思考并回答。我给我的命名为“Atlas”角色是“全栈开发与DevOps助手”。这个定义会直接写入identity/SOUL.md。记忆结构初始化向导会自动创建identity/memory.md热记忆、memory/目录冷记忆和daily-logs/目录原始记忆。它还会初始化一个SQLite数据库用于全文搜索记忆。钩子Hooks安装它会修改.claude/settings.json添加会话生命周期钩子。例如SessionEnd钩子会在每次会话结束时自动触发将本次对话的总结写入daily-logs/。这是实现“永不遗忘”的基础。Telegram Bot连接可选如果你希望能在手机上与智能体对话这里可以配置Telegram Bot。你需要提前通过BotFather创建一个Bot并获取Token。配置后你就可以在Telegram里像和朋友聊天一样向你的智能体提问了。调度任务设置可选macOS对于macOS用户向导会提示你安装launchd定时任务用于执行/heartbeat心跳检查、/promote记忆提炼等后台作业。如果你跳过后续也可以手动配置。重要提示整个/setup过程实际上是Claude Code在“阅读”模板中的说明文件并据此执行一系列文件创建和修改操作。它完美诠释了“智能体配置自己”的理念。如果遇到网络问题导致某些步骤失败比如下载Telegram依赖你可以选择跳过后续再手动补全。3.2 深度定制打造属于你的数字伙伴初始设置完成后一个基础版的智能体就已经就绪了。但真正的威力在于深度定制。以下是我对几个核心部分的调整经验。塑造人格编辑identity/SOUL.md不要满足于设置向导生成的基础内容。打开identity/SOUL.md像编写一份详细的岗位说明书一样去完善它。我的SOUL.md包含了核心使命“你的首要目标是提升我的开发效率和代码质量。你是我在技术决策上的第一道过滤器。”沟通协议“以简洁、精准的技术语言沟通。在提出方案时必须同时说明利弊。对于高风险操作如数据库变更、生产部署必须分步确认。”知识边界“你精通Python、Go、JavaScript/TypeScript和相关的云原生技术栈。对于你不熟悉的领域如深度学习模型训练应明确告知并建议学习路径或寻求专家子代理。”工作流集成“你拥有对我~/Projects目录的只读权限对~/Projects/sandbox有读写权限。你应主动了解我当前活跃的项目通过读取memory/active_projects.md。”扩充技能库在.claude/skills/中添加自定义技能UnClaw自带了一些实用技能但你可以轻松添加更多。例如我创建了一个code-review技能创建目录mkdir -p .claude/skills/code-review创建文件touch .claude/skills/code-review/SKILL.md编辑SKILL.md内容如下# 技能代码审查 (/code-review) 当用户触发此技能时对指定文件或目录进行系统的代码审查。 ## 工作流程 1. 理解用户请求的审查范围单个文件、Git Diff、PR描述。 2. 分析代码的以下方面 - **功能性**逻辑是否正确边界条件是否处理 - **可读性**命名是否清晰函数是否过于复杂 - **安全性**有无潜在的安全漏洞如SQL注入、命令注入 - **性能**有无明显的性能瓶颈 - **可维护性**是否符合项目约定的代码风格和架构模式 3. 以表格形式输出审查结果分为“严重问题”、“建议改进”和“亮点”。 4. 对于发现的问题尽可能提供具体的修改建议代码片段。 ## 示例 用户“/code-review 请看一下 src/auth/login.py 这个文件。” 你“正在审查 src/auth/login.py... 完成。以下是审查摘要[表格]”保存后重启Claude Code会话或等待它自动重新扫描技能目录新的/code-review命令就可以使用了。技能的威力在于它把复杂的、多步骤的交互模式固化成了一个简单的指令。配置记忆流转理解与调整三层记忆体系UnClaw的记忆系统是其持久性的核心理解它才能用好它。原始层 (Raw -daily-logs/): 这是未经加工的“日记”。每次会话结束SessionEnd钩子都会自动生成一个YYYY-MM-DD.md文件记录本次会话的完整摘要。这是所有记忆的源头。冷层 (Cold -memory/): 这是经过初步加工的“知识库”。通过运行/promote命令或由定时任务触发智能体会从最近的daily-logs中提取出重要的、具有长期价值的信息如项目关键决策、学到的技术要点、用户的重要偏好并将其整理成结构化的Markdown文件存入memory/目录。例如memory/project_x_architecture_decisions.md。热层 (Hot -identity/memory.md): 这是智能体的“工作记忆”。它被限制在约2500个Token以内并在每一次对话轮次中被加载到上下文窗口。这里应该只存放最高优先级、最常需要的信息当前正在进行的项目列表、本周核心目标、你的即时偏好比如“最近喜欢用FastAPI而不是Flask”。你需要定期手动或通过/memory-update命令来维护这个文件确保它精简而有效。我个人的调整我发现默认的/promote记忆提炼频率每天一次对于高强度工作来说有点低。我修改了templates/launchd/com.user.unclaw.promote.plist文件将StartInterval从8640024小时改为了4320012小时让智能体每天两次从对话日志中提炼知识记忆的保鲜度更高。4. 多智能体工作流按角色隔离的专家团队UnClaw最令我欣赏的设计之一就是它对多智能体的原生支持——通过简单的目录复制实现彻底的隔离。这完全符合Unix哲学“一个工具只做一件事并做到最好”。我是如何搭建我的专家团队的# 克隆三个独立的智能体实例 git clone https://github.com/shahshrey/unclaw atlas-dev git clone https://github.com/shahshrey/unclaw hermes-writer git clone https://github.com/shahshrey/unclaw gaia-researcher # 分别为它们进行设置 cd atlas-dev claude # 在Claude Code中输入 /setup角色选择“Senior Full-Stack Developer DevOps Engineer” # 配置独立的Telegram Bot Token cd ../hermes-writer claude # 输入 /setup角色选择“Technical Content Strategist Copywriter” # 配置另一个Telegram Bot Token cd ../gaia-researcher claude # 输入 /setup角色选择“Research Assistant Data Analyst” # 可以不配置Telegram仅通过终端使用这样做带来的好处是立竿见影的上下文纯净atlas-dev的identity/memory.md里全是关于代码库、服务器和CI/CD流水线的信息。hermes-writer的记忆里则是博客大纲、读者画像和SEO关键词。它们互不干扰每个智能体都能在专属领域内达到最深的理解。技能专精我在atlas-dev的.claude/skills/里添加了k8s-troubleshoot、database-migrate等技能。在hermes-writer里我添加了seo-optimize、tone-adjust技能。每个智能体的技能菜单都是高度定制化的没有无关功能的干扰。安全边界清晰通过.claude/rules/security.md我可以给atlas-dev访问生产服务器日志的只读权限而hermes-writer的规则则严格禁止执行任何Shell命令只能操作~/Documents/Articles目录下的文件。这种基于目录的权限隔离比在单一运行时内做复杂的权限管理要简单可靠得多。独立的沟通渠道我有三个Telegram Botatlas_dev_bot、hermes_writer_bot、gaia_research_bot。当我需要审查一段代码时我找Atlas当我想润色一篇技术博客时我找Hermes。沟通记录和上下文完全分离体验非常清爽。管理开销你可能会担心运行三个实例会很麻烦。实际上由于它们都是基于Claude Code你只需要在三个不同的终端窗口或tmux面板中分别运行claude命令即可。系统的资源消耗几乎可以忽略不计因为主要的计算发生在Anthropic的云端。本地只是运行着编辑器前端和几个后台定时任务脚本。5. 常见问题、故障排查与进阶技巧在实际使用UnClaw的几周里我遇到并解决了一些典型问题。这里分享出来希望能帮你绕过这些坑。5.1 安装与配置问题问题1运行/setup时卡住或报错。可能原因网络问题导致Claude Code无法下载某些资源如Telegram Bot的Bun运行时。解决方案检查Claude Code的版本是否为2.1或更高。在Claude Code界面输入/version查看。在/setup过程中如果遇到配置Telegram或安装依赖的步骤失败可以选择“Skip for now”跳过。核心的身份和记忆设置完成后智能体已经可以工作。你可以事后手动安装Bun (curl -fsSL https://bun.sh/install | bash)然后重新运行/setup或手动编辑config/agent.env来配置Telegram。确保你对UnClaw的目录有完整的读写权限。问题2技能/命令不显示或无法使用。可能原因Claude Code没有正确扫描到.claude/skills/目录。解决方案确认技能文件路径正确必须是.claude/skills/skill-name/SKILL.md。重启Claude Code会话。Claude Code通常在启动时加载技能新建技能文件后可能需要重启才能识别。检查CLAUDE.md文件确保没有语法错误导致Claude Code提前终止解析。问题3记忆搜索 (/search-memory) 返回空或错误。可能原因SQLite索引没有建立或索引文件损坏。解决方案运行python .claude/scripts/index_memory.py --rebuild来重建全文搜索索引。这个脚本通常在/setup时已配置好。检查daily-logs/目录下是否有.md日志文件。如果没有可能是钩子没有正确运行。检查.claude/settings.json中的hooks配置。确认identity/memory.md文件内容没有超过2500个Token大约1500-2000单词。过长会导致加载问题。5.2 性能与使用优化技巧1优化identity/memory.md的热记忆内容热记忆是性能的关键。不要把它当成垃圾堆。我遵循一个“三明治”结构来组织我的memory.md# Atlas - 热记忆 (最后更新: 2023-10-27) ## 当前核心焦点 (Active Focus) 1. **项目「Phoenix」迁移**正在将用户认证模块从Django REST迁移至GoEnt。重点数据迁移脚本的幂等性。 2. **本周学习目标**深入理解OpenTelemetry在微服务中的实践。 ## 用户近期偏好与习惯 (User Context) - 代码审查时优先关注错误处理和日志记录是否完备。 - 讨厌冗长的会议喜欢异步、书面形式的决策记录。 - 最近常用工具链Go 1.21, PostgreSQL 15, Docker Compose for local dev。 ## 关键待办与提醒 (Immediate To-Dos) - [ ] 明天上午10点前复查PR #342的数据库索引变更。 - [ ] 下午3点前为「Phoenix」项目编写部署检查清单。保持精简、结构化并定期我每周日晚上清理过时或已完成的项目。技巧2善用子代理Subagents处理复杂任务UnClaw运行在Claude Code内因此天然支持子代理功能。当你的主智能体遇到一个非常专业或耗时的子任务时可以主动创建子代理。例如当我的atlas-dev需要分析一个复杂的性能Profiling报告时我会指示它“请创建一个专注于性能分析的子代理将profiling_results.json交给它并要求它给出优化热点的摘要报告。” Claude Code会开辟一个新的会话窗格来处理这个任务完成后将结果返回给主智能体。这相当于在你的智能体内部组建了一个临时专家小组。技巧3将常用工作流固化为复合技能单一的技能有时不够。你可以通过编写更复杂的技能文件将多个步骤串联起来。例如我创建了一个/weekly-review技能它内部会依次调用搜索过去一周daily-logs中关于“错误”、“问题”的关键词。从memory/中提取所有项目的当前状态。结合我的日历生成一份包含“本周成就”、“遇到的问题”、“下周重点”和“风险提示”的周报草案。 这本质上是一个由智能体执行的自动化脚本极大地提升了复盘效率。5.3 安全与隐私考量重要提醒UnClaw的智能体基于Claude Code而Claude Code拥有你授予它的文件系统访问权限。规则是第一道防线务必精心编写.claude/rules/security.md。明确列出禁止目录如~/.ssh/,~/Documents/Financial/和限制操作如禁止运行sudo禁止访问特定网络地址。隔离是关键这就是为什么多智能体模式更安全。你的“财务分析”智能体根本不应该有访问你“开发项目”目录的路径。通过目录隔离来最小化权限。敏感信息处理避免在对话中直接输入密码、API密钥等。对于需要使用的密钥可以考虑通过环境变量传入或在config/agent.env中配置确保该文件在.gitignore中然后在规则中禁止智能体读取该文件内容。定期审计日志养成查看daily-logs/的习惯。这不仅是回顾工作也是安全检查可以确认智能体的行为是否符合预期。UnClaw代表了一种极简而强大的AI智能体构建思路。它剥离了所有不必要的复杂性让你能够直接基于一个成熟、稳定且已付费的运行时Claude Code快速打造一个完全个性化、零边际成本的数字助手。从简单的任务执行到深度的项目协作它正在成为我日常工作流中不可或缺的一部分。如果你也在使用Claude Max我强烈建议你花上半小时尝试一下UnClaw它可能会彻底改变你与AI协作的方式。