4.2 CLI 命令台：letta run 与 letta server
4.2 CLI 命令台：letta run 与 letta server
本节摘要：命令行是与 Letta 交互的最短路径：
letta server起服务，letta run直通对话。本节讲清两条核心命令的行为逻辑、适合它们的场景，以及 CLI 在脚本化与远程运维中不可替代的位置。读完本节，你能用纯键盘完成一次"启动、对话、检查"的完整循环，并判断哪些日常操作值得交给命令行。
图形界面时代的命令行价值
有了 ADE 的可视化面板，为什么还要学命令行？因为两者的强项天然错开。图形界面擅长看：全局状态、历史轨迹、批量信息，一眼即得。命令行擅长跑：进脚本、进定时任务、进远程终端，一条命令搞定。真实工作流里两者互补——白天在 ADE 里调记忆，深夜让脚本通过命令行跑回归；本机用 ADE 观测，远程服务器上只有一条 SSH 连接时，命令行就是唯一的观测手段。
还有一层价值属于可重复性。图形界面上的点击无法留痕，命令行天然是文本：写进文档就是操作手册，写进脚本就是自动化。本册第 5 章的实验要求"可复现"——同一个实验任何人任何时候重跑结果一致——能落进命令行的操作才好纳入这个标准。
对新手的最后一条实用忠告：CLI 的学习曲线不该在功能全量上，而在高频三招上——起服务（server）、对话验证（run）、状态抽查（配合接口调用工具或 SDK 单行脚本）。三招练到条件反射，其余命令用到时查手册即可。工具学习的性价比从来不来自"全会"，而来自"常用的足够顺"。
letta server：一次启动的内部旅程
letta server 在第 3 章已经用过，本节把它拆开看清。执行这条命令后，框架依次完成四件事：读取环境变量确定配置（密钥、连接串、访问密码）；按配置连接存储并确认表结构就绪；初始化智能体运行时；监听端口对外提供服务。四件事的次序决定了排查思路——服务起不来时，日志里最先报错的环节就是病灶所在：
这张流程图建议与 3.3 节的三板斧连起来用：启动失败先看死在哪一步——配置缺失死在第二关，数据库连不上死在第四关，端口冲突死在最后一关。把启动流程背下来，"服务起不来"就从一个笼统的故障变成了一个可定位的分支选择。
letta run：对话现场的最小闭环
letta run 是面向人的交互入口：它连上服务端，列出你的智能体，选中一个即可开始对话。退出重进，它记得上次聊到哪——因为状态在服务端，CLI 只是又一只接入的客户端（2.4 节的"协议对等"在此兑现）。一个典型的会话长这样：
# 启动交互式对话（确保服务已在别处运行） letta run # 交互过程示意： # ? 选择一个智能体: project_buddy # > 把今天例会的结论记一下：下周一发布灰度 # [智能体内心独白] 用户披露了新安排，应更新核心记忆 # [工具调用] core_memory_append human 块 # [工具返回] 更新成功 # 好的，已记录：下周一发布灰度。
注意这段会话里最有教学价值的部分：CLI 把本该隐藏的内心独白与工具调用直接打印在对话流里。你实时看到模型"想了什么、做了什么"——这其实就是 4.1 节四区轨迹的命令行版。快速验证记忆策略的改动时，这种"对话与轨迹同屏"的形态比切换到图形界面更快。
letta run 还有一个容易被忽略的使用姿势：把它当作记忆行为的"回放器"。改完 persona 策略后，把同一组测试消息按同样顺序重发一遍，观察独白与工具调用是否按新策略变化——同屏形态让前后对比一目了然。第 5 章的多项实验都依赖这种"固定输入看行为变化"的手法，CLI 是它最低成本的实施工具。
至于 letta server 与 letta run 的搭配关系，一句话说清：server 是常驻的舞台，run 是登台的演员之一。你可以在一个终端起 server，在另外几个终端各开一个 run——它们连的是同一个服务端、同一份状态，就像几个人同时走进同一间办公室。理解了这个关系，你就不会再问"要不要在每个终端都起服务"这类问题：服务永远只有一份，客户端随便几份。
值得交给命令行的三类操作
按"可重复性"与"无人值守"两条标准筛，三类操作最值得 CLI 化。第一类：批量检查。 比如巡检所有智能体的记忆块水位、列出长期未活动的智能体——写成脚本定时跑，输出即报告。第二类：冒烟验证。 第 3 章那条"发验证请求"的仪式，完全可以落成一个脚本，环境变更后一键确认实验台健康。第三类：远程运维。 服务器上没有浏览器时，CLI 与 curl 式的 API 调用是仅有的观测手段。
💡 一个务实的建议：把你在 ADE 里重复做过三次以上的操作固化成脚本。界面适合探索，脚本适合重复——按这个阈值执行，一个月后你会攒出一套贴身的运维小工具，而它们全部由本章的命令行能力支撑。
一个最小巡检脚本的样子
把"CLI 化三类操作"落到纸面，看一个最小巡检脚本长什么样（思路示意，具体命令随版本演进以官方手册为准）：
#!/usr/bin/env bash # 实验台每日巡检：健康、水位、活动三项 set -e # 1. 健康检查：服务是否在监听 curl -sf -o /dev/null http://localhost:8283/health || { echo "[告警] 服务未响应"; exit 1; } # 2. 智能体清单：数量是否符合预期 curl -sf http://localhost:8283/v1/agents/ | grep -o '"id"' | wc -l # 3. 磁盘水位：单文件存储的成长速度 du -sh ~/.letta/ 2>/dev/null || echo "使用 PostgreSQL，跳过"
这个脚本没有一行高深内容，价值全在"每天自动跑"。健康项告诉你服务死了没有，清单项让异常的智能体增减无处遁形，磁盘项提醒你存储成长是否偏离预期——三个数字看一眼，实验台的体检就完成了。巡检的意义不在发现大事故（大事故自己会跳出来），而在捕捉缓慢的漂移：磁盘周增长翻倍、智能体数量莫名多出，这类"温水"问题只有例行巡检抓得住。
关于 CLI 的常见疑问
问：CLI 命令与 SDK 调用是什么关系？ 同一协议的两种封装。CLI 命令在内部走的也是 REST API，你能用 curl 完成的一切，CLI 都能做；反之亦然。选择只看使用场景：人敲的用 CLI，代码调的用 SDK。
问：远程服务器上怎么安全地用 CLI？ 与 3.3 节的凭据纪律一致：访问密码经环境变量携带，不经命令行参数明文传递（参数会进 shell 历史）；SSH 通道本身提供传输加密；用完的会话及时退出。
问：CLI 输出能转成结构化数据吗？ 输出本身就是文本，配合 jq 之类的工具可以裁成任意形状；需要复杂处理时，直接换 SDK 更省力——别和命令行较劲，它是给人看的，不是给程序解析的。
本节要点回顾
- 分工逻辑：界面强在看全局，命令行强在跑操作；可重复性与无人值守是 CLI 的专属领地。
- 启动四步：读配置、连存储、起运行时、监听端口，启动失败的死点即病灶。
- run 的看点：交互会话中同屏打印内心独白与工具调用，是记忆策略改动后的快速验证场。
- CLI 化三类：批量检查、冒烟验证、远程运维，凡重复三次的操作都值得落成脚本。
- 协议对等的兑现：CLI 与图形界面、SDK 是同一服务端的对等客户端，状态只有服务端那一份。
下一节看编码侧的集成形态：当观测与操作要嵌进你自己的代码里，Letta Code 这类框架提供了什么不同的选择。