IronClaw Reborn CLI 的 Docker 与 Railway 部署实战指南

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文以仓库根目录 Dockerfile 与 docker/reborn/entrypoint.sh 为主线完整讲解 IronClaw RebornAgent OS 的新一代 CLI/WebUI 运行时如何在本地 Docker 与 Railway 平台上构建镜像、配置环境变量、挂载持久卷、启用 SSH 终端与 Slack 扩展。读完本文你将掌握从docker build到 Railway 生产级部署的完整可复制流程并理解入口脚本中每个 fail-closed 校验背后的安全设计意图。一、镜像概览默认命令与端口约定Reborn CLI 的 Docker 镜像是一个多阶段构建的独立 HTTP 服务镜像编译的是启用 WebUI v2 与 Slack host-beta 特性的ironclaw单二进制。镜像入口默认执行ironclaw serve --host ${IRONCLAW_REBORN_SERVE_HOST:-127.0.0.1} --port ${PORT:-3000}PORT由 Railway 这类平台注入公共部署必须显式设置IRONCLAW_REBORN_SERVE_HOST0.0.0.0否则平台健康检查无法到达容器。本地docker run可以保留 loopback 默认值并显式设置IRONCLAW_REBORN_SERVE_PORT3000。从源码看这个显式 host 优先、Railway 自动 0.0.0.0、本地保守 loopback的三级解析逻辑实现在 docker/reborn/entrypoint.sh 的serve-host resolution段落只有显式设置了IRONCLAW_REBORN_SERVE_HOST时它才直接采用否则检测到RAILWAY_ENVIRONMENT/RAILWAY_PROJECT_ID/RAILWAY_SERVICE_ID任一标记就绑定0.0.0.0其余场景回退到127.0.0.1。端口解析为PORT优先、IRONCLAW_REBORN_SERVE_PORT兜底、最终默认3000。Dockerfile中EXPOSE 3000 2222声明了两个容器端口3000是 WebUI/API 监听口2222是可选 SSH 终端口默认不监听见下文 SSH 章节。二、构建镜像在仓库根目录执行docker build -f Dockerfile -t ironclaw-reborn:local .从 Dockerfile 可以看到这是一条完整的多阶段流水线node_toolchainnode:22.23.1-bookworm-slim为前端构建提供 Node/npm/pnpm。railway_clidebian:bookworm-slim按TARGETARCH下载固定版本RAILWAY_CLI_VERSION5.30.4的 Railway CLI并先做sha256sum -c -校验再解压只把railway可执行文件拷入最终镜像不携带任何凭据。chef / planner / deps / builderrust:1.96-bookworm使用cargo-chef做依赖缓存随后cargo build --profile dist --package ironclaw --bin ironclaw编译正式二进制。runtimedebian:bookworm-slim安装ca-certificates、curl、gosu、openssh-server、postgresql-client、sqlite3把构建产物与docker/reborn/下四份配置及两个脚本一起复制进镜像。最终镜像以 root 启动但唯一一次提权降级发生在入口脚本内exec gosu ironclaw。任何绕过入口的方式——docker run --entrypoint、未带--user的docker exec、平台自定义启动命令——都会以 root 运行这是镜像注释明确警告的边界。三、本地运行与环境变量3.1 最小本地环境文件创建一个位于 git 之外的环境文件例如.env.reborn然后启动docker run --rm \ --env-file .env.reborn \ -p 127.0.0.1:3000:3000 \ ironclaw-reborn:local最小本地环境形状IRONCLAW_REBORN_SERVE_HOST127.0.0.1 IRONCLAW_REBORN_SERVE_PORT3000 IRONCLAW_REBORN_PROFILElocal-dev IRONCLAW_REBORN_WEBUI_TOKENrandom-hex-32-bytes-or-longer IRONCLAW_REBORN_WEBUI_USER_IDreborn-cli NEARAI_BASE_URLhttps://cloud-api.near.ai NEARAI_API_KEYnearai-api-key要点IRONCLAW_REBORN_WEBUI_TOKEN至少是 32 字节随机 hexIRONCLAW_REBORN_WEBUI_USER_ID用于固定 WebUI 身份。这两项缺失时ironclaw serve会在绑定 HTTP 监听器之前直接退出属于 fail-closed 设计。捆绑配置默认在[llm.default]选择 NearAI本地docker/reborn/config.toml实际通过环境变量兜底解析 LLM而config.hosted-single-tenant.toml、config.hosted-single-tenant-volume.toml则显式写了provider_id nearai/model deepseek-ai/DeepSeek-V4-Flash/api_key_env NEARAI_API_KEY。因此NEARAI_API_KEY必须设置除非你挂载了选择其他 provider 的自定义配置。更换 provider 或模型的标准做法挂载自定义配置到/opt/ironclaw/并把IRONCLAW_REBORN_DEFAULT_CONFIG指向该路径。首次启动时入口脚本会把该文件复制为$IRONCLAW_REBORN_HOME/config.toml之后的启动会保留已存在的 home 配置详见下文自定义配置种子。3.2 入口脚本的环境解析细节对照 entrypoint.sh 源码几个容易被忽略的细节IRONCLAW_REBORN_HOME/IRONCLAW_REBORN_WORKSPACE_ROOT均不允许等于文件系统根/。原因注释写得很清楚启动阶段 root 会把该路径chown给运行时 uid 1000若接受/就等于把容器整个根文件系统交给非特权用户。未显式设置时IRONCLAW_REBORN_WORKSPACE_ROOT默认是$IRONCLAW_REBORN_HOME/workspace保证项目文件与落地的附件与 Reborn home 在同一持久挂载上。入口脚本支持把$IRONCLAW_REBORN_SERVE_HOST、$PORT、$IRONCLAW_REBORN_SERVE_PORT这类占位符直接写进 Docker command 参数并自行解析——这正是Railway 上把 Start Command 留空也能工作的原因Railway 不会对 Docker 命令参数里的$VAR做 shell 展开而入口脚本自己做了这层替换resolve_env_placeholder_arg函数。若设置了IRONCLAW_REBORN_CONFIRM_HOST_ACCESStrue入口会追加--confirm-host-access参数。该参数对应 serve.rs 的全局开关主要用于local-dev-yolo这类信任宿主机的 profile见下文 profile 说明。四、Google 产品级认证product-auth配置如果部署需要让 Agent 连接一个 Google 凭证例如使用 Google 系工具需要配置 product-auth 专用的 OAuth 重定向IRONCLAW_REBORN_GOOGLE_CLIENT_IDgoogle-client-id IRONCLAW_REBORN_GOOGLE_CLIENT_SECRETgoogle-client-secret IRONCLAW_REBORN_GOOGLE_OAUTH_REDIRECT_URIhttp://127.0.0.1:3000/api/reborn/product-auth/oauth/google/callback关键认知Google product-auth 与 WebUI 的 Google 登录是两套独立流程。product-auth 的 callback 固定走IRONCLAW_REBORN_GOOGLE_OAUTH_REDIRECT_URI显式指定的地址不依赖 WebUI 的 base URL。它在 serve.rs 与 status.rs 中都有对应环境变量引用。仅当部署确实需要连接 Google 凭证时才设置它。五、WebUI Google 登录配置WebUI 的 Google SSO 走另一组变量IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_IDgoogle-client-id IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_SECRETgoogle-client-secret IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINSnear.ai IRONCLAW_REBORN_WEBUI_BASE_URLhttps://public-host在 Google OAuth client 中注册回调https://public-host/auth/callback/google网络边界注意事项普通 Docker bridge 网络下必须把 HTTPS 反代放在容器前面并设置公开 base URL纯http://127.0.0.1的 SSO 只在 Reborn 监听器本身绑定 loopback 时有效例如非 Docker 本地运行或 host-network 运行。IRONCLAW_REBORN_WEBUI_BASE_URL在校验上也有讲究serve_sso.rs 会要求它是合法的 https URL防止HTTP://example.com这类大小写变体绕过检查。Notion MCP 等 product-auth OAuth 流程复用同一个托管 WebUI base URL 作为 provider callback 来源因此IRONCLAW_REBORN_WEBUI_BASE_URL必须指向公开 host让 provider 看到的是公网回调源而不是本地监听地址只有 Google product-auth 是例外它依然显式使用IRONCLAW_REBORN_GOOGLE_OAUTH_REDIRECT_URI。六、Railway 部署6.1 基础形态在 Railway 上把服务的 Dockerfile 路径设为DockerfilePORT由平台注入保持IRONCLAW_REBORN_SERVE_HOST0.0.0.0。Reborn WebUI 服务提供/api/health给 Railway 健康检查。Start Command 必须留空。镜像入口脚本会从PORT与IRONCLAW_REBORN_SERVE_HOST拼出ironclaw serve参数Railway 不会在进入入口脚本之前对 Docker 命令参数里的$VAR占位符做 shell 展开——这正是入口脚本自己实现占位符解析的原因entrypoint.sh 的resolve_env_placeholder_arg。最小 Railway 变量托管单租户 Postgres profileIRONCLAW_REBORN_PROFILEhosted-single-tenant IRONCLAW_REBORN_POSTGRES_URLpostgres-url IRONCLAW_REBORN_SECRET_MASTER_KEYrandom-secret-master-key IRONCLAW_REBORN_WEBUI_TOKENrandom-hex-32-bytes-or-longer IRONCLAW_REBORN_WEBUI_USER_IDreborn-cli NEARAI_API_KEYnearai-api-keyPostgres 连接池有两点实操建议托管 Postgres 提供方如果 session-pool 上限很小应显式设置IRONCLAW_REBORN_POSTGRES_POOL_MAX_SIZE1或2而不是依赖提供方排队超出的会话。配置文件中的默认值为pool_max_size 32见 config.hosted-single-tenant.toml且该环境变量优先于文件。IRONCLAW_REBORN_FILESYSTEM_POSTGRES_MIGRATION_CONNECT_MAX_WAIT_SECS控制健康检查监听器起来之后、运行时装配等待 Postgres 的最长时间默认 5 分钟。6.2 健康检查与滚动部署的配合对hosted-single-tenantironclaw serve会先绑定 WebUI 监听器并服务/api/health再完成 Postgres 后端运行时装配非健康路由在运行时路由就绪前统一返回503。这一设计的意图是让 Railway 先 drain 旧部署、释放 PgBouncer session 模式连接新部署做启动迁移时才有连接可用。6.3 Profile 全景与沙箱化别名镜像内置四份 profile 配置由入口脚本按IRONCLAW_REBORN_PROFILE选择见 entrypoint.sh 的default_config分支profile对应配置文件说明local-dev默认docker/reborn/config.toml本地开发libSQL 本地状态local-dev-yolo同上信任宿主机访问的本地开发变体hosted-single-tenantconfig.hosted-single-tenant.tomlPostgres 托管状态WebUI 先于运行时装配hosted-single-tenant-volumeconfig.hosted-single-tenant-volume.toml挂载卷上的单租户预览libSQL 持久状态hosted-single-tenant-volume-sandboxed同上本地 Docker worker 边界演练 profilehosted-single-tenant-volume-sandboxed-railway同上Railway Sandbox 预览 profileproduction/migration-dry-runconfig.production.toml生产多租户强制要求[storage]与[policy]绝不要把local-dev-yolo用于公共 Railway 监听器该 profile 授予信任宿主机访问权限serve拒绝把它绑定到非 loopback 地址serve.rs 中--confirm-host-access与 host 校验即为此设计。公共单租户预览请用hosted-single-tenant-volume挂载卷 libSQL 持久状态保留 local-dev 产品面或hosted-single-tenantPostgres 托管状态沙箱化别名只适用于文档所描述的本地 Docker 或 Railway 预览运营模型两者都不是生产多副本 profile。volume 沙箱化 profile 有明确的运营意图区分hosted-single-tenant-volume-sandboxed本地 Docker profile用于演练 Docker worker 边界。部署工厂会启用 worker 的默认 Docker 网络--network none只是 ad-hoc 传输的 fail-closed 构造默认。Python worker 需先构建一次docker build -f Dockerfile.sandbox-worker -t ironclaw-worker:latest .。在 Docker Desktop 或 Colima 上IRONCLAW_REBORN_HOME必须位于与 Docker VM 共享的主机路径下macOS 例如/Users/...否则 daemon 无法绑定每用户 workspace。hosted-single-tenant-volume-sandboxed-railwayRailway 预览 profile每条命令在 Railway Sandbox 内的全新内层 Docker worker 中运行部署工厂启用 worker 默认 Docker 网络经外层沙箱的 Railway NAT 直接出网。其生命周期要求详见 Railway Sandbox 运营手册重要提醒Railway 的ISOLATED模式仍有 NAT 出网能力不等价于 Docker--network none不能作为不可信代码的 deny-egress 安全边界。持久化的种子配置记录的是规范化的 volume 应用设置所选 profile 仍是显式的 Rust composition profile因此启动时也会校验匹配的 sandbox process provider 已接线。6.4 持久卷与 fail-closed 行为最小 Railway 变量hosted single-tenant volume profileIRONCLAW_REBORN_PROFILEhosted-single-tenant-volume IRONCLAW_REBORN_WEBUI_TOKENrandom-hex-32-bytes-or-longer IRONCLAW_REBORN_WEBUI_USER_IDreborn-cli NEARAI_API_KEYnearai-api-key挂载 Railway volume 到/data或把IRONCLAW_REBORN_HOME设在RAILWAY_VOLUME_MOUNT_PATH之下。入口脚本在 Railway 暴露 volume 挂载时默认使用$RAILWAY_VOLUME_MOUNT_PATH/ironclaw-reborn作为 home。没有 volume 时使用local-dev、local-dev-yolo、hosted-single-tenant、hosted-single-tenant-volume、hosted-single-tenant-volume-sandboxed或hosted-single-tenant-volume-sandboxed-railway的 Railway 部署会 fail closed除非为一次性测试部署显式设置IRONCLAW_REBORN_ALLOW_EPHEMERAL_RAILWAYtrue。入口脚本的校验还做了路径规范化readlink -m比对防止..段或符号链接绕过挂载前缀检查如果IRONCLAW_REBORN_WORKSPACE_ROOT被覆盖到RAILWAY_VOLUME_MOUNT_PATH之外同样会拒绝启动。状态存储的边界hosted-single-tenant运行时/控制平面状态含扩展安装/激活状态存在 Postgres项目文件、物化的系统扩展包、当前技能文件存储仍在本机文件系统根下。镜像默认 home 是/data/ironclaw-reborn没有 Railway volume 时该路径是临时的。hosted-single-tenant-volume运行时/控制平面状态存在挂载卷上的 Reborn home 内不需要IRONCLAW_REBORN_POSTGRES_URL。入口默认IRONCLAW_REBORN_WORKSPACE_ROOT$IRONCLAW_REBORN_HOME/workspace项目文件与落地附件也落在同一持久挂载上。若本地文件需要在重新部署后存活把IRONCLAW_REBORN_HOME指向挂载卷路径覆盖 workspace root 时也必须指向持久存储。镜像自带sqlite3和psql方便从 Railway shell 做终端检查挂载卷的 libSQL/SQLite 状态用sqlite3IRONCLAW_REBORN_POSTGRES_URL部署用psql。6.5 自定义配置种子与 LLM 环境变量要替代捆绑默认配置把自定义配置挂到/opt/ironclaw/下并设置IRONCLAW_REBORN_DEFAULT_CONFIG指向该路径。首次启动时入口脚本将其复制为$IRONCLAW_REBORN_HOME/config.toml之后启动保留既有 home 配置。入口脚本强制IRONCLAW_REBORN_DEFAULT_CONFIG必须位于/opt/ironclaw/且不得包含..等相对路径段。镜像默认选择 NearAI 为默认 LLM provider所以必须设置NEARAI_API_KEY除非挂载的自定义配置选择了其他 provider。注意 config.toml 有意不内置[llm.default]槽位该槽位只由显式行为写入onboard、config set/models set-provider、WebUI 设置页Railway 环境变量NEARAI_API_KEY等通过 env 兜底解析 LLM。对于老卷中遗留的旧版内置 stub入口脚本会在启动时做一次字节级精确匹配迁移并保留config.toml.pre-llm-migration备份见 entrypoint.sh 的llm_stub_migration_needed逻辑——只有与旧 stub 完全一致的配置才会被剥离任何人工改动过的[llm.default]一律不动。6.6 多域名的 WebUI 登录如果 Railway 为同一服务暴露多个域名选择一个规范域名作为IRONCLAW_REBORN_WEBUI_BASE_URL并在 Google 注册同一个域名IRONCLAW_REBORN_WEBUI_BASE_URLhttps://railway-domain IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_IDgoogle-client-id IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_SECRETgoogle-client-secret IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINSnear.ai IRONCLAW_REBORN_WEBUI_TOKENrandom-hex-32-bytes-or-longer IRONCLAW_REBORN_WEBUI_USER_IDreborn-cli在 Google OAuth client 注册回调https://railway-domain/auth/callback/googleRailway 场景下 product-auth 的 Google 凭证重定向也应指向公网域名IRONCLAW_REBORN_GOOGLE_OAUTH_REDIRECT_URIhttps://railway-domain/api/reborn/product-auth/oauth/google/callback七、SSH 访问镜像自带sshd但默认不启动监听只有设置IRONCLAW_REBORN_SSH_PUBLIC_KEY时入口脚本容器启动时以 root 运行才会把该公钥写为唯一的authorized_keys条目并在降级到ironclaw用户之前于容器端口 2222 启动sshd。不设置该变量就完全没有 SSH 监听器。容器端口 2222 在镜像中EXPOSE了但默认不发布端口——需要显式发布才能到达例如本地docker run -p 2222:2222或托管部署用 Railway TCP proxy。登录是纯公钥方式用户名为agent。生成的sshd_config见 start-sshd.sh设置AllowUsers agent、AuthenticationMethods publickey、PubkeyAuthentication yes、PasswordAuthentication no、KbdInteractiveAuthentication no、PermitEmptyPasswords no、PermitRootLogin no同时禁用 TCP/Agent forwarding、tunnel 与 X11 forwarding——任何账户包括agent都没有密码或 keyboard-interactive 兜底。安全前提必须明确agent不是低权限账户。运行时镜像把它创建为 uid 1000 的非唯一别名与ironclaw运行时用户同 uid见 Dockerfile 中useradd --non-unique --uid 1000。因此 SSH 会话持有完整运行时身份能读写 IronClaw 进程拥有的一切。分发对应私钥的谨慎程度应与授予运行中服务的 shell 权限等同。start-sshd.sh对 SSH 状态目录还有额外防护拒绝非 root 所有的状态目录、拒绝 group/world 可写的目录、拒绝 PEM 头私钥被误粘贴、强制单行 OpenSSH 公钥格式并用ssh-keygen -l -f验证密钥合法性。八、Slack编译进镜像、无开关的扩展8.1 设计要点Slack 路由编译进镜像并无条件挂载没有任何环境变量或config.toml键能启用/禁用某个部署的 Slack因此 Railway 服务变量或挂载配置里无需任何 Slack 专属内容。Slack webhook 在 Slack 扩展的 ingress 签名密钥注册之前统一返回503 temporarily_unavailable。容器运行后打开 WebUI 的/extensions安装 Slack 扩展并完成其设置。Slack app id、bot token、签名密钥、OAuth client 凭证都在容器启动后于那里配置。没有共享频道配置把 bot 邀请进频道即为启用方式bot 以每个参与者本人的身份应答每个用户通过在 Extensions 中完成 Slack OAuth connect 完成配对——没有共享 subject 用户、没有按频道 subject 路由、也没有频道 allowlist 可配置。8.2 被移除的IRONCLAW_REBORN_SLACK_ENABLED没有IRONCLAW_REBORN_SLACK_ENABLED开关——它曾经驱动的 enablement gate 在 #6116 中被删除此后没有任何 Rust 代码读取该变量entrypoint.sh 的 Slack 迁移注释明确记录了这一点并指出旧文档曾指示设置true反而关掉了迁移机制导致容器无法启动见 #7115 修复。也不要在配置里添加[slack]段退役的设置键signing_secret_env、bot_token_env、installation_id、team_id、api_app_id、channel_routes等会让ironclaw serve拒绝启动。8.3 老卷的[slack]段迁移行为#6116 之前种下的卷可能仍携带[slack]段启动行为取决于段内容仅含enabled的段是惰性的可正常启动serve 日志给出 deprecation 提示。入口脚本唯一自动迁移的形态是旧版出厂默认——enabled false紧挨signing_secret_env/bot_token_env启动时这两个字段会被剥离容器正常启动。其他任何包含退役设置键的组合——enabled true旁边带着旧字段、没有显式enabled false行的旧字段、或上列其他设置键——都被刻意保留并拒绝启动报出迁移指引而不是在你眼皮底下把一份看似在用的频道配置悄悄改写。迁移既有配置文件时的通用原则挂载或先前种下的config.toml只要还带着[slack]或[telegram]段就能继续解析除上述唯一迁移形态外残留的 Slack 设置字段会导致启动失败并给出迁移指引而只剩惰性键的段仍能启动并记录 deprecation 提示。最稳妥的做法是直接从挂载文件删除该段——没有任何代码读取它。两个配套纪律按惯例设置 WebUI 身份环境变量不要把 OAuth、Slack 或 LLM 密钥存进config.toml——Slack bot token 与签名密钥通过 WebUI 扩展设置存储。九、运维检查清单部署前后建议对照以下清单可结合 Railway Sandbox 运营手册 的 operator checklist 使用公共监听器确认IRONCLAW_REBORN_SERVE_HOST0.0.0.0本地运行保留 loopback 默认。Railway 服务 Start Command 留空Dockerfile 路径指向仓库根Dockerfile。使用hosted-single-tenant*系列 profile 时确认 volume 已挂载且IRONCLAW_REBORN_HOME/IRONCLAW_REBORN_WORKSPACE_ROOT位于挂载路径内entrypoint 会 fail-closed 校验。IRONCLAW_REBORN_WEBUI_TOKEN、IRONCLAW_REBORN_WEBUI_USER_ID必须齐全否则服务在绑定监听器前退出。未挂载自定义 LLM 配置时确认NEARAI_API_KEY已设置。config.toml中不得存在退役的[slack]设置键不要在配置文件中存放任何密钥。需要 SSH 时设置IRONCLAW_REBORN_SSH_PUBLIC_KEY并显式发布 2222 端口不需要时保持不设置确保无 SSH 监听器。生产多租户场景使用productionprofile强制要求[storage]与[policy]段local-dev-yolo与沙箱化别名仅限其文档化的非生产场景。以上流程与校验行为均以当前仓库 Dockerfile、docker/reborn/entrypoint.sh、docker/reborn/start-sshd.sh、docker/reborn/config*.toml 及 serve.rs 等源码为准可直接对照验证。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐Wasp 部署到 Railway使用 Wasp CLI 一键部署全栈应用实战指南Wasp 部署到 Railway使用 Wasp CLI 一键部署全栈应用实战指南 导读 Railway https://railway.com/ 是一款云开发Web框架后端前端CLI开发工具IronClaw Reborn Railway Sandbox 预览部署运维指南单副本控制服务、Volume 持久状态与沙箱生命周期管理IronClaw Reborn Railway Sandbox 预览部署运维指南单副本控制服务、Volume 持久状态与沙箱生命周期管理 本篇指南围绕仓库内人工智能AI 应用交互助手AI AgentWasp 一键部署到 Railwaywasp deploy railway 完整实战指南Wasp 一键部署到 Railway wasp deploy railway 完整实战指南 Wasp 框架将部署这一全栈工程中最繁琐的环节收进一条命令 waWeb框架后端前端CLI开发工具上一篇终极指南一键合并B站缓存视频完整保留弹幕体验下一篇如何3分钟搞定B站缓存视频合并完整Android操作指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考