企业官网建设流程全解析

1. 为什么要在 Linux 上跑 OpenHands，还要配 TaoToken

OpenHands 是一个开源的 AI 软件开发代理平台，你可以把它理解成一个“能自己动手写代码、跑命令、改文件”的智能体工作台。它不只是聊天，而是能真正接管一个沙箱环境，帮你完成从读代码、改 bug 到跑测试的完整闭环。适合谁用？适合那些想把 AI 代理接入自己开发流程的后端工程师、DevOps，以及想在自己服务器上长期跑 Agent 任务的团队。

但真在 Linux 服务器上部署时，问题往往不在 OpenHands 本身，而在两件事：一是模型服务怎么接，二是跨网络怎么连。很多人的服务器在机房或云上，本地开发机在另一个网络，浏览器访问 OpenHands 的 Web UI 时经常卡在连接超时或者 WebSocket 握手失败。我试过直接在服务器上裸跑，结果本地浏览器打开一片空白，日志里全是连接被拒。

这篇就围绕这两个痛点来：用 TaoToken 统一 Key/API 通道接入模型服务，省去到处找不同厂商 Key 的麻烦；同时把 OpenHands 的 config.toml 和 settings.json 骨架、远程访问与端口转发配置、连通性验证动作全部给出来。你照着做，能在 Linux 服务器上跑起一个可远程访问、模型调用稳定的 OpenHands 实例。

2. TaoToken 前置准备：统一 Key 与 API 通道

TaoToken 在这里扮演的角色是“模型服务的统一入口”。你不需要在 OpenHands 里分别配置 OpenAI、Anthropic 等不同厂商的地址和 Key，而是通过 TaoToken 拿到一个统一的 API 通道和 Key，OpenHands 只认这一个出口就行。这样跨网络场景下，你只需要保证服务器能访问 TaoToken 的 API 地址，模型侧的事情交给它。

先做两件事。第一，注册并登录 TaoToken 官网，地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，进去之后在控制台创建 API Key。第二，记下 API 基础地址，也就是 https://taotoken.net/api ，注意这个地址后面不加任何 UTM 参数，配置里直接用它。

创建 Key 的入口在控制台的 API Keys 页面，你可以直接访问 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 来生成。生成后复制那串以 sk- 开头的字符串，后面配置里要用。如果你还想先确认模型通道是否正常，可以到模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条测试消息，能正常返回就说明 Key 和通道没问题。

注意：API Key 只显示一次，复制后找个安全的地方存好。服务器上的配置文件权限建议设成 600，别让其他用户读到。

对于长期跑编码任务或 Agent 的场景，可以考虑 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合持续性的代理调用，不用每次担心额度零散。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，配置参数对不上时翻一下这里最快。

3. 可复制配置：config.toml 与 settings.json 骨架

OpenHands 的配置分两层：一层是运行时的 config.toml，控制代理行为、模型参数、沙箱等；另一层是前端/工作区的 settings.json，控制 UI 和连接相关的东西。下面给的是骨架，你按自己环境替换路径和 Key 即可。

先建目录，把配置放整齐：

mkdir -p ~/.openhands cd ~/.openhands

然后是 config.toml，重点是 llm 段落，把模型指向 TaoToken 的 API 地址：

# ~/.openhands/config.toml [core] workspace_base = "/home/youruser/openhands-workspace" cache_dir = "/home/youruser/.openhands/cache" debug = false [llm] model = "gpt-4o" api_key = "sk-你的TaoTokenKey" base_url = "https://taotoken.net/api" max_input_tokens = 128000 max_output_tokens = 8192 temperature = 0.2 timeout = 120 [sandbox] type = "local" timeout = 300 use_host_network = false [security] confirmation_mode = false

这里几个参数说明一下。base_url 必须写成 https://taotoken.net/api ，不要带结尾斜杠，也不要加 UTM。model 填你实际要用的模型名，TaoToken 通道支持多种模型，按文档里的名称填。timeout 建议给到 120 秒以上，跨网络调用时网络抖动很常见，太短会频繁超时。

接着是 settings.json，主要管远程访问和前端连接：

