1. 项目概述：一个运行在你笔记本上的私人AI助手

如果你和我一样，经常需要在不同设备间切换，或者希望有一个私密、可控的AI助手来处理日常的编码、运维和查询任务，那么 OllamaClaw 这个项目绝对值得你花时间研究一下。简单来说，它是一个 “Telegram优先”的本地智能体（Agent） ，核心能力由 Ollama 提供的大模型驱动。它的设计理念非常明确： 所有交互都通过你私人的Telegram对话进行，所有数据和处理都留在你的本地机器上 。

想象一下这个场景：你正在外面用手机，突然需要检查一下家里服务器上的日志，或者想运行一个安全的脚本看看结果。你不需要打开电脑、连接SSH，甚至不需要记住复杂的命令。你只需要在Telegram里给你的私人机器人发条消息，比如“看看 /var/log/app/error.log 最后50行”，它就能在后台帮你执行 tail -n 50 命令，并把结果清晰地发回给你。整个过程，你的服务器IP、访问凭证、日志内容都不会经过任何第三方服务器，完全在你的掌控之中。

OllamaClaw 就是为实现这种工作流而生的。它不仅仅是一个聊天机器人，更是一个具备 “执行力” 的智能体。它内置了读取文件、执行Shell命令、网页搜索、管理定时任务（Reminder）等一系列工具。你可以通过自然语言指挥它，它会理解你的意图，调用合适的工具，并告诉你结果。更棒的是，它支持 “提醒触发” 的任务，比如让它每天上午10点自动检查GitHub仓库的CI状态，如果有失败就主动通知你。所有这些能力，都通过一个你绝对信任的Telegram私聊窗口来交付。

2. 核心设计思路与架构拆解

OllamaClaw 的架构清晰地反映了其“私有化、本地化、可执行”的设计目标。它不是一个大而全的云服务平台，而是一个精悍的、聚焦于个人效率的本地守护进程。理解其设计思路，能帮助我们在使用和后续自定义时更加得心应手。

2.1 以Telegram作为私有网关

选择Telegram作为唯一的前端交互界面，是一个深思熟虑的决定。首先，Telegram提供了强大、稳定且加密的通讯协议，其Bot API成熟且文档完善。其次，对于个人使用场景，Telegram几乎是一个“永远在线”的客户端，无论是在手机、平板还是电脑网页端，你都能即时收到通知和回复，体验无缝。

OllamaClaw 在此基础上增加了严格的安全层： 所有者白名单（Owner Allowlist） 。你需要在配置中设置自己的 owner_user_id 和 owner_chat_id ，机器人只会响应来自这个特定用户和特定聊天窗口的指令。这意味着即使有人知道了你的Bot Token，也无法操控你的本地机器。这种设计在个人工具中至关重要，它从根本上杜绝了未授权访问。

2.2 共享的本地智能体核心

项目的一个巧妙设计是 “共享核心” 。无论是你通过Telegram发起的对话、在本地终端运行的REPL（交互式命令行）模式、由定时器触发的提醒任务，还是由GitHub Webhook推送的事件，最终都会交由同一个 OllamaClaw 智能体核心来处理。

这个核心维护着统一的会话状态、工具集和记忆系统。例如，你在Telegram里教会了它某个项目的特定工作流程，这个“知识”可能会通过核心记忆系统沉淀下来。之后，当定时任务或REPL模式处理相关问题时，也能利用上这些积累的经验。这种统一性保证了体验的一致性和知识的可复用性。

2.3 工具集的“安全第一”哲学

