用 Talos 0.20.x 把自托管 Agent 的每次工具调用关进能力内核：源码安装、/policy 干跑、审批与审计回溯实操

把 Agent 接到自己的服务器、邮箱与终端之后，绕不开一个问题：它每次要跑命令、写文件、发消息时，谁说了算？Talos 是一个 MIT 许可的自托管 Agent，面向终端、Telegram 与树莓派，把每次工具调用都送进一个确定性的能力内核（capability kernel）判决，配上任务级审批与审计轨迹。本教程按官方仓库 README 与 Release 记录六步落地：审阅安装脚本、从源码装起并跑通本地会话、用 /policy 干跑看判决、走过审批闸门、用 events / why / report 回溯，最后演练迁移与签名升级。主线可接本地 Ollama 或已登录的 Agent CLI，不强制新增模型密钥。

🛡️ 适合谁：需要在自己机器上跑一个可被审计的 Agent 的平台、运维与安全工程师，以及想看清「允许 / 拒绝」究竟由哪段代码决定的人。前置准备：Python 3.11 或更新、Linux 或 macOS（含树莓派）、git、可新建的虚拟环境；模型连接三选一——自有 API Key、已安装并登录的 Claude / Hermes CLI，或本机 Ollama。Telegram 路线另需 bot token，但终端路线不需要；模型调用按你选的通道计费或计入订阅额度。请在一次性练习目录里安装，别直接接管生产主机。

先弄清：闸门在进程内，边界要自己看清

README 把内核拆成一堆刻意保持短小的模块：policy.py 负责目标推导与三种判决、capability.py 铸造与回收令牌、command_floor.py 识别危险命令、approval.py 与 standing.py 管一次性与常驻授权、executor.py / verifier.py / snapshot.py 做预写执行与撤销、web.py / broker.py 风格的出口负责 URL 守卫与解析笼。规划、定时与委派在 plan.py / schedule.py / subagent.py，并且按官方说法只会收紧某个运行，不会把它放宽。

你想问的问题	官方给的入口	本教程怎么验
这条命令会被放行吗	`/policy <path\|command>` 调用 `decide()` 只显示判决	干跑一次危险命令，确认没有实际执行
刚才那步为什么被允许	`python -m talos why <id>` 与 `events --tool`	按工具名过滤事件再查单条编号
能给外部人看一份记录吗	`report --out audit.txt` 与 `review`	导出审计文本并核对放行与拒绝两栏
能不能顺手迁移旧配置	`import list` 与 `--dry-run`	先预演，再按指纹确认应用

版本与平台口径要对齐：仓库 README 当前标注的已签名版本是 0.20.3（Release 页时间 11 月 11 日 16:43，内容为 Telegram 流式回复的修补），而 0.20.0 是维护者称为「冻结操作契约下的稳定起点」的那个版本，Roadmap 里记录了从 RC.3 到它的七天部署观察与资格检查。别把教程里的版本号写死成命令前提，安装后以 talos version 与 Release 页为准。README 明确要求 Python 3.11+ 且只支持 Linux / macOS；Apple Silicon 上另有 macOS 14+ 与 Homebrew 7+ 的单独安装说明；Windows 不在支持列表里。

Step 1：先读安装脚本，再决定用哪条路线

1 官方把「读它」写成了两条命令

仓库给出的官方安装器是「先 less 阅读、再 bash 执行」的成对写法，并说明安装器会校验签名与校验和、跑完整测试套件，然后停下来——在你明确同意之前，不会有任何进程开始监听。

# 阅读阶段：只看，不执行
curl -fsSL https://talos-agent.ch/install.sh | less

# 确认脚本内容后再执行
curl -fsSL https://talos-agent.ch/install.sh | bash

# 安装后自检：诊断环境与可用命令
talos doctor
talos help <command>

本教程主线选源码安装，理由是每一步都能看见、随时可以删掉虚拟环境回滚。官方同时提供 Telegram 路线：python -m talos setup 配 token、身份与模型，python -m talos 启动；README 提醒 token 会发往 getMe，身份来自你发给自己的 bot 的真实消息。

管道执行需要审慎：curl ... | bash 会把远端脚本直接交给本机执行，内容可能随仓库更新变化。团队机器请先过一遍安全要求。另外 talos 会持有模型凭据与通道凭据，官方说明每个 key 只属于一个 provider，不存在通用的 api_key 与统一 base url；切换到没有 key 的 provider 会被拒绝，原先的仍保持启用。请把凭据放进它由你控制的配置里，不要写进会提交的脚本。

Step 2：从源码装起，跑通终端里的本地会话

2 锁哈希依赖、设 PATH、开一轮对话

