agenticSeek | 02: 先跑起来：用 Docker、Ollama 和 Web UI 体验 AgenticSeek

上一篇我们从产品和架构角度解释了 AgenticSeek 为什么会受到关注：它不是一个普通本地聊天页面，而是一个本地优先、能调用工具、能浏览网页、能执行代码、能操作文件的 local agent 项目。

这一章进入实操：把 AgenticSeek 跑起来。

为了降低门槛，本文选择一条最适合新手的路线：

Ollama 本地模型 + Docker Compose 启动 AgenticSeek 依赖服务 + Web UI 访问 http://localhost:3000

这条路线的好处是：大部分服务由 Docker Compose 管理，用户只需要重点理解两个配置文件：.env和config.ini。

本章目标

读完并跟着操作后，你应该能完成三件事：

1. 用 Ollama 在本机启动一个本地 LLM Provider。
2. 用./start_services.sh full启动 AgenticSeek 的 Web UI、后端、搜索服务和 Redis/Valkey。
3. 在 Web UI 里提交几个简单任务，验证搜索、写文件、写代码这些能力是否正常。

本文也会顺手解释几个最容易踩坑的问题：

• SEARXNG_BASE_URL为什么有时是http://searxng:8080，有时是http://localhost:8080？
• WORK_DIR应该设置成哪里？
• config.ini里provider_name、provider_model、provider_server_address分别是什么意思？
• Web UI 模式和 CLI 模式有什么区别？
• 为什么本地运行也要注意安全边界？

先看整体拓扑

AgenticSeek 的 Web UI 完整模式不是只启动一个 Python 进程。按照当前项目的docker-compose.yml，./start_services.sh full会启动这些服务：

把它画成流程图，大致是这样：

浏览器打开 localhost:3000 -> React 前端提交 POST /query -> FastAPI 后端 localhost:7777 -> Interaction 选择 Agent -> Agent 调用 Ollama / SearxNG / Browser / Tools -> 前端轮询 latest_answer 和截图

这里有一个关键点：Ollama 通常运行在宿主机上，而 AgenticSeek 的 backend 运行在 Docker 容器里。容器访问宿主机上的 Ollama 时，会通过项目配置里的DOCKER_INTERNAL_URL=http://host.docker.internal做地址转换。

所以你在config.ini里写：

provider_server_address = 127.0.0.1:11434

Docker 后端实际会把它转成类似：

http://host.docker.internal:11434

这也是很多本地 Agent 项目的共同坑点：同一个localhost，在宿主机和容器里不是同一个网络位置。

环境准备

本文以 macOS/Linux 为主，Windows 用户可以参考 README 中的.bat脚本。

你需要提前准备：

先检查 Docker 是否可用：

dockerinfodockercompose version

如果docker info报错，说明 Docker daemon 没有启动。macOS/Windows 需要先打开 Docker Desktop，Linux 可以尝试：

sudosystemctl startdocker

再检查 Ollama：

ollama--version

如果还没有安装 Ollama，需要先到 Ollama 官网安装。安装完成后，启动 Ollama 服务：

ollama serve

这个命令会占用一个终端。如果你已经安装了桌面版 Ollama，它可能已经在后台运行，不一定需要手动执行。

拉取一个本地模型

AgenticSeek 的 README 推荐使用推理能力较强的模型，例如 DeepSeek、Qwen、Magistral 这类模型。为了便于演示，可以先选一个你的机器能跑得动的模型。

如果你的硬件足够，可以尝试：

ollama pull deepseek-r1:14b

如果显存或内存不足，可以换更小的模型，但要接受一个现实：模型越小，Agent 路由、工具调用格式、代码修正、网页总结的稳定性通常越差。

拉取完成后，先做一个最小测试：

ollama run deepseek-r1:14b

看到模型能正常回答后，就可以退出对话，继续配置 AgenticSeek。

克隆项目并准备工作目录

如果是第一次使用，可以按 README 的方式克隆：

gitclone https://github.com/Fosowl/agenticSeek.gitcdagenticSeekcp.env.example .env

README 中使用的是mv .env.example .env。我更建议用cp，这样可以保留一份原始示例，后续对照配置更方便。

接着准备一个单独的工作目录：

mkdir-p~/agenticseek_workspace/inputmkdir-p~/agenticseek_workspace/outputmkdir-p~/agenticseek_workspace/tmp

这个目录很重要。AgenticSeek 会把它挂载进 backend 容器，Agent 的文件读写和部分命令执行会围绕它展开。

不要一开始就把WORK_DIR指向这些目录：