OllamaClaw 内置的工具集是精心挑选和严格约束的，体现了“能力与安全并重”的思想。

  • bash : 这是最强大也最危险的工具。 OllamaClaw 对此实施了分级策略：对于 ls , cat , grep 等非破坏性命令，默认放行；对于 rm , dd , mv 等可能造成数据丢失的命令，会要求你在Telegram中二次确认；而对于 shutdown , reboot 等关键生命周期命令，则完全禁止。这个策略在 config.json 中是可配置的。
  • 文件操作 ( read_file , write_file ) : 支持绝对路径和相对路径（相对于 OllamaClaw 的运行目录）。 write_file 可以自动创建不存在的目录，这在进行项目笔记或日志记录时非常方便。
  • 网络工具 ( web_search , web_fetch ) : 这两个工具依赖于 Ollama 托管的API，这意味着你需要一个 OLLAMA_API_KEY 。它们并非直接访问互联网，而是通过 Ollama 的服务进行，这在某些网络环境下可能是一个限制，但也简化了配置和依赖。
  • 系统提示词管理工具 ( system_prompt_* ) : 这是一组高级工具，允许智能体在运行时动态调整自己的“行为准则”（即系统提示词）。它采用“基础层+覆盖层”的管理模式，智能体只能修改覆盖层 ( overlay )，并且所有修改都有历史记录可追溯和回滚。这为高级用户提供了极大的定制灵活性。

注意 ：工具的安全性很大程度上依赖于底层大模型对指令理解的准确性。虽然 OllamaClaw 设置了安全护栏，但在赋予它高权限（如在生产服务器上运行）时，仍需保持警惕，最好在沙箱或低权限用户环境中先行测试。

2.4 基于提醒的主动式自动化

“提醒（Reminder）”功能是 OllamaClaw 从被动响应转向主动服务的关键。它本质上是一个基于cron的定时任务系统，但任务内容是由自然语言描述的，并由大模型在每次触发时动态理解和执行。

例如，你可以设置一个提醒：“每周一上午9点，检查项目X的GitHub仓库是否有新的PR，并总结其标题和作者”。 OllamaClaw 会记住这个指令。每到周一9点，它会自动启动一个智能体会话，理解“检查PR”需要调用 web_fetch 工具访问GitHub API，然后生成摘要发给你。

更智能的是 “预取（Prefetch）”学习机制 。如果一个提醒任务多次稳定地执行了相同的bash命令（比如每次都是 cd /my/project && git pull ）， OllamaClaw 会将这些命令标记为“稳定”，并在下次该提醒触发时 自动预先执行 这些命令，将其结果作为上下文注入给大模型。这大大加快了任务执行速度，因为模型无需再“思考”这些固定步骤。

3. 从零开始部署与配置实战

理论说得再多，不如亲手搭一个。下面我将带你从零开始，在Linux系统上部署和配置一个属于你自己的 OllamaClaw 。这个过程同样适用于macOS，Windows用户可能需要借助WSL或进行适当的路径调整。

3.1 前置条件准备

在安装 OllamaClaw 之前，我们需要确保它的“大脑”和“通讯工具”已经就位。

  1. 安装 Ollama ： OllamaClaw 的核心是 Ollama ，你需要先安装它并至少下载一个模型。访问 ollama.com 获取安装指令。对于Linux，通常是一行命令：

    curl -fsSL https://ollama.com/install.sh | sh

    安装完成后，拉取一个模型，例如官方推荐的 llama3.2 或项目默认的 kimi-k2.5:cloud （注意后者是云端模型，需要网络和API Key）：

    ollama pull llama3.2

    运行 ollama serve 确保服务在后台启动（通常安装后会自动运行）。

  2. 创建 Telegram Bot ： 打开Telegram，搜索 @BotFather 这个官方机器人。

    • 发送 /newbot 指令，按提示设置机器人的名字（如 MyOllamaClawBot ）和用户名（必须以 bot 结尾，如 my_ollamaclaw_bot ）。
    • 创建成功后， BotFather 会给你一个 HTTP API Token ，形如 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ 。 妥善保存这个Token，它相当于你机器人的密码。
    • 暂时不要关闭与 BotFather 的对话，我们还需要获取你的用户ID。

  3. 获取你的 Telegram User ID ： 在Telegram中搜索 @userinfobot ，向它发送任意消息，它会回复你的详细用户信息，其中就包括 Id 。这个数字就是你的 owner_user_id 。

3.2 安装与初始化 OllamaClaw

有了前置条件，现在可以安装 OllamaClaw 本体了。项目是Go语言编写的，安装非常方便。

# 方法一：直接从源码仓库安装（推荐，方便更新）
go install github.com/ParthSareen/OllamaClaw@latest