{ "language": "zh-CN", "runtime": "local", "host": "0.0.0.0", "port": 3000, "remote_runtime_api_url": "http://127.0.0.1:3000", "api_key": "sk-你的TaoTokenKey", "base_url": "https://taotoken.net/api", "workspace": "/home/youruser/openhands-workspace", "enable_remote_access": true, "allowed_origins": ["*"] }

host 设成 0.0.0.0 是为了让服务器监听所有网卡，这样你从别的网络才能连上。port 默认 3000，如果被占用就换一个。allowed_origins 在测试阶段可以放开，生产环境建议改成你实际访问的域名或 IP。

提示：两个文件里的 api_key 和 base_url 要保持一致，否则会出现前端能打开但代理调用失败的情况。

4. 远程访问与端口转发配置

配置写好了，接下来解决跨网络连接。分两种情况：一种是你有公网 IP 或云服务器安全组可控，直接放行端口；另一种是服务器在内网，需要做端口转发或隧道。

先看直接放行的情况。以 ufw 为例：

sudo ufw allow 3000/tcp sudo ufw reload sudo ufw status

如果你用的是云服务器，还要在控制台的安全组里放行 3000 端口。这一步很多人漏掉，结果本地怎么连都超时，其实是被安全组挡了。

内网场景下，用 SSH 端口转发是最省事的办法。在你本地开发机上执行：

ssh -N -L 3000:127.0.0.1:3000 youruser@your-server-ip

这条命令把服务器的 3000 端口映射到你本地的 3000。执行后本地浏览器打开 http://127.0.0.1:3000 就能访问服务器上的 OpenHands。好处是不用暴露公网端口，安全性高，适合临时调试。

如果你需要长期从多个设备访问，可以在服务器上跑一个反向代理。用 Nginx 做 WebSocket 转发要注意 upgrade 头：

server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 300s; } }

proxy_read_timeout 给大一点，OpenHands 的代理任务执行时间长，太短会中途断开。改完 Nginx 配置记得 nginx -t 测试再 reload。

5. 验证请求与成功结果

配置和转发都做完，现在验证。先确认 OpenHands 进程起来了：

cd ~/openhands python -m openhands.server & sleep 5 curl -s http://127.0.0.1:3000/health

如果返回类似 {"status":"ok"} 就说明服务正常。接着验证模型通道，直接用 curl 打 TaoToken 的 API：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'

能返回带 choices 的 JSON 就说明 Key 和通道都通。这一步很关键，如果这里失败，OpenHands 里再怎么调都没用，先把这个打通。

最后在浏览器打开 OpenHands 的 Web UI，新建一个任务，比如让它“在当前工作区创建一个 hello.py 并打印 hello”。观察日志里是否有对 https://taotoken.net/api 的请求记录，任务完成后工作区里出现文件，就说明整条链路——远程访问、代理调用、模型服务——全部打通了。

6. 本篇常见错排查

连接超时或 WebSocket 握手失败：先查安全组和 ufw 是否放行端口，再确认 settings.json 里 host 是 0.0.0.0。如果用了 Nginx，检查 Upgrade 和 Connection 头是否配置正确。SSH 转发场景下确认隧道进程还在。

模型调用返回 401 或 403：多半是 api_key 写错或过期。重新到 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 生成一个，替换 config.toml 和 settings.json 里的值。注意 base_url 不要带多余路径。

代理任务跑到一半中断：检查 timeout 和 proxy_read_timeout 是否太小。跨网络调用延迟高，建议 timeout 不低于 120 秒，Nginx 的 proxy_read_timeout 不低于 300 秒。

前端能打开但代理不执行：看 config.toml 里 sandbox 的 type 和 workspace_base 路径是否存在、是否有写权限。路径不存在时代理会静默失败。

端口被占用：用 ss -tlnp | grep 3000 查一下，换端口后记得同步改 settings.json 和转发规则。

排障过程中如果对接入参数不确定，直接翻接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面把 base_url、鉴权头、模型名这些写得比较清楚。需要长期跑编码或 Agent 任务的话，Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 有更细的说明。想先验证模型通道是否正常，模型对话入口 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条消息最快。控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 和用量都在那里看。