• 用户主目录：/Users/yourname
• 公司代码根目录
• 下载目录
• 桌面
• 包含隐私文件、密钥、合同、财务资料的目录

更稳妥的方式是把需要处理的文件复制到~/agenticseek_workspace/input，让 Agent 的输出落在output或tmp里。这样即使 Agent 误操作，影响范围也比较可控。

配置.env

.env负责告诉 Docker 和后端：端口、工作目录、搜索服务地址、后端地址、API Key 等环境信息是什么。

打开.env，重点看这几项：

SEARXNG_BASE_URL="http://searxng:8080" SEARXNG_PORT=8080 REDIS_BASE_URL="redis://redis:6379/0" WORK_DIR="/Users/username/Documents/workspace_with_my_files" OLLAMA_PORT="11434" BACKEND_PORT="7777" BACKEND_HOST="127.0.0.1" FRONTEND_ORIGINS="http://localhost:3000" REACT_APP_BACKEND_URL=http://localhost:7777

对本章的 Web UI + Docker 完整模式，建议这样配置：

SEARXNG_BASE_URL="http://searxng:8080" SEARXNG_PORT=8080 REDIS_BASE_URL="redis://redis:6379/0" WORK_DIR="/Users/你的用户名/agenticseek_workspace" OLLAMA_PORT="11434" BACKEND_PORT="7777" BACKEND_HOST="127.0.0.1" FRONTEND_ORIGINS="http://localhost:3000" REACT_APP_BACKEND_URL=http://localhost:7777

其中最需要理解的是这三项。

WORK_DIR

WORK_DIR是 Agent 可读写的宿主机目录。

在docker-compose.yml里，backend 服务会把它挂载到容器内的/opt/workspace：

volumes:-${WORK_DIR:-.}:/opt/workspace

同时 backend 容器内会设置：

environment:-WORK_DIR=/opt/workspace

所以从 Agent 视角看，它操作的是/opt/workspace；从你电脑视角看，对应的是.env里的WORK_DIR。

这也是为什么一定要给它一个单独目录。

SEARXNG_BASE_URL

Web UI 完整模式下，backend 在 Docker 容器里运行，SearxNG 也在 Docker Compose 网络里运行。因此 backend 访问 SearxNG 要用容器服务名：

SEARXNG_BASE_URL="http://searxng:8080"

注意这里永远是容器内部端口8080。即使你把宿主机暴露端口改成8001，backend 访问 SearxNG 仍然应该是http://searxng:8080。

只有 CLI 模式下，后端运行在宿主机，才需要改成：

SEARXNG_BASE_URL="http://localhost:8080"

这是新手最容易混淆的地方。

BACKEND_HOST

.env.example对这一项写得很谨慎：

BACKEND_HOST="127.0.0.1"

这意味着后端默认只绑定本机回环地址。由于/query接口没有认证，而且 Agent 能运行命令，默认不暴露到局域网是正确选择。

除非你非常清楚自己在做什么，并且有反向代理、认证、防火墙，否则不要把它改成0.0.0.0。

配置config.ini

.env解决的是服务和环境问题，config.ini解决的是 AgenticSeek 自己该怎么调用模型、怎么使用浏览器、是否恢复会话、是否开启语音等问题。

一个适合本章路线的最小配置如下：

[MAIN] is_local = True provider_name = ollama provider_model = deepseek-r1:14b provider_server_address = 127.0.0.1:11434 agent_name = Jarvis recover_last_session = False save_session = False speak = False listen = False jarvis_personality = False languages = en zh safe_mode = True [BROWSER] headless_browser = True stealth_mode = False

这里有几个点要特别说明。

config.ini不支持行内注释

README 里已经提醒过：不要把带注释的示例直接复制到config.ini。

例如不要写成：

provider_name = ollama # 使用 Ollama

应该写成：

provider_name = ollama

配置文件里如果混入注释，可能导致解析异常或取值不符合预期。

is_local

本章使用 Ollama，所以设置为：

is_local = True

如果你使用 OpenAI、DeepSeek、Google、Anthropic 这类云端 API Provider，则通常设置为：

is_local = False

本章先不走云端 API 路线，因为它会把请求内容发送到云端，不符合“本地优先体验”的目标。

provider_name

如果你使用 Ollama，应该写：

provider_name = ollama

如果你使用 LM Studio，应该写：

provider_name = lm-studio

如果你使用的是本地 OpenAI-compatible server，例如某些 llama.cpp server，才考虑：

provider_name = openai is_local = True

这几个名字不要混用。尤其是 LM Studio，README 明确提醒不要把它写成openai。

provider_model