# 安装后，二进制文件通常位于 $GOPATH/bin 或 $GOBIN 下，请确保该目录在系统PATH中
# 你可以通过 `which ollamaclaw` 来检查是否安装成功

# 方法二：克隆仓库并本地构建（适合需要修改代码的开发者）
git clone https://github.com/ParthSareen/OllamaClaw.git
cd OllamaClaw
go build -o ollamaclaw .
# 这样会在当前目录生成可执行文件 `ollamaclaw`

安装完成后，运行初始化命令。如果这是第一次运行，且没有配置文件，它会启动一个交互式的配置向导。

./ollamaclaw launch

你会看到一个基于文本的交互界面，依次询问以下信息：

  • Ollama host : 通常就是 http://localhost:11434 ，除非你的Ollama运行在其他地方。
  • Default model : 输入你本地已拉取的模型名，如 llama3.2 。
  • Telegram bot token : 粘贴刚才从 @BotFather 获取的Token。
  • Telegram owner ID : 输入从 @userinfobot 获取的你的用户ID。向导会默认将这个ID同时用于 owner_chat_id 和 owner_user_id ，这对于私人使用完全没问题。
  • GitHub webhook 相关配置 ：这部分是可选的，如果你不需要GitHub集成，可以直接按回车跳过。

配置完成后， OllamaClaw 会尝试启动。你应该能在终端看到连接Telegram成功的日志。同时，在你的Telegram里，找到你创建的机器人（通过它的用户名），发送 /start 命令，你应该能收到机器人的回复。恭喜，至此最基本的通信链路已经打通！

3.3 核心配置文件详解

初始化后，配置文件会保存在 ~/.ollamaclaw/config.json 。理解这个文件的各个字段，对于后续的调优和问题排查至关重要。

{
  "ollama_host": "http://localhost:11434",
  "default_model": "llama3.2", // 你实际使用的模型
  "db_path": "~/.ollamaclaw/state.db",
  "compaction_threshold": 0.8, // 上下文窗口使用率超过80%时触发压缩
  "keep_recent_turns": 8, // 压缩后保留的最新对话轮数
  "context_window_tokens": 252000, // 模型上下文窗口大小（需与模型匹配）
  "tool_output_max_bytes": 16384, // 单个工具输出最大字节数（防止爆窗）
  "bash_timeout_seconds": 120, // bash命令超时时间
  "telegram": {
    "bot_token": "YOUR_BOT_TOKEN",
    "owner_chat_id": YOUR_USER_ID,
    "owner_user_id": YOUR_USER_ID
  },
  "github_webhook": {
    "enabled": false, // 是否启用GitHub Webhook
    "listen_addr": "127.0.0.1:8787", // 本地监听地址
    "secret": "", // Webhook签名密钥，用于验证请求来源
    "owner_login": "", // 你的GitHub用户名
    "repo_allowlist": [] // 允许触发Webhook的仓库列表
  }
}

关键参数调整建议：

  • default_model : 根据你的硬件和需求选择。 llama3.2:1b 等小模型响应快， llama3.2:3b 或 qwen2.5:7b 等模型能力更强。
  • context_window_tokens : 务必与所选模型的真实上下文长度匹配！ 例如 llama3.2:3b 的上下文是128k，而不是默认的252k。设置过大会导致不必要的内存占用和潜在错误。
  • compaction_threshold 和 keep_recent_turns : 如果你的对话非常长，可以适当降低阈值（如0.7）或增加保留轮数（如12），以平衡上下文长度和历史记忆。
  • tool_output_max_bytes : 如果经常处理大文件，可以适当调大，但注意过大的输出可能会被模型截断，影响理解。

3.4 进阶配置：GitHub Webhook集成

