无头模式

非交互式运行 Letta Code，用于脚本和自动化

无头模式允许您非交互式运行 Letta Code，使其易于集成到脚本、CI/CD 管道或与其他 UNIX 工具组合使用。

基本用法

使用 -p 标志直接传递提示：

letta -p "Look around this repo and write a README.md documenting it"

您也可以通过管道输入 Letta Code：

echo "Explain this error" | letta -p

输出格式

Letta Code 在无头模式下支持三种输出格式：

文本（默认）

以纯文本返回代理的响应：

letta -p "What files are in this directory?"

JSON

返回带有元数据的结构化 JSON 响应：

letta -p "List all TypeScript files" --output-format json

示例输出：

{
  "type": "result",
  "result": "Found 15 TypeScript files...",
  "agent_id": "agent-abc123",
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 89
  }
}

流式 JSON

返回行分隔的 JSON 事件以进行实时流式传输。这对于防止超时和获取增量进度很有用：

letta -p "Explain this codebase" --output-format stream-json

每行是一个 JSON 事件：

{"type":"system","subtype":"init","agent_id":"agent-...","session_id":"agent-...","model":"claude-sonnet-4-5","tools":[...]}
{"type":"message","message_type":"reasoning_message","reasoning":"The user is asking...","otid":"...","seq_id":1}
{"type":"message","message_type":"assistant_message","content":"Here's an overview...","otid":"...","seq_id":5}
{"type":"message","message_type":"stop_reason","stop_reason":"end_turn"}
{"type":"message","message_type":"usage_statistics","prompt_tokens":294,"completion_tokens":97}
{"type":"result","subtype":"success","result":"Here's an overview...","agent_id":"...","session_id":"...","uuid":"..."}

消息在 token 级别流式传输——每个块具有相同的 otid（输出轮次 ID）和递增的 seq_id。

双向模式

对于程序化控制，使用 --input-format stream-json 启用通过 stdin/stdout 的双向 JSON 通信。这允许外部程序以结构化格式发送消息和接收响应。

letta -p --input-format stream-json --output-format stream-json

输入消息类型

向 stdin 发送 JSON 消息（每行一个）：

用户消息：

{"type":"user","message": {"role":"user","content":"What files are here?"}}

初始化控制请求：

{"type":"control_request","request_id":"init_1","request": {"subtype":"initialize"}}

中断控制请求：

{"type":"control_request","request_id":"int_1","request": {"subtype":"interrupt"}}

输出消息类型

CLI 向 stdout 发出 JSON 消息：

初始化事件（会话开始时发出）：

{"type":"system","subtype":"init","agent_id":"agent-xxx","session_id":"agent-xxx","model":"...","tools": [...]}

控制响应：

{"type":"control_response","response": {"subtype":"success","request_id":"init_1","response": {...}}}

流式消息：

{"type":"message","message_type":"assistant_message","content":"Hello!","session_id":"...","uuid":"..."}

结果（每轮后发出）：

{"type":"result","subtype":"success","result":"Hello!","session_id":"...","agent_id":"..."}

多轮对话

进程保持活动直到 stdin 关闭，允许多轮对话：

(
  echo '{"type": "user", "message": {"role": "user", "content": "Remember: secret is BANANA"}}'
  sleep 5
  echo '{"type": "user", "message": {"role": "user", "content": "What was the secret?"}}'
) | letta -p --input-format stream-json --output-format stream-json

Token 级流式传输

添加 --include-partial-messages 以接收 token 级流式事件：

letta -p --input-format stream-json --output-format stream-json --include-partial-messages

这会将每个块包装在 stream_event 中：

{"type":"stream_event","event": {"message_type":"assistant_message","content":"Hel"},"session_id":"...","uuid":"..."}

代理选择

默认情况下，无头模式使用当前目录的上次代理并创建新对话（就像交互模式一样）。您的代理在运行之间保持记忆，但每次运行都以新的消息历史开始。

创建新代理：

