1. 一个“主权代理人”到底在说什么

第一次看到“主权代理人”这个说法，我脑子里冒出来的不是技术架构，而是一个很朴素的疑问：我们天天在用的那些AI助手，到底是谁的助手？是“我的”，还是“平台的”？这个问题听起来有点哲学，但落到工程实践上，它其实非常具体——你的对话记录存在哪、你的工作流能不能被平台随时掐断、你换一个模型供应商时积累的上下文资产能不能带走。

OpenClaw 创始人 Steinberger 提出的这套核心方法论，我理解下来，本质上是在回答一个问题：当AI从“工具”变成“代理”之后，控制权应该归谁。他给出的答案是“主权”——代理的主权属于使用者，而不是托管平台。这个立场在当下这个时间点特别值得聊，因为绝大多数人用AI的方式，还是把一切交给某个云端服务，你输入什么、它记住什么、它怎么调用外部能力，全在别人的服务器上跑。

这套方法论适合谁来参考？我的判断是三类人：一是正在做AI应用、需要设计代理架构的开发者；二是对数据主权、工作流可迁移性有要求的技术团队；三是单纯想搞明白“为什么我不该把所有东西都塞进一个聊天框”的普通用户。它不是一个具体的代码库教程，而是一套设计哲学，落到实操上会直接影响你怎么选型、怎么存数据、怎么设计调用链。

我先把结论摆前面：主权代理人的核心不是“更强的模型”，而是“更可控的边界”。模型强弱是租来的，边界设计才是你自己的资产。下面我按这套方法论的几个关键层面拆开讲，穿插我自己在类似架构上踩过的坑。

2. 核心思路拆解：为什么“主权”比“能力”更值得先想清楚

2.1 从“调用API”到“拥有代理”的思维转变

大部分人接触AI的路径是这样的：注册一个账号，打开对话框，输入问题，拿到回答。这个路径里，你拥有的是“访问权”，不是“所有权”。你的提示词、你的历史记录、你调教出来的那套上下文，全都寄生在别人的系统里。哪天服务改版、涨价、下线，你积累的东西一夜归零。

Steinberger 的方法论把这个顺序倒过来了：先想清楚“这个代理归谁管”，再想“它要具备什么能力”。这个顺序的差别很大。前者是以控制权为中心设计，后者是以功能为中心设计。功能为中心的思路下，你会不断往一个平台里堆需求，最后被平台绑架；控制权为中心的思路下，你会优先保证核心资产（数据、逻辑、接口）在自己手里，模型只是可替换的执行单元。

我举个生活化的类比。功能为中心就像你租房子，房东给你配什么家具你就用什么，住得再舒服，房子不是你的，房东要卖房你只能搬。控制权为中心就像你自己买房，装修可以请人做，家具可以随时换，但房子的产权在你手上。主权代理人要的就是后者——模型可以换，代理的“人格”和“记忆”得是你的。

这个转变落到工程上，最直接的影响就是：你会开始关心数据存在哪、格式是什么、能不能导出、换一个模型后上下文怎么迁移。这些问题在“纯调用API”的思路里根本不会出现，因为那时候你默认一切都在云端。

2.2 主权代理人的三个支柱：数据、逻辑、接口

我把这套方法论拆成三个可操作的支柱，这样聊起来不至于太虚。

第一个支柱是数据主权。你的对话历史、知识库、偏好设置，这些是代理的“记忆”。主权设计要求这些数据以开放格式存在你能控制的地方，而不是锁死在某个服务的数据库里。实操上，这意味着你要么本地存，要么存在自己可控的对象存储里，格式优先选纯文本或标准结构化格式（比如 JSON、Markdown），别用平台私有的二进制格式。

第二个支柱是逻辑主权。代理的行为逻辑——什么情况下调用什么工具、怎么组织上下文、怎么处理错误——这些应该由你定义，而不是被平台的“工作流编排器”框死。很多低代码平台看起来很美好，拖拖拽拽就能搭一个代理，但你的逻辑被表达成了平台的配置文件，换平台就得重做。主权设计倾向于用代码或至少是开放标准的配置来描述逻辑。

第三个支柱是接口主权。代理要调用外部能力（搜索、计算、文件操作等），这些接口的凭证和调用方式应该由你掌握。这一点最容易被忽视，因为很多人图省事，直接用平台内置的工具市场。方便是方便，但你的代理能力上限就被平台的市场决定了。

这三个支柱里，我觉得数据主权是最容易被低估的。大家聊AI架构时都在聊模型、聊提示词工程，很少有人认真聊“你的数据放哪”。但恰恰是数据，决定了你换供应商时的迁移成本。我自己踩过的坑就是早期把一堆对话记录存在某个服务的导出功能里，结果那个导出格式是它私有的，想迁移到另一个系统时解析了半天。