这个功能让你能将GitHub事件（如PR更新、CI完成）主动推送到你的Telegram会话，实现项目监控自动化。

  1. 修改配置 ：编辑 config.json ，启用并填写 github_webhook 部分。

    "github_webhook": {
  "enabled": true,
  "listen_addr": "127.0.0.1:8787",
  "secret": "YourSuperSecretString", // 生成一个强密码
  "owner_login": "YourGitHubUsername",
  "repo_allowlist": ["your-org/your-repo"] // 可选，为空则接收所有仓库事件
}

    重启 OllamaClaw 。

  2. 配置端口转发 ：由于 OllamaClaw 运行在本地，你需要让GitHub能访问到它的 listen_addr （如 127.0.0.1:8787 ）。可以使用 ngrok 或 cloudflared 等工具创建隧道。

    # 使用 ngrok 示例 (需要先注册 ngrok 并获取authtoken)
ngrok http 8787

    ngrok 会生成一个公网URL（如 https://abc123.ngrok.io ）。

  3. 在GitHub仓库设置Webhook ：

    • 进入你的GitHub仓库 -> Settings -> Webhooks -> Add webhook。
    • Payload URL : 填入你的隧道URL + /webhooks/github ，例如 https://abc123.ngrok.io/webhooks/github 。
    • Content type : 选择 application/json 。
    • Secret : 填入你在配置中设置的 YourSuperSecretString 。
    • Which events... : 选择 Let me select individual events ，然后勾选你关心的事件，如 Pull requests , Pull request reviews , Check runs 等。
    • 保存后，GitHub会发送一个 ping 事件进行测试。如果配置正确，你会在 OllamaClaw 的日志和Telegram中收到通知。

4. 日常使用技巧与高级功能探索

配置妥当后， OllamaClaw 就成为了你得力的数字助手。下面分享一些高频使用场景和进阶技巧。

4.1 基础对话与文件操作

最直接的用法就是像使用ChatGPT一样和它聊天，但它能直接操作你本地的文件系统。

  • 查询日志 ：“读取 /var/log/syslog 文件，找出今天所有包含 ‘error’ 的行，并统计数量。”
    • 背后逻辑：它会调用 read_file 工具读取文件，然后可能调用 bash 工具执行 grep 和 wc -l 命令来完成统计。
  • 编写脚本 ：“在 ~/scripts 目录下创建一个名为 cleanup_tmp.sh 的脚本，内容为删除 /tmp 下超过7天的文件。”
    • 背后逻辑：它会先检查目录是否存在，然后调用 write_file 工具创建脚本文件。 注意 ：由于涉及删除操作，执行这个脚本时可能需要你在Telegram中批准。
  • 搜索与总结 ：“搜索‘如何在Go中优雅地关闭HTTP服务器’，并总结三个要点发给我。”
    • 背后逻辑：调用 web_search 工具获取信息，然后由大模型进行归纳总结。

4.2 提醒功能的妙用

提醒功能是自动化工作的核心。其时间全部基于 America/Los_Angeles (PST/PDT) 时区，在设置时请注意时区转换。

  • 创建一次性提醒 ： /reminder add once "明天下午3点，提醒我打电话给客户张三"
  • 创建周期性任务 ：
    • 每天上午10点检查服务器状态 ： /reminder add daily 10:00 "检查服务器负载和磁盘使用率"
    • 每周一上午9点同步项目 ： /reminder add weekdays "Mon" 09:00 "进入~/project目录，执行git pull，并报告是否有更新"
  • 管理提醒 ：
    • /reminder list all ：列出所有提醒。
    • /reminder safe <id> ：将一个提醒标记为“安全模式”。这意味着该提醒中涉及的 bash 命令如果之前被成功执行过并被学习为“预取命令”，那么未来运行时将自动执行，无需再次确认。这对于完全信任的自动化任务非常有用。
    • /reminder prefetch list <id> ：查看某个提醒已学习的预取命令。

实操心得 ：在设置涉及文件操作的提醒时，尽量使用绝对路径。因为提醒任务运行时的工作目录可能与你在Telegram聊天时的目录不同，使用相对路径可能导致找不到文件。

4.3 系统提示词与核心记忆管理