官方源码路线用 --require-hashes 装两份锁文件，再把仓库的 bin 目录加进 PATH。setup terminal 只配本地身份与模型，不需要 Telegram；随后 chat 起一个会话，审批直接在终端完成。

git clone https://github.com/talos-kernel/talos.git
cd talos
python3 -m venv .venv
. .venv/bin/activate
pip install --require-hashes -r requirements.lock -r requirements-dev.lock
export PATH="$PWD/bin:$PATH"

# 本地身份 + 模型，不接 Telegram
python -m talos setup terminal

# 开一轮会话；这一轮里可以直接体验审批
python -m talos chat

# 若要跑 Telegram 路线，换成下面两条
python -m talos setup
python -m talos

会话内可用的一批斜杠命令也值得先记下来：/stop、/stopall、/queue、/status、/new、/retry、/background，审批相关的 /pending、/approve、/deny、/allowed、/revoke，以及 /log、/undo、/policy、/autonomy、/tools、/usage 等。

💡 想少绕弯，先跑 talos doctor 再看会话：README 把 doctor、config、models 归为「配好它，并查清它为什么不工作」的一组命令。模型没接上时，先确认你选的 provider 是否真的有对应凭据，而不是反复改提示词。

Step 3：用 /policy 干跑，看判决但不执行

3 理解内核最快的入口

官方把 /policy <path|command> 定义成一次干跑：调用 decide() 并把判决显示出来，不执行任何东西。这是在改动配置之前看清边界的方式，也适合用来给同事讲清楚「为什么这条被拦」。

# 会话内：把想试的路径或命令交给 /policy，只看判决
/policy rm -rf /tmp/talos-probe
/policy ./notes/draft.md

# 会话内另一个诊断入口
/eval 这条命令会不会改文件

# 命令行侧：按名字查配置、改一个显示项做对照
python -m talos config list model
python -m talos config describe TALOS_STATUS_STYLE
python -m talos config set TALOS_STATUS_STYLE expressive
python -m talos models --refresh

把「判决」和「诊断」分开很重要。README 明确写 /eval <text> 是独立的本地诊断：本地分类器只给出一个可能的类别，并显式声明这不构成事实；它的结果从不被 decide() 采纳，也不能批准任何动作。看到 /eval 输出别当成放行依据。

配置写入也有边界：官方示例里 config set TALOS_MODEL_OVERRIDES 只接受上下文窗口或价格这类目录里没有的字段，明确不接受 provider、url 或 key；并且文档把它标注为「以你的话为准」。改配置前建议用 config describe 看说明，改完用 status 复核生效范围。

Step 4：走一遍审批闸门，确认拒绝真的拦住动作

4 待决、放行、拒绝、收回授权

审批分一次性与常驻两类，由 approval.py 与 standing.py 承担；执行侧用预写、核验与快照支持撤销。实操时不要把「问了」当成「批了」：让 Agent 提一个会改动练习目录的请求，然后分别走放行与拒绝两条分支。

# 会话内：列出待决请求，再逐条处理
/pending
/approve <id>
/deny <id>
/allowed
/revoke <id>

# 需要单轮、可脚本化的一问一答
python -m talos ask "列出当前练习目录里的文件，不要修改任何内容"

# 会话里还可查看用量、模型与当前工具清单
/usage
/model
/tools
/whoami

验收时请盯住两件事：被 /deny 的请求是否在文件系统中确实没有留下改动；/revoke 之后同类动作是否重新回到待决状态。README 把 /undo 与 /log 放在同一组，撤销能力依赖执行侧的快照与写入前记录，别把它理解成「任何外部副作用都能回滚」。

💡 让信任边界可观察：在练习目录里预置一个哨兵文件，跑完一轮审批后检查它的内容与时间戳。用文件系统事实核对判决，比看终端里一句「已拒绝」更可靠。

内核不等于强制隔离：README 在 Roadmap 里坦白，只要 Agent 与它的配置文件属于同一个可写用户，命令底线与沙箱就只是同一进程里的代码，并不构成真正的权限分离；加固安装的做法是让配置归 root、Agent 只读。实验性的可视化适配器另有独立资格要求，输入回执只证明派发成功，不证明访客系统里真的显示出了结果；规划的 macOS 方案限定为固定 x86_64 Debian 客户机、QEMU TCG，排除端口转发、桥接网络、宿主目录、剪贴板与宿主凭据，且尚未完成硬件资格验证。别把这些边界当成已交付能力。

Step 5：用事件、原因与报告做一次完整回溯

5 从「发生了什么」追到「为什么允许」

官方把 status、events、why <id> 归为一组，用来回答「它做了什么、为什么这被允许或拒绝」；report 与 review 则产出别人也能读的记录与「这套安装该改什么」。

