ChatOllama 是一个开源智能体（agentic）应用，用于在本地模型或托管模型上运行 AI 智能体。其当前主要用户入口是可安装的 chatollama-agent 命令行应用。该项目不是一个用于构建智能体的 SDK，而是用于运行智能体的应用。
用途 ChatOllama 的核心用途是让用户通过命令行与 AI 智能体交互，并在本地或远程模型上执行任务。它支持多种模型提供商，能够自动发现可用模型，并允许智能体在对话过程中调用工具来检查工作目录。
主要能力
- 支持本地和托管模型：Ollama 被支持为 OpenAI 兼容提供商之一，也可配置其他提供商。
- 模型自动发现：启动时，ChatOllama 会发现可用模型。已配置的远程提供商会提供内置模型目录；OpenAI 还会进行过滤后的模型发现；可用的 Ollama 端点会提供其已安装的模型。发现失败会产生警告，但不会阻止 CLI 打开。
- 工具调用：运行时可以调用 read_file、list_directory、grep 和 find_files 来检查 CLI 启动时所在的目录。终端模式会显示每个工具的验证输入、执行状态和有限结果。
- 模型切换与管理：通过 /models 查看可用模型并选择，通过 /model <provider>/<model-id> 直接切换，通过 /new 清空对话历史但保留当前模型，通过 /exit 退出。
- 对话与取消：输入消息后按回车发送，后续消息继续同一内存中的对话。响应过程中按 Ctrl+C 可取消该响应并保持 CLI 打开；空闲时按 Ctrl+C 退出。
- 工作区文件操作：write_file 和 edit_file 支持原子替换，对同一路径的更改会序列化，拒绝超过 1,048,576 字节的内容。成功读取、写入和编辑会返回完整内容的 sha256:<hex> 版本。写入和编辑可接受可选的 expectedVersion，过期值会返回 VERSION_CONFLICT 而不更改文件。edit_file 支持单个精确替换以及最多 100 个替换的批量操作，要求每个 oldText 在原始内容中精确匹配一次、范围不重叠且整批原子化。匹配不支持模糊匹配。不暴露 shell 命令。
使用方式
- 环境要求：需要 Node.js 24 或更高版本。
- 配置提供商：在启动 CLI 之前，为要使用的提供商设置 API 密钥。CLI 还识别显式的启动覆盖参数，如 AGENT_PROVIDER、AGENT_MODEL、AGENT_BASE_URL、AGENT_API_KEY。AGENT_PROVIDER 或 AGENT_MODEL 优先于已保存的选择；AGENT_BASE_URL 和 AGENT_API_KEY 覆盖其端点和凭据而不改变提供商/模型身份。若要将提供商的模型加入自动发现，仍需映射的提供商凭据，仅 AGENT_API_KEY 不够。
- Ollama 兼容性：当没有可用模型时，CLI 回退到 ollama/qwen3:8b；仅设置 AGENT_MODEL 而未设置 AGENT_PROVIDER 时使用 Ollama。要显式选择，可设置 AGENT_PROVIDER=ollama，必要时设置 AGENT_BASE_URL。
- 交互命令：输入 /models 查看并选择模型，交互终端中可用方向键和回车，按 Escape 取消；输入 /model <provider>/<model-id> 直接切换，例如 /model openrouter/openai/gpt-5-mini；输入 /new 清空对话历史；输入 /exit 退出。
- 纯文本或脚本输入：/models 会打印编号列表而非交互式选择器。
- 无提供商演示：可运行确定性的工具循环，无需提供商、网络请求或付费 API 密钥。该演示使用 AI SDK MockLanguageModelV3 执行两个真实模型步骤：第一步请求安全的 UTC 时间工具，第二步接收结果并流式输出最终答案。
- 工作区限制：CLI 启动目录是工作区根目录，工具路径必须相对于该根目录，绝对路径、.. 逃逸、前缀混淆路径以及解析到根目录外的符号链接会被拒绝。读取/搜索结果有上限并报告截断。
适用场景
- 需要在本地或远程模型上运行 AI 智能体并通过命令行交互的用户。
- 需要在对话中检查工作目录文件、搜索内容的场景。
- 需要模型自动发现和切换的开发者或高级用户。
- 希望使用开源工具运行智能体，而非构建智能体的项目。
限制
- 是一个运行智能体的应用，不是构建智能体的 SDK。
- 需要 Node.js 24 或更高版本。
- 对话和 API 密钥不会保存；模型选择会保存为下次启动默认值。
- 文件操作不暴露 shell 命令。
- 内容大小限制为 1,048,576 字节，不支持模糊匹配。
- 发现失败会产生警告，但不阻止 CLI 打开。
- 回退模型 ollama/qwen3:8b 不意味着该模型已安装或可达。
- 配置优先级、保存偏好位置、纯模式行为和提供商特定示例需参阅 Agent CLI 指南（文档未在此提供具体内容）。