2.3 为什么现在提“主权”不是杞人忧天

有人可能会说，我一个普通用户，聊什么主权，能用就行。这个想法在“AI只是玩具”的阶段没问题，但当AI开始深度介入你的工作流——帮你写代码、管理日程、处理邮件、做决策辅助——它就不再是玩具了，它是你数字生活的基础设施。基础设施的控制权问题，迟早要面对。

从行业趋势看，模型能力正在快速商品化。今天最强的模型，半年后可能就被追平甚至超越。这意味着模型本身不再是护城河，围绕模型构建的代理体系才是。而代理体系的价值，很大程度上取决于它的可迁移性和可控性。一个绑死在某个平台上的代理，价值会随着平台政策波动；一个主权设计的代理，可以在模型迭代中持续增值。

Steinberger 提这套方法论，我理解不是要大家都去自建基础设施，而是提醒一个优先级：在追求能力之前，先把控制权的边界划清楚。这个提醒在当下这个“什么都要接AI”的热潮里，显得特别清醒。

3. 核心细节解析：主权代理人怎么落地

3.1 数据层的设计：让记忆真正属于你

数据层是主权代理人的地基。我建议的实操方案是：对话历史和知识库用纯文本或 Markdown 存储，元数据用 JSON，索引可以用轻量级数据库。为什么这么选？因为纯文本和 Markdown 是“人类可读、机器可解析”的格式，十年后你换个系统，这些文件照样能打开。JSON 是事实上的数据交换标准，几乎所有语言都有原生支持。

具体到目录结构，我习惯这样组织：

agent-data/ conversations/ 2024-01-15-session-001.md 2024-01-15-session-002.md knowledge/ notes/ references/ config/ preferences.json tools.json

每个对话文件用 Markdown 存，头部用 YAML front matter 记录元数据（时间、模型、标签）。这样你既可以用编辑器直接看，也可以写脚本批量处理。我实测下来，这种结构在迁移时几乎零成本——换个系统，把目录拷过去，写个解析脚本就行。

注意：不要用平台私有的“导出”功能作为唯一备份。很多平台的导出格式是阉割过的，丢失了上下文关联信息。主权设计要求你从第一天就用开放格式存。

这里有个细节值得展开：上下文窗口的管理。主权代理人不是把所有历史都塞进提示词，而是要有选择地检索。我通常会把对话按主题切分，每个主题维护一个摘要文件，检索时先匹配摘要再拉取原文。这样既控制了 token 消耗，又保证了记忆的连续性。这个逻辑应该由你自己的代码控制，而不是依赖平台的“记忆功能”——因为平台的记忆功能怎么实现、存哪、能不能导出，你都不知道。

3.2 逻辑层的设计：把行为规则握在自己手里

逻辑层是代理的“大脑”，决定它怎么思考、怎么行动。主权设计在这里的核心原则是：行为逻辑用代码或开放配置表达，不用平台私有编排器。

我见过太多团队用低代码平台搭代理，拖拽几下就上线，看起来很高效。但问题是，这些逻辑被表达成了平台的配置文件，你想加一个自定义的判断分支，平台不支持；你想把逻辑迁移到另一个平台，格式不兼容。最后要么被平台绑架，要么推倒重来。

我的做法是用一个轻量的编排层，通常就是一个 Python 或 TypeScript 写的调度器。它负责几件事：接收输入、决定调用哪个模型、组装上下文、调用工具、处理输出。这个调度器的逻辑是纯代码，可以版本控制、可以测试、可以迁移。

一个简化的调度逻辑大概长这样：

def handle_input(user_input, context): intent = classify_intent(user_input) if intent == "question": context = retrieve_relevant(context, user_input) response = call_model(user_input, context) elif intent == "action": tool = select_tool(user_input) response = tool.execute(user_input) return response

这段代码本身不复杂，但它的意义在于：逻辑是你的，不是平台的。你想换模型，改call_model的实现就行；你想加工具，改select_tool的逻辑就行。整个代理的行为边界清晰可控。

提示：编排层不要过度设计。我见过有人一上来就搞复杂的状态机、多代理协作，结果调试成本极高。先从单代理、线性流程开始，跑通了再扩展。

3.3 接口层的设计：工具调用的主权

接口层是代理和外部世界交互的通道。主权设计在这里的要求是：工具的定义、凭证、调用方式都由你掌握。

具体来说，我会把每个工具封装成一个独立的模块，模块里包含工具的描述（给模型看的）、参数 schema、执行逻辑、错误处理。凭证存在环境变量或本地密钥管理里，不进代码库。这样做的原因是，工具是代理能力的延伸，如果工具被平台托管，你的代理能力上限就被平台决定了。