letta -p "..." --new

使用特定代理：

letta -p "..." --agent <agent-id>

模型选择

为无头运行指定模型：

letta -p "..." --model sonnet-4.5
letta -p "..." -m gpt-5-codex
letta -p "..." -m haiku

有关支持的模型 ID 完整列表，请参阅模型。

权限控制

自动允许所有工具

使用 --yolo 绕过所有权限提示（谨慎使用）：

letta -p "Refactor this file" --yolo

限制可用工具

--tools 标志控制将哪些工具附加到代理（将它们从上下文窗口中完全移除）：

letta -p "Analyze this codebase" --tools "Read,Glob,Grep"

无工具（仅对话）：

letta -p "What do you think about this approach?" --tools ""

这与 --allowedTools/--disallowedTools 不同，后者控制权限但保留上下文中的工具。有关更多详细信息，请参阅权限。

权限模式

自动允许仅编辑：

letta -p "Fix the type errors" --permission-mode acceptEdits

只读模式：

letta -p "Review this PR" --permission-mode plan

高级选项

按名称恢复

使用 -n 或 --name 按名称恢复代理（不区分大小写）。匹配固定代理或最近代理：

letta -p "Continue where we left off" --name myproject

系统提示配置

创建新代理时自定义代理的系统提示：

使用预设：

letta -p "..." --new --system letta-claude

使用自定义提示：

letta -p "..." --new --system-custom "You are a Python expert who writes clean code."

使用附加指令扩展预设：

letta -p "..." --new --system letta-claude --system-append "Always respond in Spanish."

可用预设：

default/letta-claude - 完整 Letta Code 提示（Claude 优化）
letta-codex - 完整 Letta Code 提示（Codex 优化）
letta-gemini - 完整 Letta Code 提示（Gemini 优化）
claude - 基础 Claude（无技能/记忆指令）
codex - 基础 Codex
gemini - 基础 Gemini

记忆块配置

自定义代理使用哪些记忆块：

指定要包含的预设块：

letta -p "..." --new --init-blocks "persona,project"

设置预设块的值：

letta -p "..." --new --init-blocks "persona,project" \
  --block-value persona="You are a Go expert" \
  --block-value project="CLI tool for Docker"

使用完全自定义的记忆块（JSON）：

letta -p "..." --new --memory-blocks '[
  {"label": "context", "value": "API documentation for Acme Corp..."},
  {"label": "rules", "value": "Always use TypeScript"}
]'

无可选块（仅核心技能块）：

letta -p "..." --new --init-blocks ""

可用预设块：

persona - 代理的个性和行为
human - 关于用户的信息
project - 当前项目上下文

核心块（始终包含）：

skills - 可用技能目录
loaded_skills - 当前加载的技能指令

工具集覆盖

强制使用特定工具集而不是基于模型的自动检测：

letta -p "..." --toolset codex    # Codex 风格工具
letta -p "..." --toolset gemini   # Gemini 风格工具
letta -p "..." --toolset default  # 默认 Letta 工具

示例

自动化任务

运行 lint 并修复错误：

letta -p "Run the linter and fix any errors" --yolo

用于脚本的结构化输出

使用 JSON 输出以编程方式解析结果：

result=$(letta -p "What is the main entry point of this project?" --output-format json)
echo $result | jq '.result'

只读分析

使用 --tools 将代理限制为只读操作：

letta -p "Review this codebase for potential security issues" --tools "Read,Glob,Grep"

使用 cron 的计划任务

使用 cron 按计划运行 Letta Code：

每天早上 9 点进行代码审查：

0 9 * * * cd /path/to/project && letta -p "Review recent changes and summarize any issues" --tools "Read,Glob,Grep" --output-format json >> /var/log/letta-review.log 2>&1

每周依赖检查：

0 10 * * 1 cd /path/to/project && letta -p "Check for outdated dependencies and security vulnerabilities" --yolo >> /var/log/letta-deps.log 2>&1