这是 OllamaClaw 区别于简单脚本的“智能”所在。系统提示词定义了AI助手的角色、行为规范和能力范围。核心记忆则是助手从与你的长期对话中学习到的稳定偏好和知识。

  • 查看当前系统提示词 ：使用 /fullsystem 命令，或者在REPL模式中使用 system_prompt_get 工具。你会看到基础提示词和覆盖层内容的合并结果。
  • 动态调整助手行为 ：你可以直接告诉助手修改它的行为准则。例如，发送消息：“请将‘在回复代码时总是使用代码块’这条规则添加到你的系统指令中。” 助手会调用 system_prompt_update 工具，以 append 模式将这条规则添加到覆盖层 ( ~/.ollamaclaw/system_prompt.overlay.md )。
  • 理解核心记忆（Dreaming） ：每进行10轮用户对话，助手会在后台启动一次“梦境”过程，分析最近的对话，提取出稳定的模式（比如你总是要求用表格总结数据、你某个项目的特定路径等），并将其写入 ~/.ollamaclaw/core_memories.md 。之后，这些核心记忆会作为系统上下文的一部分注入每次对话，让助手越来越了解你的习惯。你可以用 /show dreaming off 关闭该会话的通知，或用 /dream 命令手动触发一次核心记忆刷新。

重要提示 ：系统提示词覆盖层和核心记忆文件都是纯文本文件，你也可以直接用文本编辑器手动编辑。但通过助手工具进行修改，可以保留完整的历史记录 ( system_prompt.overlay.history.jsonl )，方便回滚。

4.4 会话管理与状态控制

长时间的对话会导致上下文膨胀，影响速度和成本。 OllamaClaw 提供了精细的会话管理工具。

  • 监控上下文大小 ：使用 /status 命令。关键信息是 estimated next prompt size ，它预估了下一轮请求的token数量（按 len(request_json)/4 粗略计算）。当这个数字接近 context_window_tokens 时，就需要警惕了。
  • 主动压缩会话 ：当预估大小超过 compaction_threshold 阈值时，压缩会自动触发。你也可以通过开启一个新会话来间接触发旧会话的归档（旧会话仍保存在数据库，但不再参与新对话）。
  • 开始一个新会话 ：使用 /reset 命令。这会归档当前会话的所有消息（标记为 archived=1 ），并开启一个全新的、干净的会话。这对于切换讨论主题非常有用。
  • 控制思考过程可见性 ：使用 /show thinking on 和 /verbose on 。开启后，你能看到助手在调用工具前的“内心独白”（推理过程），以及详细的工具调用和返回的追踪日志。这对调试复杂指令或理解助手的行为逻辑非常有帮助，但也会使消息流变得冗长。

5. 常见问题排查与性能调优

即使设计再完善，在实际使用中也可能遇到各种问题。下面是我在长期使用中积累的一些常见问题及其解决方法。

5.1 连接与通信问题