举个例子，一个“搜索”工具，我不建议直接用平台内置的搜索，而是自己封装一个。封装层可以做几件事：控制搜索源、过滤结果、缓存、限流。这些控制权在你手里，代理的行为才可预期。

工具描述这块有个经验：描述要写给模型看，不是写给人看。很多人写工具描述时用人类习惯的语言，结果模型理解偏差。好的工具描述应该明确说明：这个工具做什么、什么时候用、参数是什么格式、返回什么。我通常会用类似这样的结构：

{ "name": "search_notes", "description": "在本地笔记库中搜索相关内容。当用户询问过去记录过的信息时使用。", "parameters": { "query": "搜索关键词，字符串", "limit": "返回条数，整数，默认5" } }

这种结构化的描述，模型解析起来准确率高很多。我实测下来，同样的模型，工具描述规范化之后，调用准确率能提升不少。

3.4 模型层的设计：把模型当可替换零件

模型层是主权方法论里最反直觉的部分。大家习惯把模型当成核心，但主权设计里，模型是可替换的执行单元。

这个思路的实操含义是：你的代理不应该依赖某个模型的独有特性。比如某个模型有特殊的函数调用格式，你就围绕这个格式设计整个系统，那换模型时就痛苦了。主权设计倾向于用模型无关的抽象层，把模型调用统一成一个接口，不同模型用适配器接入。

我通常会在配置里维护一个模型列表，每个模型标注能力标签（比如“擅长推理”“擅长代码”“便宜快速”），调度时根据任务类型选择。这样模型迭代时，你只需要更新适配器，代理逻辑不动。

注意：不要为了“用最新模型”而频繁切换。模型切换有成本，提示词可能要调整，行为可能有变化。主权设计给你切换的自由，但不意味着你要频繁切换。稳定优先。

4. 实操过程：从零搭一个主权代理的骨架

4.1 环境准备与目录初始化

我按自己的习惯走一遍流程。首先建目录结构，这是数据主权的基础：

mkdir -p agent/{data/{conversations,knowledge},src/{core,tools,adapters},config} cd agent

然后初始化配置。config/preferences.json存用户偏好，config/models.json存模型列表，config/tools.json存工具注册信息。这些文件都是纯 JSON，可读可改可迁移。

环境变量用.env文件管理，存 API 密钥之类的敏感信息。记得把.env加进.gitignore，别把密钥提交到版本库。这个坑我见过太多次了，有人图省事把密钥写死在代码里，结果仓库一公开就泄露。

4.2 核心调度器的实现

调度器是整个代理的心脏。我用 Python 写一个最小可用版本，核心就三个函数：意图识别、上下文组装、模型调用。

意图识别我倾向于先用规则，跑通了再考虑用模型。规则简单直接，调试成本低。比如关键词匹配、正则表达式，覆盖80%的常见场景足够了。等规则搞不定了，再引入模型做分类。

上下文组装是主权设计的关键环节。我的做法是：从对话历史里检索相关片段，加上知识库里的相关内容，组装成一个结构化的上下文。这个上下文不是简单拼接，而是有层次的——最近的对话在前，相关知识在后，用分隔符隔开。

模型调用用适配器模式。每个模型一个适配器类，实现统一的generate(prompt, context)接口。这样换模型时，调度器代码不动，只换适配器。

class ModelAdapter: def generate(self, prompt, context): raise NotImplementedError class SomeModelAdapter(ModelAdapter): def generate(self, prompt, context): # 具体调用逻辑 pass

这个抽象层的价值在迁移时体现得最明显。我试过把一个代理从模型A迁到模型B，只改了适配器，调度逻辑一行没动，半天搞定。

4.3 工具模块的封装与注册

工具模块我按“一个工具一个文件”的原则组织。每个文件里定义工具的元数据和执行函数。注册时扫描目录，自动加载。

一个工具文件的模板大概是这样：

TOOL_META = { "name": "read_file", "description": "读取本地文件内容", "parameters": {"path": "文件路径，字符串"} } def execute(path): with open(path, 'r') as f: return f.read()

注册器扫描tools/目录，收集所有TOOL_META，生成给模型看的工具列表。执行时根据工具名路由到对应的execute函数。

这个设计的妙处在于扩展成本极低。想加工具，新建一个文件，写好元数据和执行逻辑，重启就生效。不需要改任何核心代码。我实测下来，加一个简单工具从写到能用，十分钟以内。

4.4 数据持久化与迁移测试

数据持久化我坚持用文件系统，不用数据库。原因是文件系统最透明，迁移最方便。对话存 Markdown，元数据存 JSON，知识库存纯文本。这些格式十年后照样能读。