这一项必须和你的 Provider 中实际存在的模型名一致。

如果你执行的是：

ollama pull deepseek-r1:14b

那么这里就写：

provider_model = deepseek-r1:14b

如果你换成其他模型，也要同步修改这里。

provider_server_address

Ollama 默认端口是11434，所以写：

provider_server_address = 127.0.0.1:11434

即使 backend 在 Docker 里运行，也可以这么写。项目的Provider会结合DOCKER_INTERNAL_URL把容器里的访问地址转到宿主机。

headless_browser

Web UI + Docker 模式建议保持：

headless_browser = True

因为浏览器运行在容器环境里，通常不显示真实窗口。项目代码里也会在检测到 Docker 环境时强制 headless。

如果你想看到真实浏览器窗口，更适合后面尝试 CLI 模式。

safe_mode

建议第一次体验时先打开：

safe_mode = True

这样 Bash 工具会对一部分危险命令做拦截。它不是完整沙箱，但对新手更友好。

启动完整 Web UI 模式

确认.env和config.ini配好后，启动完整模式：

./start_services.sh full

这个脚本会做几件事：

1. 读取.env。
2. 检查WORK_DIR是否设置。
3. 检查 Docker 是否运行。
4. 检查 Docker Compose 是否可用。
5. 生成 SearxNG secret key。
6. 先启动 backend 并等待容器 ready。
7. 再通过 Docker Compose profile 启动完整服务。

第一次启动会拉取镜像、构建前后端容器，可能比较慢。README 提醒过，首次运行后端可能需要几分钟。

启动完成后，打开浏览器：

http://localhost:3000

如果页面能打开，并且右上角状态显示 Online，说明前端已经能访问后端。

你也可以单独检查后端健康状态：

curlhttp://localhost:7777/health

正常会返回类似：

{"status":"healthy","version":"0.1.0"}

如果你想确认 SearxNG 是否能访问，可以打开：

http://localhost:8080

注意，这是给人从浏览器访问的宿主机地址。backend 在 Docker 内访问 SearxNG 仍然用http://searxng:8080。

第一个任务：让它做一次网页搜索

先从低风险任务开始，不要一上来就让它改文件或执行复杂脚本。

可以在 Web UI 输入：

进行网页搜索，找出 AgenticSeek 项目的主要能力，用 5 条中文要点总结。

这里刻意写了“进行网页搜索”。因为 README 也提到，AgenticSeek 早期路由系统不一定总能准确判断用户意图。你把动作说清楚，Router 更容易把任务交给 Browser Agent。

观察几个现象：

• 前端状态是否变为工作中。
• 后端日志里是否出现 SearxNG 搜索。
• 页面右侧是否出现浏览器截图。
• 最终回答是否包含网页来源或搜索结果总结。

如果这个任务失败，先不要急着怀疑模型。优先检查：

• SearxNG 是否能打开。
• .env里的SEARXNG_BASE_URL是否仍是http://searxng:8080。
• backend 是否能正常启动。
• 模型是否正在运行。

第二个任务：让它写入工作目录

确认搜索能力可用后，再测试文件写入。

输入：

进行网页搜索，找出 3 个适合学习 local agent 的开源项目名称和一句话介绍，并保存到 local_agent_projects.txt。

如果执行成功，你应该能在WORK_DIR对应的宿主机目录里看到输出文件。

例如：

~/agenticseek_workspace/local_agent_projects.txt

这里要注意：Agent 在容器内看到的是/opt/workspace，你在宿主机看到的是.env里配置的WORK_DIR。两者通过 Docker volume 映射到一起。

如果文件没有出现，可以从几个角度排查：

• WORK_DIR路径是否真实存在。
• WORK_DIR是否有写权限。
• 任务是否真的路由到了 File/Code/Planner 相关 Agent。
• Agent 是否只是回答了内容，但没有执行保存动作。

你可以把提示写得更明确：

请把结果保存到工作目录根目录下的 local_agent_projects.txt 文件中。

第三个任务：让它写一个小脚本

最后测试代码执行能力。建议用一个没有外部依赖、不会修改系统状态的小脚本。

输入：

写一个 Python 脚本，统计当前工作目录下每种文件扩展名的数量，并把脚本保存为 count_extensions.py，然后运行它。

这个任务会测试几个链路：

• Router 是否选择 Code Agent，或 Planner 是否拆解任务。
• LLM 是否按工具协议输出python或bash代码块。
• 工具系统是否能解析代码块。
• Python 执行器是否能运行脚本。
• 执行结果是否会反馈给 Agent。