问题现象 可能原因 排查步骤与解决方案
启动时提示 Failed to connect to Ollama 1. Ollama服务未运行。
2. ollama_host 配置错误。
3. 防火墙/网络策略阻止。		 1. 运行 ollama serve 并检查服务状态 ( systemctl status ollama 或 `ps aux
Telegram机器人无响应 1. Bot Token错误。
2. owner_chat_id 或 owner_user_id 配置错误。
3. 网络问题导致无法连接Telegram API。		 1. 检查 config.json 中的 bot_token 是否与 @BotFather 提供的一致，且无多余空格。
2. 确认你是在配置的 owner_chat_id 对应的私聊窗口中发送消息。可以用 /configure 命令重新运行向导。
3. 查看 ollamaclaw 运行日志，看是否有连接Telegram API的错误信息。
模型响应慢或超时 1. 本地模型过大，硬件（CPU/内存）不足。
2. 上下文过长，导致每次生成都需要处理大量文本。
3. 网络延迟（如果使用云端模型）。		 1. 换用更小的模型（如 llama3.2:1b ）。
2. 使用 /status 检查上下文大小，适时使用 /reset 或等待自动压缩。
3. 对于云端模型，检查网络状况。考虑在 bash 命令中增加 timeout_seconds 参数。

5.2 工具执行与权限问题

问题现象 可能原因 排查步骤与解决方案
bash 命令被拒绝或要求确认 命令触发了安全策略。 1. 非破坏性命令（如 ls , cat ）应直接执行。如果被拒，检查配置中 bash 策略是否被意外修改。
2. 破坏性命令（如 rm ）需要在Telegram中点击“批准”按钮。确保你收到了确认请求。
read_file 或 write_file 失败 1. 路径不存在或拼写错误。
2. OllamaClaw 进程用户权限不足。		 1. 使用绝对路径，或在命令中先让助手 bash 执行 pwd 确认当前工作目录。
2. 检查文件/目录的权限 ( ls -la )。确保运行 ollamaclaw 的用户有读写权限。 切勿以root身份长期运行 ，必要时将特定目录权限授予运行用户。
web_search 返回错误 1. OLLAMA_API_KEY 环境变量未设置或无效。
2. Ollama云端API服务暂时不可用。		 1. 确认已正确设置环境变量： export OLLAMA_API_KEY=your_key_here ，并且是在启动 ollamaclaw 的同一个shell中设置。
2. 稍后重试，或检查Ollama服务状态。

5.3 数据库与状态问题

问题现象 可能原因 排查步骤与解决方案
会话历史丢失或混乱 SQLite数据库文件 ( state.db ) 损坏。 1. 备份！ 首先复制 ~/.ollamaclaw/state.db 文件。
2. 尝试使用SQLite命令行工具修复：`sqlite3 ~/.ollamaclaw/state.db “.recover”
提醒任务没有按时触发 1. 系统时区与PST/PDT不一致。
2. OllamaClaw 进程挂掉或未运行。
3. Cron调度器内部错误。		 1. 确认运行 OllamaClaw 的服务器系统时区，并理解提醒时间是基于 America/Los_Angeles 计算的。
2. 检查 ollamaclaw 进程是否在运行 (`ps aux

5.4 性能调优建议

  1. 模型选型 ：这是最大的性能影响因素。在个人笔记本上， 7B 参数以下的模型通常能在保证可用性的同时提供不错的响应速度。 llama3.2:3b 、 qwen2.5:3b 都是不错的起点。如果追求极速响应，可以尝试 1B 左右的模型。
  2. 上下文管理 ：合理设置 context_window_tokens （匹配模型）和 compaction_threshold （如0.7）。过大的上下文不仅慢，还可能影响模型对最近信息的关注度。养成使用 /reset 清理无关会话的习惯。
  3. 预取学习 ：对于重复性的提醒任务，充分利用 auto_prefetch 功能。在任务稳定运行几次后，使用 /reminder safe <id> 将其标记为安全，后续运行将跳过学习阶段，直接执行预取命令，大幅提升速度。
  4. 运行环境 ：如果可能，在拥有更好CPU和内存的机器上运行 OllamaClaw 和 Ollama 。对于Intel/AMD CPU，确保开启了相应的加速指令集支持。也可以考虑使用 Ollama的GPU加速 ，但这需要额外的驱动和配置。

OllamaClaw 将一个强大的本地大模型智能体封装成了一个通过Telegram即可便捷使用的私人助手。它的价值在于将AI能力无缝、安全地融入到了个人的工作流中。从简单的文件查看到复杂的自动化任务编排，它都能胜任。当然，它的能力边界也清晰可见：依赖于本地或指定的大模型服务，工具集固定但可扩展（需要修改代码），适合技术背景的用户进行深度定制。

我个人最欣赏的是它的“隐私优先”和“本地化”设计。在数据主权日益重要的今天，能够完全掌控自己的数据和AI交互过程，是一种安心。如果你对Go语言熟悉，完全可以基于它的框架，添加自己需要的工具（比如调用内部API、查询特定数据库），打造一个独一无二的专属数字员工。开始用它来处理那些重复、琐碎的数字事务吧，把时间和精力留给更有创造性的思考。

# Ollama
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

Hugging Face Optimum 源码静态评测：模型部署优化框架的工程结构与验证边界

avatar 亚马逊云科技技术品牌专区
cover

单片机基础核心知识点汇总（十）

avatar 亚马逊云科技技术品牌专区
cover

AI 工具能解决独立站获客难的问题吗？

avatar 亚马逊云科技技术品牌专区