迁移测试是主权设计里必须做的一步。我的做法是：定期把整个data/目录拷到另一台机器，用同样的代码跑一遍，看能不能正常读取。这个测试能暴露很多隐藏的依赖问题。我踩过的坑是早期用了某个库的私有序列化格式，迁移时发现另一台机器上库版本不同，读不出来。后来全部改成纯文本，问题消失。

提示：迁移测试不要等到真要迁移时才做。定期做，当成健康检查。发现问题早，修复成本低。

5. 常见问题与排查技巧实录

5.1 上下文丢失与记忆断裂

这是主权代理最常见的坑。表现是：代理突然“忘了”之前聊过的内容，或者把不相关的历史拉进来干扰回答。

排查思路分三步。第一步，检查检索逻辑。是不是检索关键词匹配错了，导致拉取了不相关的片段。第二步，检查上下文组装。是不是 token 超限被截断了，重要的内容被切掉。第三步，检查存储格式。是不是某个对话文件格式损坏，解析失败被跳过了。

我的经验是，上下文问题八成出在检索环节。检索太宽，拉一堆无关内容；检索太窄，该拉的没拉到。调检索参数时，我通常先看召回率，再看准确率。宁可多召回一点，再在组装环节过滤，也别漏掉关键信息。

5.2 工具调用失败与参数错误

工具调用失败通常有两类原因：模型生成的参数格式不对，或者工具执行本身出错。

参数格式问题，根源往往在工具描述。描述不清晰，模型就猜，猜错就失败。我的做法是把参数 schema 写得极其明确，类型、格式、示例都给全。实测下来，描述规范化之后，参数错误率大幅下降。

工具执行出错，要做好错误处理。我的原则是：工具执行失败不能让整个代理崩溃。捕获异常，返回一个结构化的错误信息给模型，让模型决定怎么处理。比如搜索失败，模型可以告诉用户“搜索暂时不可用”，而不是整个对话卡死。

5.3 模型切换后的行为漂移

换模型后代理行为变化，这个坑很隐蔽。同样的提示词，模型A和模型B的输出风格、工具调用习惯可能完全不同。

排查方法是做回归测试。准备一组标准输入，记录模型A的输出，换模型B后跑同样的输入，对比差异。差异大的地方，就是需要调整提示词或逻辑的地方。

我的经验是，切换模型时预留一周的观察期。别指望无缝切换，行为漂移是常态。观察期内密切监控，发现问题及时调整。

5.4 常见问题速查表

这张表是我自己踩坑总结的，基本覆盖了主权代理落地时的高频问题。遇到问题先查表，能省不少时间。

5.5 几个容易被忽视的避坑技巧

第一个技巧：给代理加“自检”能力。定期让代理自己检查数据完整性、工具可用性、模型连通性。发现问题主动报告，而不是等用户遇到才暴露。

第二个技巧：日志要结构化。别用print打日志，用结构化日志（JSON 格式），记录时间、事件类型、关键参数。排查问题时，结构化日志能快速过滤和聚合。

第三个技巧：版本控制要覆盖配置。很多人只对代码做版本控制，配置和提示词不管。结果改了个提示词，效果变差，想回滚发现没记录。我的做法是配置和提示词也进版本库，每次改动都有记录。

第四个技巧：定期做“断网测试”。把外部依赖断掉，看代理能不能优雅降级。主权设计的一个隐含要求是：外部服务不可用时，代理的核心功能还能用。这个测试能暴露很多隐藏的强依赖。

6. 我对这套方法论的真实体会

聊了这么多架构和实操，最后说点个人的真实感受。我最早接触“主权”这个概念时，觉得有点小题大做——不就是用个AI吗，至于上升到主权吗。但用得越久，越觉得这个提醒有价值。

我自己的代理体系跑了两年多，中间换过三次模型，迁移过两次存储方案。每次迁移，我都庆幸当初把数据存成了开放格式、把逻辑写成了代码。如果当初图省事用了某个平台的全家桶，这几次迁移的成本会高得多，甚至可能迁不动。

Steinberger 这套方法论最打动我的地方，是它把“控制权”放在了“能力”前面。这个优先级在当下这个模型能力日新月异的时代，显得特别反直觉，但也特别清醒。模型会一直变强，但你的数据、你的逻辑、你的工作流，这些才是真正属于你的资产。把资产握在手里，模型随便换，这才是主权代理人的底气。

如果你正准备搭自己的AI代理，我的建议是：先花半天时间想清楚数据存哪、逻辑怎么写、工具怎么管，再动手写第一行代码。这半天能省你后面无数个小时的迁移和重构。能力可以慢慢加，主权一旦丢了，找回来就难了。