# 最近做了什么
python -m talos status

# 按工具过滤事件，只读且可筛选
python -m talos events --tool run_shell

# 追单条事件：为什么被允许或拒绝（编号来自 events 输出）
python -m talos why 4831

# 导出可交付的记录；review 给出安装层面的改进建议
python -m talos report --out audit.txt
python -m talos review

一次完整回溯建议按「事件编号 → 判决原因 → 报告文本」三段走：先拿到工具调用的事件编号，再用 why 看当时的目标推导与授权状态，最后把 report 导出的文本交给不参与操作的人复核。审计报告里如果只有放行、没有拒绝，通常说明闸门根本没有被触发，应回到 Step 4 重跑。

💡 events 的输出可以直接作为回归基线：把同一组动作在改配置前后各跑一次，比较事件条数与判决分布，比逐条读日志更容易发现「审批被悄悄放宽」这类变化。

Step 6：迁移旧配置与签名升级，留好回滚路径

6 先预演、按指纹确认，升级前先过测试

README 给出 Hermes 与 OpenClaw 两套旧环境的导入预览，流程是「列出来源 → --dry-run 预演 → 带指纹 --apply --confirm」，并要求非活动式原子暂存与恢复归档。connections list 看隔离 worker 清单与默认禁用的无密钥连接草稿。

# 列出可预览的旧 Agent 家目录
python -m talos import list

# 两条来源都先预演，不落盘
python -m talos import hermes --source "$HOME/.hermes" --dry-run
python -m talos import openclaw --source "$HOME/.openclaw" --dry-run

# 预演无误后按官方给出的指纹确认应用
python -m talos import hermes --source "$HOME/.hermes" --apply --confirm <fingerprint>

# 查隔离 worker 与连接草稿
python -m talos connections list

# 签名校验、先跑测试的升级
talos update

# 从 Beta.7 或更早版本、且改过 pip 配置时，官方给的临时写法
PIP_CONFIG_FILE=/dev/null talos update

官方说明 talos update 会先校验签名、跑测试再切换；更新器把新版本装在旧目录旁边，两套测试在新目录里都通过才换过去。Release 资产另提供签名归档、SHA-256 校验和与 Ed25519 签名，实验性的 computer 适配器有单独的资格要求。

升级不是「越新越好」：先读 Release 说明，再在练习安装上跑一遍 doctor 与本教程的回溯链。若导入预演里出现你不认识的来源或动作，停在 --dry-run，不要为了跑通而直接 --apply。另外仓库把 1.0 描述为需要额外运行与升级证据的兼容性承诺，而不是一个日历上的时间点，别把它当既定排期。

做到哪一步算成功：验收清单与交付前自查

按下面四条逐项打勾，能全部复现就说明「安装 → 判决 → 审批 → 回溯」这条链路通了，而不是只在终端里聊了两句。

验收项	预期现象
本地会话可用	`setup terminal` 与 `chat` 正常，`doctor` 无阻断项
判决可观察	`/policy` 给出判决且文件系统无改动，`/eval` 结果未被当作放行依据
闸门禁得住	`/deny` 后哨兵文件未变，`/revoke` 后同类动作回到待决
记录可交付	`events` 有编号、`why` 能解释、`report --out` 产出可读文本

交付前自查：确认配置文件属主与 Agent 运行用户分开；确认没有把 Telegram token 或模型 Key 写进仓库；确认 import 只做了预演或已按指纹确认；确认可视化适配器没有按「已可用」写进方案；确认升级后在练习安装上复跑过回溯链。

成本与隐私：接云端模型会产生真实费用，接 Telegram 会把消息内容交给你的 bot；审计日志、事件与报告里可能包含路径、命令与文本片段，导出前按你们的日志政策做脱敏。README 的说明是「模型与托管成本取决于你的部署方式」，别用别人的账单数字估自己的开销。

常见问题速查

现象	大概率原因 & 处理
切模型时被拒绝	选中 provider 没有对应 key；官方说各 provider 的 key 不通用，切换被拒后原配置仍生效
`/policy` 看似放行却没执行	它按定义只做干跑，真执行要走正常会话动作与审批
`/eval` 说了「安全」仍被拦	它的输出不参与 `decide()`，也不具备批准能力，属正常设计
导入后结果不对	先退回 `--dry-run` 核对来源与动作，再用归档回滚，别直接重跑 `--apply`
Windows 上装不起来	README 只支持 Linux / macOS；Apple Silicon 另有 Homebrew 路线，Windows 需改用虚拟机或 WSL 评估
`talos update` 行为异常	从 Beta.7 或更早且改过 pip 配置的安装，官方建议临时用 `PIP_CONFIG_FILE=/dev/null` 跑一次

← 返回教程中心