企业官网建设流程全解析

Headlong是一个开源的 Agent 微框架（agent microharness），核心仅约 11K 行 Bash，主打"持续心智"（persistent agency）：你的 Agent 会在对话间隙自主思考、自启项目、主动找你汇报。它天然适合接本地大模型——配合Ollama或llama.cpp，无需任何 API Key，推理全部在本地完成，实现零成本与完全私有的 24 小时私人 AI 助理。

为什么 Headlong 适合本地模型 🤔

Headlong 的 Agent 全天候循环思考，如果用云端 API，官方 README 估算按常规配置运行约需 1–2 美元/小时，长期运行成本可观，而且你的每条记忆、轨迹都会经过第三方服务。

本地部署则完全解决这两点：

• 💰零成本：一次下载模型，之后无限推理，不花一分钱 token
• 🔒完全私有：对话内容、Agent 记忆（memories/）、思维轨迹（trajectories/）都不离开你的机器
• 🧩无 Key 门槛：Headlong 内置openai-compatible通用 Provider，只要模型服务器提供 OpenAI 风格的 chat completions 接口（Ollama、llama.cpp、vLLM、LM Studio 都可以），直接对接，无需密钥

相关源码入口：统一模型调用层是 bin/llm，Provider 策略文档见 design/providers.md。

Headlong 如何识别本地模型

Headlong 不会自动探测本地服务（模型名无法可靠推断来源），需要你显式声明 Provider 和地址。核心三个变量：

一次典型的连通性测试（docs/shellm.md 中有更完整的llm工具说明）：

LLM_PROVIDER=openai-compatible \ LLM_API_URL=http://127.0.0.1:11434/v1/chat/completions \ llm -m qwen3:8b "hello"

方案一：用 Ollama 快速起步（推荐新手）🚀

Ollama 一行命令拉模型，是本地推理最省心的起点。

第 1 步：启动服务并下载模型

ollama serve ollama pull qwen3:8b

第 2 步：验证连通性

LLM_PROVIDER=openai-compatible \ LLM_API_URL=http://127.0.0.1:11434/v1/chat/completions \ llm -m qwen3:8b "hello"

Ollama 默认监听11434端口并暴露 OpenAI 兼容接口，Headlong 可直接使用。

方案二：用 llama.cpp 跑 GGUF 模型

想用特定 GGUF 量化模型，llama.cpp 更自由。启动服务器时加上--alias，让别名可以直接当 Headlong 的模型名使用：

llama-server \ -m qwen3-8b-instruct.gguf \ --alias qwen3-8b-instruct \ -c 32768

然后验证（注意 llama.cpp 默认端口是8080）：

LLM_PROVIDER=openai-compatible \ LLM_API_URL=http://127.0.0.1:8080/v1/chat/completions \ llm -m qwen3-8b-instruct "hello"

三步完成 Headlong 本地模型配置

第 1 步：安装 Headlong

从仓库检出安装（安装器不会自动帮你装模型服务器，需先确保 Ollama/llama.cpp 已在运行）：

git clone https://gitcode.com/gh_mirrors/headl/headlong cd headlong ./install.sh --init

安装过程中被问到"模型从哪来"时，选择本地模型服务器，填入http://localhost:11434（Ollama）或http://localhost:8080（llama.cpp）即可。Headlong 会先查询/v1/models拉取模型列表，再实际发起一次 chat completion 校验，确认链路真正可用后 Agent 的心智才会启动。

第 2 步：写入配置

如果已经装好 Headlong，只需在~/.headlong/.env中补充三行（以 Ollama 为例，llama.cpp 把端口改成8080、模型改成qwen3-8b-instruct）：

LLM_PROVIDER='openai-compatible' SHELLM_API_URL='http://127.0.0.1:11434/v1/chat/completions' SHELLM_MODEL='qwen3:8b'

第 3 步：重启 Agent 生效

ada stop ada start

（把ada换成你的 Agent 名字。它既是聊天命令也是管理命令：ada hello发一条消息等回复，ada dash打开仪表盘。）

安装与配置的全部细节（含 CI 非交互安装HEADLONG_PROVIDER=local环境变量方式）见 docs/install.md，本地模型一节在 README.md。

Docker 沙箱下的网络注意点 ⚠️

Headlong 默认把 Agent 生成的 shell 命令放进 Docker 沙箱执行，这带来一个细节：容器内localhost指向容器自身而非宿主机，所以——

• 宿主机安装：.env里保留127.0.0.1即可，shellm只在沙箱内执行命令时自动把地址改写为host.docker.internal
• 整容器安装：直接使用host.docker.internal访问宿主机的模型服务器
• Linux 特别注意：模型服务器必须监听 Docker 可达的地址，例如 llama.cpp 加--host 0.0.0.0，或 Ollama 设置OLLAMA_HOST=0.0.0.0:11434，并用防火墙挡住不可信网络

安全提醒：host.docker.internal会把沙箱代码引向整个宿主机，而不仅仅是模型服务——宿主环回接口上的其他服务（数据库、管理面板等）也可能被触达。host.docker.internal的完整安全分析见 docs/install.md。

常见问题速查

本地配置的完整行为矩阵（URL 归一化、失效端点不落盘、幂等重跑等）都有自动化测试钉住，可参考 tests/test_local_llm_setup.sh。

总结

把 Headlong 接到 Ollama 或 llama.cpp，只需记住四件事：起服务器 → 验连通 → 写三行配置 → 重启 Agent。从此你的 Agent 全天候思考、记忆、干活，token 不花一分，数据一步不出门——这就是开源微框架 + 本地模型的魅力。想深入了解设计哲学，可以继续读 philosophy.md 与 design/providers.md。