如果失败，常见原因包括：

• 模型没有按 Markdown code block 格式输出代码。
• 模型生成了需要额外依赖的代码。
• 工作目录为空或权限不足。
• safe mode 拦截了部分命令。

这类失败反而很适合观察 AgenticSeek 的核心机制：它会把执行错误反馈给 LLM，再让模型尝试修复。后面讲 Code Agent 时，我们会专门拆这个循环。

Web UI 和 CLI 怎么选

AgenticSeek 提供 Web UI 和 CLI 两种使用方式。新手建议先用 Web UI，因为它更直观，也更接近产品形态。

CLI 模式有一个非常关键的差异：后端逻辑运行在宿主机，而不是 Docker 容器里。因此.env里的 SearxNG 地址要改成宿主机地址：

SEARXNG_BASE_URL="http://localhost:8080"

而 Web UI 完整模式应该保持：

SEARXNG_BASE_URL="http://searxng:8080"

这两个值看起来只差一个 hostname，但背后是 Docker 网络和宿主机网络的区别。

常见问题排查

1. Web UI 打不开

先检查 frontend 容器是否启动：

dockerps

再确认端口是否被占用：

lsof-i:3000

如果端口被其他进程占用，需要先关闭占用进程，或调整 Docker Compose 配置。

2. 页面显示 Offline

这通常表示前端访问不到 backend。

检查 backend 健康状态：

curlhttp://localhost:7777/health

如果不通，继续看 backend 日志：

dockercompose logs backend

重点关注：

• Provider 初始化是否失败。
• Ollama 是否连接失败。
• config.ini是否解析异常。
• ChromeDriver 或浏览器是否初始化失败。

3. Ollama 连接失败

先在宿主机确认 Ollama 可用：

curlhttp://localhost:11434/api/tags

如果这里失败，说明 Ollama 没有启动，或端口不是默认11434。

再检查config.ini：

provider_name = ollama provider_server_address = 127.0.0.1:11434

如果你把 Ollama 改到了其他端口，需要同步修改provider_server_address和.env里的OLLAMA_PORT。

4. SearxNG 搜索失败

Web UI 完整模式下，.env应该是：

SEARXNG_BASE_URL="http://searxng:8080"

同时宿主机浏览器访问：

http://localhost:8080

如果你修改了SEARXNG_PORT=8001，那么宿主机访问地址变成：

http://localhost:8001

但 backend 容器里的SEARXNG_BASE_URL仍然应该保持：

SEARXNG_BASE_URL="http://searxng:8080"

5. Agent 不按预期执行任务

这类问题不一定是环境错，也可能是模型能力或提示词不够明确。

可以尝试把提示写得更具体：

不要写：

找几个 local agent 项目。

改成：

进行网页搜索，找出 3 个 local agent 开源项目，给出项目名、GitHub 地址和一句话介绍，并保存到工作目录根目录下的 local_agent_projects.txt。

AgenticSeek 当前仍处于早期阶段，明确动作、数量、输出格式和保存路径，会显著提高成功率。

6. ChromeDriver 或浏览器问题

Browser Agent 依赖 Selenium 和 Chrome/ChromeDriver。README 里专门列了 ChromeDriver 相关问题。

如果遇到浏览器初始化失败，可以先确认：

• 本机是否安装了 Chrome。
• Docker 日志里是否有 ChromeDriver 版本不匹配。
• headless_browser是否为True。
• 是否启用了stealth_mode，以及相关依赖是否齐全。

初次体验建议：

headless_browser = True stealth_mode = False

先把基础链路跑通，再尝试更复杂的浏览器设置。

小白最应该记住的配置关系

如果你只想先跑起来，记住下面这张表就够了：

本章小结

这一章我们把 AgenticSeek 的 Web UI 路线跑通思路梳理了一遍：

1. 用 Ollama 在宿主机启动本地模型。
2. 用.env配置 Docker、SearxNG、工作目录和端口。
3. 用config.ini配置模型 Provider、模型名、浏览器和安全模式。
4. 用./start_services.sh full启动 frontend、backend、SearxNG、Redis/Valkey。
5. 通过http://localhost:3000访问 Web UI。
6. 用搜索、写文件、写脚本三个低风险任务验证链路。

到这里，我们已经不只是“看懂 AgenticSeek 是什么”，而是可以亲手体验它的任务执行流程。

下一章会进入源码主线：从 Web UI 输入一句话开始，沿着App.js、api.py、Interaction、Router、Agent.process()追踪一次请求到底经过了哪些对象。那一章会帮你把“跑起来的现象”和“源码里的调用链”对上。